1 <?php

     2 // $Id: form.inc,v 1.265.2.25 2009/05/26 08:18:46 goba Exp $

     3 

     4 /**

     5  * @defgroup forms Form builder functions

     6  * @{

     7  * Functions that build an abstract representation of a HTML form.

     8  *

     9  * All modules should declare their form builder functions to be in this

    10  * group and each builder function should reference its validate and submit

    11  * functions using \@see. Conversely, validate and submit functions should

    12  * reference the form builder function using \@see. For examples, of this see

    13  * system_modules_uninstall() or user_pass(), the latter of which has the

    14  * following in its doxygen documentation:

    15  *

    16  * \@ingroup forms

    17  * \@see user_pass_validate().

    18  * \@see user_pass_submit().

    19  *

    20  * @} End of "defgroup forms".

    21  */

    22 

    23 /**

    24  * @defgroup form_api Form generation

    25  * @{

    26  * Functions to enable the processing and display of HTML forms.

    27  *

    28  * Drupal uses these functions to achieve consistency in its form processing and

    29  * presentation, while simplifying code and reducing the amount of HTML that

    30  * must be explicitly generated by modules.

    31  *

    32  * The drupal_get_form() function handles retrieving, processing, and

    33  * displaying a rendered HTML form for modules automatically. For example:

    34  *

    35  * @code

    36  * // Display the user registration form.

    37  * $output = drupal_get_form('user_register');

    38  * @endcode

    39  *

    40  * Forms can also be built and submitted programmatically without any user input

    41  * using the drupal_execute() function.

    42  *

    43  * For information on the format of the structured arrays used to define forms,

    44  * and more detailed explanations of the Form API workflow, see the

    45  * @link http://api.drupal.org/api/file/developer/topics/forms_api_reference.html reference @endlink

    46  * and the @link http://api.drupal.org/api/file/developer/topics/forms_api.html quickstart guide. @endlink

    47  */

    48 

    49 /**

    50  * Retrieves a form from a constructor function, or from the cache if

    51  * the form was built in a previous page-load. The form is then passesed

    52  * on for processing, after and rendered for display if necessary.

    53  *

    54  * @param $form_id

    55  *   The unique string identifying the desired form. If a function

    56  *   with that name exists, it is called to build the form array.

    57  *   Modules that need to generate the same form (or very similar forms)

    58  *   using different $form_ids can implement hook_forms(), which maps

    59  *   different $form_id values to the proper form constructor function. Examples

    60  *   may be found in node_forms(), search_forms(), and user_forms().

    61  * @param ...

    62  *   Any additional arguments are passed on to the functions called by

    63  *   drupal_get_form(), including the unique form constructor function.

    64  *   For example, the node_edit form requires that a node object be passed

    65  *   in here when it is called.

    66  * @return

    67  *   The rendered form.

    68  */

    69 function drupal_get_form($form_id) {

    70   $form_state = array('storage' => NULL, 'submitted' => FALSE);

    71 

    72   $args = func_get_args();

    73   $cacheable = FALSE;

    74 

    75   if (isset($_SESSION['batch_form_state'])) {

    76     // We've been redirected here after a batch processing : the form has

    77     // already been processed, so we grab the post-process $form_state value

    78     // and move on to form display. See _batch_finished() function.

    79     $form_state = $_SESSION['batch_form_state'];

    80     unset($_SESSION['batch_form_state']);

    81   }

    82   else {

    83     // If the incoming $_POST contains a form_build_id, we'll check the

    84     // cache for a copy of the form in question. If it's there, we don't

    85     // have to rebuild the form to proceed. In addition, if there is stored

    86     // form_state data from a previous step, we'll retrieve it so it can

    87     // be passed on to the form processing code.

    88     if (isset($_POST['form_id']) && $_POST['form_id'] == $form_id && !empty($_POST['form_build_id'])) {

    89       $form = form_get_cache($_POST['form_build_id'], $form_state);

    90     }

    91 

    92     // If the previous bit of code didn't result in a populated $form

    93     // object, we're hitting the form for the first time and we need

    94     // to build it from scratch.

    95     if (!isset($form)) {

    96       $form_state['post'] = $_POST;

    97       // Use a copy of the function's arguments for manipulation

    98       $args_temp = $args;

    99       $args_temp[0] = &$form_state;

   100       array_unshift($args_temp, $form_id);

   101 

   102       $form = call_user_func_array('drupal_retrieve_form', $args_temp);

   103       $form_build_id = 'form-'. md5(uniqid(mt_rand(), true));

   104       $form['#build_id'] = $form_build_id;

   105       drupal_prepare_form($form_id, $form, $form_state);

   106       // Store a copy of the unprocessed form for caching and indicate that it

   107       // is cacheable if #cache will be set.

   108       $original_form = $form;

   109       $cacheable = TRUE;

   110       unset($form_state['post']);

   111     }

   112     $form['#post'] = $_POST;

   113 

   114     // Now that we know we have a form, we'll process it (validating,

   115     // submitting, and handling the results returned by its submission

   116     // handlers. Submit handlers accumulate data in the form_state by

   117     // altering the $form_state variable, which is passed into them by

   118     // reference.

   119     drupal_process_form($form_id, $form, $form_state);

   120     if ($cacheable && !empty($form['#cache'])) {

   121       // Caching is done past drupal_process_form so #process callbacks can

   122       // set #cache. By not sending the form state, we avoid storing

   123       // $form_state['storage'].

   124       form_set_cache($form_build_id, $original_form, NULL);

   125     }

   126   }

   127 

   128   // Most simple, single-step forms will be finished by this point --

   129   // drupal_process_form() usually redirects to another page (or to

   130   // a 'fresh' copy of the form) once processing is complete. If one

   131   // of the form's handlers has set $form_state['redirect'] to FALSE,

   132   // the form will simply be re-rendered with the values still in its

   133   // fields.

   134   //

   135   // If $form_state['storage'] or $form_state['rebuild'] have been

   136   // set by any submit or validate handlers, however, we know that

   137   // we're in a complex multi-part process of some sort and the form's

   138   // workflow is NOT complete. We need to construct a fresh copy of

   139   // the form, passing in the latest $form_state in addition to any

   140   // other variables passed into drupal_get_form().

   141 

   142   if (!empty($form_state['rebuild']) || !empty($form_state['storage'])) {

   143     $form = drupal_rebuild_form($form_id, $form_state, $args);

   144   }

   145 

   146   // If we haven't redirected to a new location by now, we want to

   147   // render whatever form array is currently in hand.

   148   return drupal_render_form($form_id, $form);

   149 }

   150 

   151 /**

   152  * Retrieves a form, caches it and processes it with an empty $_POST.

   153  *

   154  * This function clears $_POST and passes the empty $_POST to the form_builder.

   155  * To preserve some parts from $_POST, pass them in $form_state.

   156  *

   157  * If your AHAH callback simulates the pressing of a button, then your AHAH

   158  * callback will need to do the same as what drupal_get_form would do when the

   159  * button is pressed: get the form from the cache, run drupal_process_form over

   160  * it and then if it needs rebuild, run drupal_rebuild_form over it. Then send

   161  * back a part of the returned form.

   162  * $form_state['clicked_button']['#array_parents'] will help you to find which

   163  * part.

   164  *

   165  * @param $form_id

   166  *   The unique string identifying the desired form. If a function

   167  *   with that name exists, it is called to build the form array.

   168  *   Modules that need to generate the same form (or very similar forms)

   169  *   using different $form_ids can implement hook_forms(), which maps

   170  *   different $form_id values to the proper form constructor function. Examples

   171  *   may be found in node_forms(), search_forms(), and user_forms().

   172  * @param $form_state

   173  *   A keyed array containing the current state of the form. Most

   174  *   important is the $form_state['storage'] collection.

   175  * @param $args

   176  *   Any additional arguments are passed on to the functions called by

   177  *   drupal_get_form(), plus the original form_state in the beginning. If you

   178  *   are getting a form from the cache, use $form['#parameters'] to shift off

   179  *   the $form_id from its beginning then the resulting array can be used as

   180  *   $arg here.

   181  * @param $form_build_id

   182  *   If the AHAH callback calling this function only alters part of the form,

   183  *   then pass in the existing form_build_id so we can re-cache with the same

   184  *   csid.

   185  * @return

   186  *   The newly built form.

   187  */

   188 function drupal_rebuild_form($form_id, &$form_state, $args, $form_build_id = NULL) {

   189   // Remove the first argument. This is $form_id.when called from

   190   // drupal_get_form and the original $form_state when called from some AHAH

   191   // callback. Neither is needed. After that, put in the current state.

   192   $args[0] = &$form_state;

   193   // And the form_id.

   194   array_unshift($args, $form_id);

   195   $form = call_user_func_array('drupal_retrieve_form', $args);

   196 

   197   if (!isset($form_build_id)) {

   198     // We need a new build_id for the new version of the form.

   199     $form_build_id = 'form-'. md5(mt_rand());

   200   }

   201   $form['#build_id'] = $form_build_id;

   202   drupal_prepare_form($form_id, $form, $form_state);

   203 

   204   // Now, we cache the form structure so it can be retrieved later for

   205   // validation. If $form_state['storage'] is populated, we'll also cache

   206   // it so that it can be used to resume complex multi-step processes.

   207   form_set_cache($form_build_id, $form, $form_state);

   208 

   209   // Clear out all post data, as we don't want the previous step's

   210   // data to pollute this one and trigger validate/submit handling,

   211   // then process the form for rendering.

   212   $_POST = array();

   213   $form['#post'] = array();

   214   drupal_process_form($form_id, $form, $form_state);

   215   return $form;

   216 }

   217 

   218 /**

   219  * Store a form in the cache.

   220  */

   221 function form_set_cache($form_build_id, $form, $form_state) {

   222   global $user;

   223   // 6 hours cache life time for forms should be plenty.

   224   $expire = 21600;

   225 

   226   if ($user->uid) {

   227     $form['#cache_token'] = drupal_get_token();

   228   }

   229   cache_set('form_'. $form_build_id, $form, 'cache_form', time() + $expire);

   230   if (!empty($form_state['storage'])) {

   231     cache_set('storage_'. $form_build_id, $form_state['storage'], 'cache_form', time() + $expire);

   232   }

   233 }

   234 

   235 /**

   236  * Fetch a form from cache.

   237  */

   238 function form_get_cache($form_build_id, &$form_state) {

   239   global $user;

   240   if ($cached = cache_get('form_'. $form_build_id, 'cache_form')) {

   241     $form = $cached->data;

   242     if ((isset($form['#cache_token']) && drupal_valid_token($form['#cache_token'])) || (!isset($form['#cache_token']) && !$user->uid)) {

   243       if ($cached = cache_get('storage_'. $form_build_id, 'cache_form')) {

   244         $form_state['storage'] = $cached->data;

   245       }

   246       return $form;

   247     }

   248   }

   249 }

   250 

   251 /**

   252  * Retrieves a form using a form_id, populates it with $form_state['values'],

   253  * processes it, and returns any validation errors encountered. This

   254  * function is the programmatic counterpart to drupal_get_form().

   255  *

   256  * @param $form_id

   257  *   The unique string identifying the desired form. If a function

   258  *   with that name exists, it is called to build the form array.

   259  *   Modules that need to generate the same form (or very similar forms)

   260  *   using different $form_ids can implement hook_forms(), which maps

   261  *   different $form_id values to the proper form constructor function. Examples

   262  *   may be found in node_forms(), search_forms(), and user_forms().

   263  * @param $form_state

   264  *   A keyed array containing the current state of the form. Most

   265  *   important is the $form_state['values'] collection, a tree of data

   266  *   used to simulate the incoming $_POST information from a user's

   267  *   form submission.

   268  * @param ...

   269  *   Any additional arguments are passed on to the functions called by

   270  *   drupal_execute(), including the unique form constructor function.

   271  *   For example, the node_edit form requires that a node object be passed

   272  *   in here when it is called.

   273  * For example:

   274  *

   275  * // register a new user

   276  * $form_state = array();

   277  * $form_state['values']['name'] = 'robo-user';

   278  * $form_state['values']['mail'] = 'robouser@example.com';

   279  * $form_state['values']['pass'] = 'password';

   280  * $form_state['values']['op'] = t('Create new account');

   281  * drupal_execute('user_register', $form_state);

   282  *

   283  * // Create a new node

   284  * $form_state = array();

   285  * module_load_include('inc', 'node', 'node.pages');

   286  * $node = array('type' => 'story');

   287  * $form_state['values']['title'] = 'My node';

   288  * $form_state['values']['body'] = 'This is the body text!';

   289  * $form_state['values']['name'] = 'robo-user';

   290  * $form_state['values']['op'] = t('Save');

   291  * drupal_execute('story_node_form', $form_state, (object)$node);

   292  */

   293 function drupal_execute($form_id, &$form_state) {

   294   $args = func_get_args();

   295   $form = call_user_func_array('drupal_retrieve_form', $args);

   296   $form['#post'] = $form_state['values'];

   297   drupal_prepare_form($form_id, $form, $form_state);

   298   drupal_process_form($form_id, $form, $form_state);

   299 }

   300 

   301 /**

   302  * Retrieves the structured array that defines a given form.

   303  *

   304  * @param $form_id

   305  *   The unique string identifying the desired form. If a function

   306  *   with that name exists, it is called to build the form array.

   307  *   Modules that need to generate the same form (or very similar forms)

   308  *   using different $form_ids can implement hook_forms(), which maps

   309  *   different $form_id values to the proper form constructor function.

   310  * @param $form_state

   311  *   A keyed array containing the current state of the form.

   312  * @param ...

   313  *   Any additional arguments needed by the unique form constructor

   314  *   function. Generally, these are any arguments passed into the

   315  *   drupal_get_form() or drupal_execute() functions after the first

   316  *   argument. If a module implements hook_forms(), it can examine

   317  *   these additional arguments and conditionally return different

   318  *   builder functions as well.

   319  */

   320 function drupal_retrieve_form($form_id, &$form_state) {

   321   static $forms;

   322 

   323   // We save two copies of the incoming arguments: one for modules to use

   324   // when mapping form ids to constructor functions, and another to pass to

   325   // the constructor function itself. We shift out the first argument -- the

   326   // $form_id itself -- from the list to pass into the constructor function,

   327   // since it's already known.

   328   $args = func_get_args();

   329   $saved_args = $args;

   330   array_shift($args);

   331   if (isset($form_state)) {

   332     array_shift($args);

   333   }

   334 

   335   // We first check to see if there's a function named after the $form_id.

   336   // If there is, we simply pass the arguments on to it to get the form.

   337   if (!function_exists($form_id)) {

   338     // In cases where many form_ids need to share a central constructor function,

   339     // such as the node editing form, modules can implement hook_forms(). It

   340     // maps one or more form_ids to the correct constructor functions.

   341     //

   342     // We cache the results of that hook to save time, but that only works

   343     // for modules that know all their form_ids in advance. (A module that

   344     // adds a small 'rate this comment' form to each comment in a list

   345     // would need a unique form_id for each one, for example.)

   346     //

   347     // So, we call the hook if $forms isn't yet populated, OR if it doesn't

   348     // yet have an entry for the requested form_id.

   349     if (!isset($forms) || !isset($forms[$form_id])) {

   350       $forms = module_invoke_all('forms', $form_id, $args);

   351     }

   352     $form_definition = $forms[$form_id];

   353     if (isset($form_definition['callback arguments'])) {

   354       $args = array_merge($form_definition['callback arguments'], $args);

   355     }

   356     if (isset($form_definition['callback'])) {

   357       $callback = $form_definition['callback'];

   358     }

   359   }

   360 

   361   array_unshift($args, NULL);

   362   $args[0] = &$form_state;

   363 

   364   // If $callback was returned by a hook_forms() implementation, call it.

   365   // Otherwise, call the function named after the form id.

   366   $form = call_user_func_array(isset($callback) ? $callback : $form_id, $args);

   367 

   368   // We store the original function arguments, rather than the final $arg

   369   // value, so that form_alter functions can see what was originally

   370   // passed to drupal_retrieve_form(). This allows the contents of #parameters

   371   // to be saved and passed in at a later date to recreate the form.

   372   $form['#parameters'] = $saved_args;

   373   return $form;

   374 }

   375 

   376 /**

   377  * This function is the heart of form API. The form gets built, validated and in

   378  * appropriate cases, submitted.

   379  *

   380  * @param $form_id

   381  *   The unique string identifying the current form.

   382  * @param $form

   383  *   An associative array containing the structure of the form.

   384  * @param $form_state

   385  *   A keyed array containing the current state of the form. This

   386  *   includes the current persistent storage data for the form, and

   387  *   any data passed along by earlier steps when displaying a

   388  *   multi-step form. Additional information, like the sanitized $_POST

   389  *   data, is also accumulated here.

   390  */

   391 function drupal_process_form($form_id, &$form, &$form_state) {

   392   $form_state['values'] = array();

   393 

   394   $form = form_builder($form_id, $form, $form_state);

   395   // Only process the form if it is programmed or the form_id coming

   396   // from the POST data is set and matches the current form_id.

   397   if ((!empty($form['#programmed'])) || (!empty($form['#post']) && (isset($form['#post']['form_id']) && ($form['#post']['form_id'] == $form_id)))) {

   398     drupal_validate_form($form_id, $form, $form_state);

   399 

   400     // form_clean_id() maintains a cache of element IDs it has seen,

   401     // so it can prevent duplicates. We want to be sure we reset that

   402     // cache when a form is processed, so scenerios that result in

   403     // the form being built behind the scenes and again for the

   404     // browser don't increment all the element IDs needlessly.

   405     form_clean_id(NULL, TRUE);

   406 

   407     if ((!empty($form_state['submitted'])) && !form_get_errors() && empty($form_state['rebuild'])) {

   408       $form_state['redirect'] = NULL;

   409       form_execute_handlers('submit', $form, $form_state);

   410 

   411       // We'll clear out the cached copies of the form and its stored data

   412       // here, as we've finished with them. The in-memory copies are still

   413       // here, though.

   414       if (variable_get('cache', CACHE_DISABLED) == CACHE_DISABLED && !empty($form_state['values']['form_build_id'])) {

   415         cache_clear_all('form_'. $form_state['values']['form_build_id'], 'cache_form');

   416         cache_clear_all('storage_'. $form_state['values']['form_build_id'], 'cache_form');

   417       }

   418 

   419       // If batches were set in the submit handlers, we process them now,

   420       // possibly ending execution. We make sure we do not react to the batch

   421       // that is already being processed (if a batch operation performs a

   422       // drupal_execute).

   423       if ($batch =& batch_get() && !isset($batch['current_set'])) {

   424         // The batch uses its own copies of $form and $form_state for

   425         // late execution of submit handers and post-batch redirection.

   426         $batch['form'] = $form;

   427         $batch['form_state'] = $form_state;

   428         $batch['progressive'] = !$form['#programmed'];

   429         batch_process();

   430         // Execution continues only for programmatic forms.

   431         // For 'regular' forms, we get redirected to the batch processing

   432         // page. Form redirection will be handled in _batch_finished(),

   433         // after the batch is processed.

   434       }

   435 

   436       // If no submit handlers have populated the $form_state['storage']

   437       // bundle, and the $form_state['rebuild'] flag has not been set,

   438       // we're finished and should redirect to a new destination page

   439       // if one has been set (and a fresh, unpopulated copy of the form

   440       // if one hasn't). If the form was called by drupal_execute(),

   441       // however, we'll skip this and let the calling function examine

   442       // the resulting $form_state bundle itself.

   443       if (!$form['#programmed'] && empty($form_state['rebuild']) && empty($form_state['storage'])) {

   444         drupal_redirect_form($form, $form_state['redirect']);

   445       }

   446     }

   447   }

   448 }

   449 

   450 /**

   451  * Prepares a structured form array by adding required elements,

   452  * executing any hook_form_alter functions, and optionally inserting

   453  * a validation token to prevent tampering.

   454  *

   455  * @param $form_id

   456  *   A unique string identifying the form for validation, submission,

   457  *   theming, and hook_form_alter functions.

   458  * @param $form

   459  *   An associative array containing the structure of the form.

   460  * @param $form_state

   461  *   A keyed array containing the current state of the form. Passed

   462  *   in here so that hook_form_alter() calls can use it, as well.

   463  */

   464 function drupal_prepare_form($form_id, &$form, &$form_state) {

   465   global $user;

   466 

   467   $form['#type'] = 'form';

   468   $form['#programmed'] = isset($form['#post']);

   469 

   470   if (isset($form['#build_id'])) {

   471     $form['form_build_id'] = array(

   472       '#type' => 'hidden',

   473       '#value' => $form['#build_id'],

   474       '#id' => $form['#build_id'],

   475       '#name' => 'form_build_id',

   476     );

   477   }

   478 

   479   // Add a token, based on either #token or form_id, to any form displayed to

   480   // authenticated users. This ensures that any submitted form was actually

   481   // requested previously by the user and protects against cross site request

   482   // forgeries.

   483   if (isset($form['#token'])) {

   484     if ($form['#token'] === FALSE || $user->uid == 0 || $form['#programmed']) {

   485       unset($form['#token']);

   486     }

   487     else {

   488       $form['form_token'] = array('#type' => 'token', '#default_value' => drupal_get_token($form['#token']));

   489     }

   490   }

   491   else if (isset($user->uid) && $user->uid && !$form['#programmed']) {

   492     $form['#token'] = $form_id;

   493     $form['form_token'] = array(

   494       '#id' => form_clean_id('edit-'. $form_id .'-form-token'),

   495       '#type' => 'token',

   496       '#default_value' => drupal_get_token($form['#token']),

   497     );

   498   }

   499 

   500   if (isset($form_id)) {

   501     $form['form_id'] = array(

   502       '#type' => 'hidden',

   503       '#value' => $form_id,

   504       '#id' => form_clean_id("edit-$form_id"),

   505     );

   506   }

   507   if (!isset($form['#id'])) {

   508     $form['#id'] = form_clean_id($form_id);

   509   }

   510 

   511   $form += _element_info('form');

   512 

   513   if (!isset($form['#validate'])) {

   514     if (function_exists($form_id .'_validate')) {

   515       $form['#validate'] = array($form_id .'_validate');

   516     }

   517   }

   518 

   519   if (!isset($form['#submit'])) {

   520     if (function_exists($form_id .'_submit')) {

   521       // We set submit here so that it can be altered.

   522       $form['#submit'] = array($form_id .'_submit');

   523     }

   524   }

   525 

   526   // Normally, we would call drupal_alter($form_id, $form, $form_state).

   527   // However, drupal_alter() normally supports just one byref parameter. Using

   528   // the __drupal_alter_by_ref key, we can store any additional parameters

   529   // that need to be altered, and they'll be split out into additional params

   530   // for the hook_form_alter() implementations.

   531   // @todo: Remove this in Drupal 7.

   532   $data = &$form;

   533   $data['__drupal_alter_by_ref'] = array(&$form_state);

   534   drupal_alter('form_'. $form_id, $data);

   535 

   536   // __drupal_alter_by_ref is unset in the drupal_alter() function, we need

   537   // to repopulate it to ensure both calls get the data.

   538   $data['__drupal_alter_by_ref'] = array(&$form_state);

   539   drupal_alter('form', $data, $form_id);

   540 }

   541 

   542 

   543 /**

   544  * Validates user-submitted form data from the $form_state using

   545  * the validate functions defined in a structured form array.

   546  *

   547  * @param $form_id

   548  *   A unique string identifying the form for validation, submission,

   549  *   theming, and hook_form_alter functions.

   550  * @param $form

   551  *   An associative array containing the structure of the form.

   552  * @param $form_state

   553  *   A keyed array containing the current state of the form. The current

   554  *   user-submitted data is stored in $form_state['values'], though

   555  *   form validation functions are passed an explicit copy of the

   556  *   values for the sake of simplicity. Validation handlers can also

   557  *   $form_state to pass information on to submit handlers. For example:

   558  *     $form_state['data_for_submision'] = $data;

   559  *   This technique is useful when validation requires file parsing,

   560  *   web service requests, or other expensive requests that should

   561  *   not be repeated in the submission step.

   562  */

   563 function drupal_validate_form($form_id, $form, &$form_state) {

   564   static $validated_forms = array();

   565 

   566   if (isset($validated_forms[$form_id])) {

   567     return;

   568   }

   569 

   570   // If the session token was set by drupal_prepare_form(), ensure that it

   571   // matches the current user's session.

   572   if (isset($form['#token'])) {

   573     if (!drupal_valid_token($form_state['values']['form_token'], $form['#token'])) {

   574       // Setting this error will cause the form to fail validation.

   575       form_set_error('form_token', t('Validation error, please try again. If this error persists, please contact the site administrator.'));

   576     }

   577   }

   578 

   579   _form_validate($form, $form_state, $form_id);

   580   $validated_forms[$form_id] = TRUE;

   581 }

   582 

   583 /**

   584  * Renders a structured form array into themed HTML.

   585  *

   586  * @param $form_id

   587  *   A unique string identifying the form for validation, submission,

   588  *   theming, and hook_form_alter functions.

   589  * @param $form

   590  *   An associative array containing the structure of the form.

   591  * @return

   592  *   A string containing the themed HTML.

   593  */

   594 function drupal_render_form($form_id, &$form) {

   595   // Don't override #theme if someone already set it.

   596   if (!isset($form['#theme'])) {

   597     init_theme();

   598     $registry = theme_get_registry();

   599     if (isset($registry[$form_id])) {

   600       $form['#theme'] = $form_id;

   601     }

   602   }

   603 

   604   $output = drupal_render($form);

   605   return $output;

   606 }

   607 

   608 /**

   609  * Redirect the user to a URL after a form has been processed.

   610  *

   611  * @param $form

   612  *   An associative array containing the structure of the form.

   613  * @param $redirect

   614  *   An optional value containing the destination path to redirect

   615  *   to if none is specified by the form.

   616  */

   617 function drupal_redirect_form($form, $redirect = NULL) {

   618   $goto = NULL;

   619   if (isset($redirect)) {

   620     $goto = $redirect;

   621   }

   622   if ($goto !== FALSE && isset($form['#redirect'])) {

   623     $goto = $form['#redirect'];

   624   }

   625   if (!isset($goto) || ($goto !== FALSE)) {

   626     if (isset($goto)) {

   627       if (is_array($goto)) {

   628         call_user_func_array('drupal_goto', $goto);

   629       }

   630       else {

   631         drupal_goto($goto);

   632       }

   633     }

   634     drupal_goto($_GET['q']);

   635   }

   636 }

   637 

   638 /**

   639  * Performs validation on form elements. First ensures required fields are

   640  * completed, #maxlength is not exceeded, and selected options were in the

   641  * list of options given to the user. Then calls user-defined validators.

   642  *

   643  * @param $elements

   644  *   An associative array containing the structure of the form.

   645  * @param $form_state

   646  *   A keyed array containing the current state of the form. The current

   647  *   user-submitted data is stored in $form_state['values'], though

   648  *   form validation functions are passed an explicit copy of the

   649  *   values for the sake of simplicity. Validation handlers can also

   650  *   $form_state to pass information on to submit handlers. For example:

   651  *     $form_state['data_for_submision'] = $data;

   652  *   This technique is useful when validation requires file parsing,

   653  *   web service requests, or other expensive requests that should

   654  *   not be repeated in the submission step.

   655  * @param $form_id

   656  *   A unique string identifying the form for validation, submission,

   657  *   theming, and hook_form_alter functions.

   658  */

   659 function _form_validate($elements, &$form_state, $form_id = NULL) {

   660   static $complete_form;

   661 

   662   // Also used in the installer, pre-database setup.

   663   $t = get_t();

   664 

   665   // Recurse through all children.

   666   foreach (element_children($elements) as $key) {

   667     if (isset($elements[$key]) && $elements[$key]) {

   668       _form_validate($elements[$key], $form_state);

   669     }

   670   }

   671   // Validate the current input.

   672   if (!isset($elements['#validated']) || !$elements['#validated']) {

   673     if (isset($elements['#needs_validation'])) {

   674       // Make sure a value is passed when the field is required.

   675       // A simple call to empty() will not cut it here as some fields, like

   676       // checkboxes, can return a valid value of '0'. Instead, check the

   677       // length if it's a string, and the item count if it's an array.

   678       if ($elements['#required'] && (!count($elements['#value']) || (is_string($elements['#value']) && strlen(trim($elements['#value'])) == 0))) {

   679         form_error($elements, $t('!name field is required.', array('!name' => $elements['#title'])));

   680       }

   681 

   682       // Verify that the value is not longer than #maxlength.

   683       if (isset($elements['#maxlength']) && drupal_strlen($elements['#value']) > $elements['#maxlength']) {

   684         form_error($elements, $t('!name cannot be longer than %max characters but is currently %length characters long.', array('!name' => empty($elements['#title']) ? $elements['#parents'][0] : $elements['#title'], '%max' => $elements['#maxlength'], '%length' => drupal_strlen($elements['#value']))));

   685       }

   686 

   687       if (isset($elements['#options']) && isset($elements['#value'])) {

   688         if ($elements['#type'] == 'select') {

   689           $options = form_options_flatten($elements['#options']);

   690         }

   691         else {

   692           $options = $elements['#options'];

   693         }

   694         if (is_array($elements['#value'])) {

   695           $value = $elements['#type'] == 'checkboxes' ? array_keys(array_filter($elements['#value'])) : $elements['#value'];

   696           foreach ($value as $v) {

   697             if (!isset($options[$v])) {

   698               form_error($elements, $t('An illegal choice has been detected. Please contact the site administrator.'));

   699               watchdog('form', 'Illegal choice %choice in !name element.', array('%choice' => $v, '!name' => empty($elements['#title']) ? $elements['#parents'][0] : $elements['#title']), WATCHDOG_ERROR);

   700             }

   701           }

   702         }

   703         elseif (!isset($options[$elements['#value']])) {

   704           form_error($elements, $t('An illegal choice has been detected. Please contact the site administrator.'));

   705           watchdog('form', 'Illegal choice %choice in %name element.', array('%choice' => $elements['#value'], '%name' => empty($elements['#title']) ? $elements['#parents'][0] : $elements['#title']), WATCHDOG_ERROR);

   706         }

   707       }

   708     }

   709 

   710     // Call user-defined form level validators and store a copy of the full

   711     // form so that element-specific validators can examine the entire structure

   712     // if necessary.

   713     if (isset($form_id)) {

   714       form_execute_handlers('validate', $elements, $form_state);

   715       $complete_form = $elements;

   716     }

   717     // Call any element-specific validators. These must act on the element

   718     // #value data.

   719     elseif (isset($elements['#element_validate'])) {

   720       foreach ($elements['#element_validate'] as $function) {

   721         if (function_exists($function))  {

   722           $function($elements, $form_state, $complete_form);

   723         }

   724       }

   725     }

   726     $elements['#validated'] = TRUE;

   727   }

   728 }

   729 

   730 /**

   731  * A helper function used to execute custom validation and submission

   732  * handlers for a given form. Button-specific handlers are checked

   733  * first. If none exist, the function falls back to form-level handlers.

   734  *

   735  * @param $type

   736  *   The type of handler to execute. 'validate' or 'submit' are the

   737  *   defaults used by Form API.

   738  * @param $form

   739  *   An associative array containing the structure of the form.

   740  * @param $form_state

   741  *   A keyed array containing the current state of the form. If the user

   742  *   submitted the form by clicking a button with custom handler functions

   743  *   defined, those handlers will be stored here.

   744  */

   745 function form_execute_handlers($type, &$form, &$form_state) {

   746   $return = FALSE;

   747   if (isset($form_state[$type .'_handlers'])) {

   748     $handlers = $form_state[$type .'_handlers'];

   749   }

   750   elseif (isset($form['#'. $type])) {

   751     $handlers = $form['#'. $type];

   752   }

   753   else {

   754     $handlers = array();

   755   }

   756 

   757   foreach ($handlers as $function) {

   758     if (function_exists($function))  {

   759       // Check to see if a previous _submit handler has set a batch, but 

   760       // make sure we do not react to a batch that is already being processed 

   761       // (for instance if a batch operation performs a drupal_execute()).

   762       if ($type == 'submit' && ($batch =& batch_get()) && !isset($batch['current_set'])) {

   763         // Some previous _submit handler has set a batch. We store the call

   764         // in a special 'control' batch set, for execution at the correct

   765         // time during the batch processing workflow.

   766         $batch['sets'][] = array('form_submit' => $function);

   767       }

   768       else {

   769         $function($form, $form_state);

   770       }

   771       $return = TRUE;

   772     }

   773   }

   774   return $return;

   775 }

   776 

   777 /**

   778  * File an error against a form element.

   779  *

   780  * @param $name

   781  *   The name of the form element. If the #parents property of your form

   782  *   element is array('foo', 'bar', 'baz') then you may set an error on 'foo'

   783  *   or 'foo][bar][baz'. Setting an error on 'foo' sets an error for every

   784  *   element where the #parents array starts with 'foo'.

   785  * @param $message

   786  *   The error message to present to the user.

   787  * @param $reset

   788  *   Reset the form errors static cache.

   789  * @return

   790  *   Never use the return value of this function, use form_get_errors and

   791  *   form_get_error instead.

   792  */

   793 function form_set_error($name = NULL, $message = '', $reset = FALSE) {

   794   static $form = array();

   795   if ($reset) {

   796     $form = array();

   797   }

   798   if (isset($name) && !isset($form[$name])) {

   799     $form[$name] = $message;

   800     if ($message) {

   801       drupal_set_message($message, 'error');

   802     }

   803   }

   804   return $form;

   805 }

   806 

   807 /**

   808  * Return an associative array of all errors.

   809  */

   810 function form_get_errors() {

   811   $form = form_set_error();

   812   if (!empty($form)) {

   813     return $form;

   814   }

   815 }

   816 

   817 /**

   818  * Return the error message filed against the form with the specified name.

   819  */

   820 function form_get_error($element) {

   821   $form = form_set_error();

   822   $key = $element['#parents'][0];

   823   if (isset($form[$key])) {

   824     return $form[$key];

   825   }

   826   $key = implode('][', $element['#parents']);

   827   if (isset($form[$key])) {

   828     return $form[$key];

   829   }

   830 }

   831 

   832 /**

   833  * Flag an element as having an error.

   834  */

   835 function form_error(&$element, $message = '') {

   836   form_set_error(implode('][', $element['#parents']), $message);

   837 }

   838 

   839 /**

   840  * Walk through the structured form array, adding any required

   841  * properties to each element and mapping the incoming $_POST

   842  * data to the proper elements.

   843  *

   844  * @param $form_id

   845  *   A unique string identifying the form for validation, submission,

   846  *   theming, and hook_form_alter functions.

   847  * @param $form

   848  *   An associative array containing the structure of the form.

   849  * @param $form_state

   850  *   A keyed array containing the current state of the form. In this

   851  *   context, it is used to accumulate information about which button

   852  *   was clicked when the form was submitted, as well as the sanitized

   853  *   $_POST data.

   854  */

   855 function form_builder($form_id, $form, &$form_state) {

   856   static $complete_form, $cache;

   857 

   858   // Initialize as unprocessed.

   859   $form['#processed'] = FALSE;

   860 

   861   // Use element defaults.

   862   if ((!empty($form['#type'])) && ($info = _element_info($form['#type']))) {

   863     // Overlay $info onto $form, retaining preexisting keys in $form.

   864     $form += $info;

   865   }

   866 

   867   if (isset($form['#type']) && $form['#type'] == 'form') {

   868     $cache = NULL;

   869     $complete_form = $form;

   870     if (!empty($form['#programmed'])) {

   871       $form_state['submitted'] = TRUE;

   872     }

   873   }

   874 

   875   if (isset($form['#input']) && $form['#input']) {

   876     _form_builder_handle_input_element($form_id, $form, $form_state, $complete_form);

   877   }

   878   $form['#defaults_loaded'] = TRUE;

   879 

   880   // We start off assuming all form elements are in the correct order.

   881   $form['#sorted'] = TRUE;

   882 

   883   // Recurse through all child elements.

   884   $count = 0;

   885   foreach (element_children($form) as $key) {

   886     $form[$key]['#post'] = $form['#post'];

   887     $form[$key]['#programmed'] = $form['#programmed'];

   888     // Don't squash an existing tree value.

   889     if (!isset($form[$key]['#tree'])) {

   890       $form[$key]['#tree'] = $form['#tree'];

   891     }

   892 

   893     // Deny access to child elements if parent is denied.

   894     if (isset($form['#access']) && !$form['#access']) {

   895       $form[$key]['#access'] = FALSE;

   896     }

   897 

   898     // Don't squash existing parents value.

   899     if (!isset($form[$key]['#parents'])) {

   900       // Check to see if a tree of child elements is present. If so,

   901       // continue down the tree if required.

   902       $form[$key]['#parents'] = $form[$key]['#tree'] && $form['#tree'] ? array_merge($form['#parents'], array($key)) : array($key);

   903       $array_parents = isset($form['#array_parents']) ? $form['#array_parents'] : array();

   904       $array_parents[] = $key;

   905       $form[$key]['#array_parents'] = $array_parents;

   906     }

   907 

   908     // Assign a decimal placeholder weight to preserve original array order.

   909     if (!isset($form[$key]['#weight'])) {

   910       $form[$key]['#weight'] = $count/1000;

   911     }

   912     else {

   913       // If one of the child elements has a weight then we will need to sort

   914       // later.

   915       unset($form['#sorted']);

   916     }

   917     $form[$key] = form_builder($form_id, $form[$key], $form_state);

   918     $count++;

   919   }

   920 

   921   // The #after_build flag allows any piece of a form to be altered

   922   // after normal input parsing has been completed.

   923   if (isset($form['#after_build']) && !isset($form['#after_build_done'])) {

   924     foreach ($form['#after_build'] as $function) {

   925       $form = $function($form, $form_state);

   926       $form['#after_build_done'] = TRUE;

   927     }

   928   }

   929 

   930   // Now that we've processed everything, we can go back to handle the funky

   931   // Internet Explorer button-click scenario.

   932   _form_builder_ie_cleanup($form, $form_state);

   933 

   934   // We shoud keep the buttons array until the IE clean up function

   935   // has recognized the submit button so the form has been marked

   936   // as submitted. If we already know which button was submitted,

   937   // we don't need the array.

   938   if (!empty($form_state['submitted'])) {

   939     unset($form_state['buttons']);

   940   }

   941 

   942   // If some callback set #cache, we need to flip a static flag so later it

   943   // can be found.

   944   if (!empty($form['#cache'])) {

   945     $cache = $form['#cache'];

   946   }

   947   // We are on the top form, we can copy back #cache if it's set.

   948   if (isset($form['#type']) && $form['#type'] == 'form' && isset($cache)) {

   949     $form['#cache'] = TRUE;

   950   }

   951   return $form;

   952 }

   953 

   954 /**

   955  * Populate the #value and #name properties of input elements so they

   956  * can be processed and rendered. Also, execute any #process handlers

   957  * attached to a specific element.

   958  */

   959 function _form_builder_handle_input_element($form_id, &$form, &$form_state, $complete_form) {

   960   if (!isset($form['#name'])) {

   961     $name = array_shift($form['#parents']);

   962     $form['#name'] = $name;

   963     if ($form['#type'] == 'file') {

   964       // To make it easier to handle $_FILES in file.inc, we place all

   965       // file fields in the 'files' array. Also, we do not support

   966       // nested file names.

   967       $form['#name'] = 'files['. $form['#name'] .']';

   968     }

   969     elseif (count($form['#parents'])) {

   970       $form['#name'] .= '['. implode('][', $form['#parents']) .']';

   971     }

   972     array_unshift($form['#parents'], $name);

   973   }

   974   if (!isset($form['#id'])) {

   975     $form['#id'] = form_clean_id('edit-'. implode('-', $form['#parents']));

   976   }

   977 

   978   if (!empty($form['#disabled'])) {

   979     $form['#attributes']['disabled'] = 'disabled';

   980   }

   981 

   982   if (!isset($form['#value']) && !array_key_exists('#value', $form)) {

   983     $function = !empty($form['#value_callback']) ? $form['#value_callback'] : 'form_type_'. $form['#type'] .'_value';

   984     if (($form['#programmed']) || ((!isset($form['#access']) || $form['#access']) && isset($form['#post']) && (isset($form['#post']['form_id']) && $form['#post']['form_id'] == $form_id))) {

   985       $edit = $form['#post'];

   986       foreach ($form['#parents'] as $parent) {

   987         $edit = isset($edit[$parent]) ? $edit[$parent] : NULL;

   988       }

   989       if (!$form['#programmed'] || isset($edit)) {

   990         // Call #type_value to set the form value;

   991         if (function_exists($function)) {

   992           $form['#value'] = $function($form, $edit);

   993         }

   994         if (!isset($form['#value']) && isset($edit)) {

   995           $form['#value'] = $edit;

   996         }

   997       }

   998       // Mark all posted values for validation.

   999       if (isset($form['#value']) || (isset($form['#required']) && $form['#required'])) {

  1000         $form['#needs_validation'] = TRUE;

  1001       }

  1002     }

  1003     // Load defaults.

  1004     if (!isset($form['#value'])) {

  1005       // Call #type_value without a second argument to request default_value handling.

  1006       if (function_exists($function)) {

  1007         $form['#value'] = $function($form);

  1008       }

  1009       // Final catch. If we haven't set a value yet, use the explicit default value.

  1010       // Avoid image buttons (which come with garbage value), so we only get value

  1011       // for the button actually clicked.

  1012       if (!isset($form['#value']) && empty($form['#has_garbage_value'])) {

  1013         $form['#value'] = isset($form['#default_value']) ? $form['#default_value'] : '';

  1014       }

  1015     }

  1016   }

  1017 

  1018   // Determine which button (if any) was clicked to submit the form.

  1019   // We compare the incoming values with the buttons defined in the form,

  1020   // and flag the one that matches. We have to do some funky tricks to

  1021   // deal with Internet Explorer's handling of single-button forms, though.

  1022   if (!empty($form['#post']) && isset($form['#executes_submit_callback'])) {

  1023     // First, accumulate a collection of buttons, divided into two bins:

  1024     // those that execute full submit callbacks and those that only validate.

  1025     $button_type = $form['#executes_submit_callback'] ? 'submit' : 'button';

  1026     $form_state['buttons'][$button_type][] = $form;

  1027 

  1028     if (_form_button_was_clicked($form)) {

  1029       $form_state['submitted'] = $form_state['submitted'] || $form['#executes_submit_callback'];

  1030 

  1031       // In most cases, we want to use form_set_value() to manipulate

  1032       // the global variables. In this special case, we want to make sure that

  1033       // the value of this element is listed in $form_variables under 'op'.

  1034       $form_state['values'][$form['#name']] = $form['#value'];

  1035       $form_state['clicked_button'] = $form;

  1036 

  1037       if (isset($form['#validate'])) {

  1038         $form_state['validate_handlers'] = $form['#validate'];

  1039       }

  1040       if (isset($form['#submit'])) {

  1041         $form_state['submit_handlers'] = $form['#submit'];

  1042       }

  1043     }

  1044   }

  1045   // Allow for elements to expand to multiple elements, e.g., radios,

  1046   // checkboxes and files.

  1047   if (isset($form['#process']) && !$form['#processed']) {

  1048     foreach ($form['#process'] as $process) {

  1049       if (function_exists($process)) {

  1050         $form = $process($form, isset($edit) ? $edit : NULL, $form_state, $complete_form);

  1051       }

  1052     }

  1053     $form['#processed'] = TRUE;

  1054   }

  1055   form_set_value($form, $form['#value'], $form_state);

  1056 }

  1057 

  1058 /**

  1059  * Helper function to handle the sometimes-convoluted logic of button

  1060  * click detection.

  1061  *

  1062  * In Internet Explorer, if ONLY one submit button is present, AND the

  1063  * enter key is used to submit the form, no form value is sent for it

  1064  * and we'll never detect a match. That special case is handled by

  1065  * _form_builder_ie_cleanup().

  1066  */

  1067 function _form_button_was_clicked($form) {

  1068   // First detect normal 'vanilla' button clicks. Traditionally, all

  1069   // standard buttons on a form share the same name (usually 'op'),

  1070   // and the specific return value is used to determine which was

  1071   // clicked. This ONLY works as long as $form['#name'] puts the

  1072   // value at the top level of the tree of $_POST data.

  1073   if (isset($form['#post'][$form['#name']]) && $form['#post'][$form['#name']] == $form['#value']) {

  1074     return TRUE;

  1075   }

  1076   // When image buttons are clicked, browsers do NOT pass the form element

  1077   // value in $_POST. Instead they pass an integer representing the

  1078   // coordinates of the click on the button image. This means that image

  1079   // buttons MUST have unique $form['#name'] values, but the details of

  1080   // their $_POST data should be ignored.

  1081   elseif (!empty($form['#has_garbage_value']) && isset($form['#value']) && $form['#value'] !== '') {

  1082     return TRUE;

  1083   }

  1084   return FALSE;

  1085 }

  1086 

  1087 /**

  1088  * In IE, if only one submit button is present, AND the enter key is

  1089  * used to submit the form, no form value is sent for it and our normal

  1090  * button detection code will never detect a match. We call this

  1091  * function after all other button-detection is complete to check

  1092  * for the proper conditions, and treat the single button on the form

  1093  * as 'clicked' if they are met.

  1094  */

  1095 function _form_builder_ie_cleanup($form, &$form_state) {

  1096   // Quick check to make sure we're always looking at the full form

  1097   // and not a sub-element.

  1098   if (!empty($form['#type']) && $form['#type'] == 'form') {

  1099     // If we haven't recognized a submission yet, and there's a single

  1100     // submit button, we know that we've hit the right conditions. Grab

  1101     // the first one and treat it as the clicked button.

  1102     if (empty($form_state['submitted']) && !empty($form_state['buttons']['submit']) && empty($form_state['buttons']['button'])) {

  1103       $button = $form_state['buttons']['submit'][0];

  1104 

  1105       // Set up all the $form_state information that would have been

  1106       // populated had the button been recognized earlier.

  1107       $form_state['submitted'] = TRUE;

  1108       $form_state['submit_handlers'] = empty($button['#submit']) ? NULL : $button['#submit'];

  1109       $form_state['validate_handlers'] = empty($button['#validate']) ? NULL : $button['#validate'];

  1110       $form_state['values'][$button['#name']] = $button['#value'];

  1111       $form_state['clicked_button'] = $button;

  1112     }

  1113   }

  1114 }

  1115 

  1116 /**

  1117  * Helper function to determine the value for an image button form element.

  1118  *

  1119  * @param $form

  1120  *   The form element whose value is being populated.

  1121  * @param $edit

  1122  *   The incoming POST data to populate the form element. If this is FALSE,

  1123  *   the element's default value should be returned.

  1124  * @return

  1125  *   The data that will appear in the $form_state['values'] collection

  1126  *   for this element. Return nothing to use the default.

  1127  */

  1128 function form_type_image_button_value($form, $edit = FALSE) {

  1129   if ($edit !== FALSE) {

  1130     if (!empty($edit)) {

  1131       // If we're dealing with Mozilla or Opera, we're lucky. It will

  1132       // return a proper value, and we can get on with things.

  1133       return $form['#return_value'];

  1134     }

  1135     else {