defr/drupal/core: includes/form.inc annotate

annotate includes/form.inc @ 15:4347c45bb494 6.7

Drupal 6.7

author	Franck Deroche <webmaster@defr.org>
date	Tue, 23 Dec 2008 14:32:44 +0100
parents	8b6c45761e01
children	3edae6ecd6c6

rev	line source
webmaster@1	1 <?php
webmaster@15	2 // $Id: form.inc,v 1.265.2.16 2008/11/22 13:03:19 dries Exp $
webmaster@1	3
webmaster@1	4 /**
webmaster@1	5 * @defgroup forms Form builder functions
webmaster@1	6 * @{
webmaster@1	7 * Functions that build an abstract representation of a HTML form.
webmaster@1	8 *
webmaster@1	9 * All modules should declare their form builder functions to be in this
webmaster@1	10 * group and each builder function should reference its validate and submit
webmaster@1	11 * functions using \@see. Conversely, validate and submit functions should
webmaster@1	12 * reference the form builder function using \@see. For examples, of this see
webmaster@1	13 * system_modules_uninstall() or user_pass(), the latter of which has the
webmaster@1	14 * following in its doxygen documentation:
webmaster@1	15 *
webmaster@1	16 * \@ingroup forms
webmaster@1	17 * \@see user_pass_validate().
webmaster@1	18 * \@see user_pass_submit().
webmaster@1	19 *
webmaster@1	20 * @} End of "defgroup forms".
webmaster@1	21 */
webmaster@1	22
webmaster@1	23 /**
webmaster@1	24 * @defgroup form_api Form generation
webmaster@1	25 * @{
webmaster@1	26 * Functions to enable the processing and display of HTML forms.
webmaster@1	27 *
webmaster@1	28 * Drupal uses these functions to achieve consistency in its form processing and
webmaster@1	29 * presentation, while simplifying code and reducing the amount of HTML that
webmaster@1	30 * must be explicitly generated by modules.
webmaster@1	31 *
webmaster@1	32 * The drupal_get_form() function handles retrieving, processing, and
webmaster@1	33 * displaying a rendered HTML form for modules automatically. For example:
webmaster@1	34 *
webmaster@1	35 * @code
webmaster@1	36 * // Display the user registration form.
webmaster@1	37 * $output = drupal_get_form('user_register');
webmaster@1	38 * @endcode
webmaster@1	39 *
webmaster@1	40 * Forms can also be built and submitted programmatically without any user input
webmaster@1	41 * using the drupal_execute() function.
webmaster@1	42 *
webmaster@1	43 * For information on the format of the structured arrays used to define forms,
webmaster@1	44 * and more detailed explanations of the Form API workflow, see the
webmaster@1	45 * @link http://api.drupal.org/api/file/developer/topics/forms_api_reference.html reference @endlink
webmaster@1	46 * and the @link http://api.drupal.org/api/file/developer/topics/forms_api.html quickstart guide. @endlink
webmaster@1	47 */
webmaster@1	48
webmaster@1	49 /**
webmaster@1	50 * Retrieves a form from a constructor function, or from the cache if
webmaster@1	51 * the form was built in a previous page-load. The form is then passesed
webmaster@1	52 * on for processing, after and rendered for display if necessary.
webmaster@1	53 *
webmaster@1	54 * @param $form_id
webmaster@1	55 * The unique string identifying the desired form. If a function
webmaster@1	56 * with that name exists, it is called to build the form array.
webmaster@1	57 * Modules that need to generate the same form (or very similar forms)
webmaster@1	58 * using different $form_ids can implement hook_forms(), which maps
webmaster@1	59 * different $form_id values to the proper form constructor function. Examples
webmaster@1	60 * may be found in node_forms(), search_forms(), and user_forms().
webmaster@1	61 * @param ...
webmaster@1	62 * Any additional arguments are passed on to the functions called by
webmaster@1	63 * drupal_get_form(), including the unique form constructor function.
webmaster@1	64 * For example, the node_edit form requires that a node object be passed
webmaster@1	65 * in here when it is called.
webmaster@1	66 * @return
webmaster@1	67 * The rendered form.
webmaster@1	68 */
webmaster@1	69 function drupal_get_form($form_id) {
webmaster@1	70 $form_state = array('storage' => NULL, 'submitted' => FALSE);
webmaster@1	71
webmaster@1	72 $args = func_get_args();
webmaster@1	73 $cacheable = FALSE;
webmaster@1	74
webmaster@1	75 if (isset($_SESSION['batch_form_state'])) {
webmaster@1	76 // We've been redirected here after a batch processing : the form has
webmaster@1	77 // already been processed, so we grab the post-process $form_state value
webmaster@1	78 // and move on to form display. See _batch_finished() function.
webmaster@1	79 $form_state = $_SESSION['batch_form_state'];
webmaster@1	80 unset($_SESSION['batch_form_state']);
webmaster@1	81 }
webmaster@1	82 else {
webmaster@1	83 // If the incoming $_POST contains a form_build_id, we'll check the
webmaster@1	84 // cache for a copy of the form in question. If it's there, we don't
webmaster@1	85 // have to rebuild the form to proceed. In addition, if there is stored
webmaster@1	86 // form_state data from a previous step, we'll retrieve it so it can
webmaster@1	87 // be passed on to the form processing code.
webmaster@1	88 if (isset($_POST['form_id']) && $_POST['form_id'] == $form_id && !empty($_POST['form_build_id'])) {
webmaster@1	89 $form = form_get_cache($_POST['form_build_id'], $form_state);
webmaster@1	90 }
webmaster@1	91
webmaster@1	92 // If the previous bit of code didn't result in a populated $form
webmaster@1	93 // object, we're hitting the form for the first time and we need
webmaster@1	94 // to build it from scratch.
webmaster@1	95 if (!isset($form)) {
webmaster@1	96 $form_state['post'] = $_POST;
webmaster@1	97 // Use a copy of the function's arguments for manipulation
webmaster@1	98 $args_temp = $args;
webmaster@1	99 $args_temp[0] = &$form_state;
webmaster@1	100 array_unshift($args_temp, $form_id);
webmaster@1	101
webmaster@1	102 $form = call_user_func_array('drupal_retrieve_form', $args_temp);
webmaster@9	103 $form_build_id = 'form-'. md5(uniqid(mt_rand(), true));
webmaster@1	104 $form['#build_id'] = $form_build_id;
webmaster@1	105 drupal_prepare_form($form_id, $form, $form_state);
webmaster@1	106 // Store a copy of the unprocessed form for caching and indicate that it
webmaster@1	107 // is cacheable if #cache will be set.
webmaster@1	108 $original_form = $form;
webmaster@1	109 $cacheable = TRUE;
webmaster@1	110 unset($form_state['post']);
webmaster@1	111 }
webmaster@1	112 $form['#post'] = $_POST;
webmaster@1	113
webmaster@1	114 // Now that we know we have a form, we'll process it (validating,
webmaster@1	115 // submitting, and handling the results returned by its submission
webmaster@1	116 // handlers. Submit handlers accumulate data in the form_state by
webmaster@1	117 // altering the $form_state variable, which is passed into them by
webmaster@1	118 // reference.
webmaster@1	119 drupal_process_form($form_id, $form, $form_state);
webmaster@1	120 if ($cacheable && !empty($form['#cache'])) {
webmaster@1	121 // Caching is done past drupal_process_form so #process callbacks can
webmaster@1	122 // set #cache. By not sending the form state, we avoid storing
webmaster@1	123 // $form_state['storage'].
webmaster@1	124 form_set_cache($form_build_id, $original_form, NULL);
webmaster@1	125 }
webmaster@1	126 }
webmaster@1	127
webmaster@1	128 // Most simple, single-step forms will be finished by this point --
webmaster@1	129 // drupal_process_form() usually redirects to another page (or to
webmaster@1	130 // a 'fresh' copy of the form) once processing is complete. If one
webmaster@1	131 // of the form's handlers has set $form_state['redirect'] to FALSE,
webmaster@1	132 // the form will simply be re-rendered with the values still in its
webmaster@1	133 // fields.
webmaster@1	134 //
webmaster@1	135 // If $form_state['storage'] or $form_state['rebuild'] have been
webmaster@1	136 // set by any submit or validate handlers, however, we know that
webmaster@1	137 // we're in a complex multi-part process of some sort and the form's
webmaster@1	138 // workflow is NOT complete. We need to construct a fresh copy of
webmaster@1	139 // the form, passing in the latest $form_state in addition to any
webmaster@1	140 // other variables passed into drupal_get_form().
webmaster@1	141
webmaster@1	142 if (!empty($form_state['rebuild']) \|\| !empty($form_state['storage'])) {
webmaster@1	143 $form = drupal_rebuild_form($form_id, $form_state, $args);
webmaster@1	144 }
webmaster@1	145
webmaster@1	146 // If we haven't redirected to a new location by now, we want to
webmaster@1	147 // render whatever form array is currently in hand.
webmaster@1	148 return drupal_render_form($form_id, $form);
webmaster@1	149 }
webmaster@1	150
webmaster@1	151 /**
webmaster@1	152 * Retrieves a form, caches it and processes it with an empty $_POST.
webmaster@1	153 *
webmaster@1	154 * This function clears $_POST and passes the empty $_POST to the form_builder.
webmaster@1	155 * To preserve some parts from $_POST, pass them in $form_state.
webmaster@1	156 *
webmaster@1	157 * If your AHAH callback simulates the pressing of a button, then your AHAH
webmaster@1	158 * callback will need to do the same as what drupal_get_form would do when the
webmaster@1	159 * button is pressed: get the form from the cache, run drupal_process_form over
webmaster@1	160 * it and then if it needs rebuild, run drupal_rebuild_form over it. Then send
webmaster@1	161 * back a part of the returned form.
webmaster@1	162 * $form_state['clicked_button']['#array_parents'] will help you to find which
webmaster@1	163 * part.
webmaster@1	164 *
webmaster@1	165 * @param $form_id
webmaster@1	166 * The unique string identifying the desired form. If a function
webmaster@1	167 * with that name exists, it is called to build the form array.
webmaster@1	168 * Modules that need to generate the same form (or very similar forms)
webmaster@1	169 * using different $form_ids can implement hook_forms(), which maps
webmaster@1	170 * different $form_id values to the proper form constructor function. Examples
webmaster@1	171 * may be found in node_forms(), search_forms(), and user_forms().
webmaster@1	172 * @param $form_state
webmaster@1	173 * A keyed array containing the current state of the form. Most
webmaster@1	174 * important is the $form_state['storage'] collection.
webmaster@1	175 * @param $args
webmaster@1	176 * Any additional arguments are passed on to the functions called by
webmaster@1	177 * drupal_get_form(), plus the original form_state in the beginning. If you
webmaster@1	178 * are getting a form from the cache, use $form['#parameters'] to shift off
webmaster@1	179 * the $form_id from its beginning then the resulting array can be used as
webmaster@1	180 * $arg here.
webmaster@1	181 * @param $form_build_id
webmaster@1	182 * If the AHAH callback calling this function only alters part of the form,
webmaster@1	183 * then pass in the existing form_build_id so we can re-cache with the same
webmaster@1	184 * csid.
webmaster@1	185 * @return
webmaster@1	186 * The newly built form.
webmaster@1	187 */
webmaster@1	188 function drupal_rebuild_form($form_id, &$form_state, $args, $form_build_id = NULL) {
webmaster@1	189 // Remove the first argument. This is $form_id.when called from
webmaster@1	190 // drupal_get_form and the original $form_state when called from some AHAH
webmaster@1	191 // callback. Neither is needed. After that, put in the current state.
webmaster@1	192 $args[0] = &$form_state;
webmaster@1	193 // And the form_id.
webmaster@1	194 array_unshift($args, $form_id);
webmaster@1	195 $form = call_user_func_array('drupal_retrieve_form', $args);
webmaster@1	196
webmaster@1	197 if (!isset($form_build_id)) {
webmaster@1	198 // We need a new build_id for the new version of the form.
webmaster@1	199 $form_build_id = 'form-'. md5(mt_rand());
webmaster@1	200 }
webmaster@1	201 $form['#build_id'] = $form_build_id;
webmaster@1	202 drupal_prepare_form($form_id, $form, $form_state);
webmaster@1	203
webmaster@1	204 // Now, we cache the form structure so it can be retrieved later for
webmaster@1	205 // validation. If $form_state['storage'] is populated, we'll also cache
webmaster@1	206 // it so that it can be used to resume complex multi-step processes.
webmaster@1	207 form_set_cache($form_build_id, $form, $form_state);
webmaster@1	208
webmaster@1	209 // Clear out all post data, as we don't want the previous step's
webmaster@1	210 // data to pollute this one and trigger validate/submit handling,
webmaster@1	211 // then process the form for rendering.
webmaster@1	212 $_POST = array();
webmaster@1	213 $form['#post'] = array();
webmaster@1	214 drupal_process_form($form_id, $form, $form_state);
webmaster@1	215 return $form;
webmaster@1	216 }
webmaster@1	217
webmaster@1	218 /**
webmaster@9	219 * Store a form in the cache.
webmaster@1	220 */
webmaster@9	221 function form_set_cache($form_build_id, $form, $form_state) {
webmaster@9	222 global $user;
webmaster@9	223 // 6 hours cache life time for forms should be plenty.
webmaster@9	224 $expire = 21600;
webmaster@9	225
webmaster@9	226 if ($user->uid) {
webmaster@9	227 $form['#cache_token'] = drupal_get_token();
webmaster@9	228 }
webmaster@9	229 cache_set('form_'. $form_build_id, $form, 'cache_form', time() + $expire);
webmaster@9	230 if (!empty($form_state['storage'])) {
webmaster@9	231 cache_set('storage_'. $form_build_id, $form_state['storage'], 'cache_form', time() + $expire);
webmaster@1	232 }
webmaster@1	233 }
webmaster@1	234
webmaster@1	235 /**
webmaster@9	236 * Fetch a form from cache.
webmaster@1	237 */
webmaster@9	238 function form_get_cache($form_build_id, &$form_state) {
webmaster@9	239 global $user;
webmaster@9	240 if ($cached = cache_get('form_'. $form_build_id, 'cache_form')) {
webmaster@9	241 $form = $cached->data;
webmaster@9	242 if ((isset($form['#cache_token']) && drupal_valid_token($form['#cache_token'])) \|\| (!isset($form['#cache_token']) && !$user->uid)) {
webmaster@9	243 if ($cached = cache_get('storage_'. $form_build_id, 'cache_form')) {
webmaster@9	244 $form_state['storage'] = $cached->data;
webmaster@9	245 }
webmaster@9	246 return $form;
webmaster@9	247 }
webmaster@1	248 }
webmaster@1	249 }
webmaster@1	250
webmaster@1	251 /**
webmaster@1	252 * Retrieves a form using a form_id, populates it with $form_state['values'],
webmaster@1	253 * processes it, and returns any validation errors encountered. This
webmaster@1	254 * function is the programmatic counterpart to drupal_get_form().
webmaster@1	255 *
webmaster@1	256 * @param $form_id
webmaster@1	257 * The unique string identifying the desired form. If a function
webmaster@1	258 * with that name exists, it is called to build the form array.
webmaster@1	259 * Modules that need to generate the same form (or very similar forms)
webmaster@1	260 * using different $form_ids can implement hook_forms(), which maps
webmaster@1	261 * different $form_id values to the proper form constructor function. Examples
webmaster@1	262 * may be found in node_forms(), search_forms(), and user_forms().
webmaster@1	263 * @param $form_state
webmaster@1	264 * A keyed array containing the current state of the form. Most
webmaster@1	265 * important is the $form_state['values'] collection, a tree of data
webmaster@1	266 * used to simulate the incoming $_POST information from a user's
webmaster@1	267 * form submission.
webmaster@1	268 * @param ...
webmaster@1	269 * Any additional arguments are passed on to the functions called by
webmaster@1	270 * drupal_execute(), including the unique form constructor function.
webmaster@1	271 * For example, the node_edit form requires that a node object be passed
webmaster@1	272 * in here when it is called.
webmaster@1	273 * For example:
webmaster@1	274 *
webmaster@1	275 * // register a new user
webmaster@1	276 * $form_state = array();
webmaster@1	277 * $form_state['values']['name'] = 'robo-user';
webmaster@1	278 * $form_state['values']['mail'] = 'robouser@example.com';
webmaster@1	279 * $form_state['values']['pass'] = 'password';
webmaster@1	280 * $form_state['values']['op'] = t('Create new account');
webmaster@1	281 * drupal_execute('user_register', $form_state);
webmaster@1	282 *
webmaster@1	283 * // Create a new node
webmaster@1	284 * $form_state = array();
webmaster@1	285 * module_load_include('inc', 'node', 'node.pages');
webmaster@1	286 * $node = array('type' => 'story');
webmaster@1	287 * $form_state['values']['title'] = 'My node';
webmaster@1	288 * $form_state['values']['body'] = 'This is the body text!';
webmaster@1	289 * $form_state['values']['name'] = 'robo-user';
webmaster@1	290 * $form_state['values']['op'] = t('Save');
webmaster@1	291 * drupal_execute('story_node_form', $form_state, (object)$node);
webmaster@1	292 */
webmaster@1	293 function drupal_execute($form_id, &$form_state) {
webmaster@1	294 $args = func_get_args();
webmaster@1	295 $form = call_user_func_array('drupal_retrieve_form', $args);
webmaster@1	296 $form['#post'] = $form_state['values'];
webmaster@1	297 drupal_prepare_form($form_id, $form, $form_state);
webmaster@1	298 drupal_process_form($form_id, $form, $form_state);
webmaster@1	299 }
webmaster@1	300
webmaster@1	301 /**
webmaster@1	302 * Retrieves the structured array that defines a given form.
webmaster@1	303 *
webmaster@1	304 * @param $form_id
webmaster@1	305 * The unique string identifying the desired form. If a function
webmaster@1	306 * with that name exists, it is called to build the form array.
webmaster@1	307 * Modules that need to generate the same form (or very similar forms)
webmaster@1	308 * using different $form_ids can implement hook_forms(), which maps
webmaster@1	309 * different $form_id values to the proper form constructor function.
webmaster@1	310 * @param $form_state
webmaster@1	311 * A keyed array containing the current state of the form.
webmaster@1	312 * @param ...
webmaster@1	313 * Any additional arguments needed by the unique form constructor
webmaster@1	314 * function. Generally, these are any arguments passed into the
webmaster@1	315 * drupal_get_form() or drupal_execute() functions after the first
webmaster@1	316 * argument. If a module implements hook_forms(), it can examine
webmaster@1	317 * these additional arguments and conditionally return different
webmaster@1	318 * builder functions as well.
webmaster@1	319 */
webmaster@1	320 function drupal_retrieve_form($form_id, &$form_state) {
webmaster@1	321 static $forms;
webmaster@1	322
webmaster@1	323 // We save two copies of the incoming arguments: one for modules to use
webmaster@1	324 // when mapping form ids to constructor functions, and another to pass to
webmaster@1	325 // the constructor function itself. We shift out the first argument -- the
webmaster@1	326 // $form_id itself -- from the list to pass into the constructor function,
webmaster@1	327 // since it's already known.
webmaster@1	328 $args = func_get_args();
webmaster@1	329 $saved_args = $args;
webmaster@1	330 array_shift($args);
webmaster@1	331 if (isset($form_state)) {
webmaster@1	332 array_shift($args);
webmaster@1	333 }
webmaster@1	334
webmaster@1	335 // We first check to see if there's a function named after the $form_id.
webmaster@1	336 // If there is, we simply pass the arguments on to it to get the form.
webmaster@1	337 if (!function_exists($form_id)) {
webmaster@1	338 // In cases where many form_ids need to share a central constructor function,
webmaster@1	339 // such as the node editing form, modules can implement hook_forms(). It
webmaster@1	340 // maps one or more form_ids to the correct constructor functions.
webmaster@1	341 //
webmaster@1	342 // We cache the results of that hook to save time, but that only works
webmaster@1	343 // for modules that know all their form_ids in advance. (A module that
webmaster@1	344 // adds a small 'rate this comment' form to each comment in a list
webmaster@1	345 // would need a unique form_id for each one, for example.)
webmaster@1	346 //
webmaster@1	347 // So, we call the hook if $forms isn't yet populated, OR if it doesn't
webmaster@1	348 // yet have an entry for the requested form_id.
webmaster@1	349 if (!isset($forms) \|\| !isset($forms[$form_id])) {
webmaster@1	350 $forms = module_invoke_all('forms', $form_id, $args);
webmaster@1	351 }
webmaster@1	352 $form_definition = $forms[$form_id];
webmaster@1	353 if (isset($form_definition['callback arguments'])) {
webmaster@1	354 $args = array_merge($form_definition['callback arguments'], $args);
webmaster@1	355 }
webmaster@1	356 if (isset($form_definition['callback'])) {
webmaster@1	357 $callback = $form_definition['callback'];
webmaster@1	358 }
webmaster@1	359 }
webmaster@1	360
webmaster@1	361 array_unshift($args, NULL);
webmaster@1	362 $args[0] = &$form_state;
webmaster@1	363
webmaster@1	364 // If $callback was returned by a hook_forms() implementation, call it.
webmaster@1	365 // Otherwise, call the function named after the form id.
webmaster@1	366 $form = call_user_func_array(isset($callback) ? $callback : $form_id, $args);
webmaster@1	367
webmaster@1	368 // We store the original function arguments, rather than the final $arg
webmaster@1	369 // value, so that form_alter functions can see what was originally
webmaster@1	370 // passed to drupal_retrieve_form(). This allows the contents of #parameters
webmaster@1	371 // to be saved and passed in at a later date to recreate the form.
webmaster@1	372 $form['#parameters'] = $saved_args;
webmaster@1	373 return $form;
webmaster@1	374 }
webmaster@1	375
webmaster@1	376 /**
webmaster@1	377 * This function is the heart of form API. The form gets built, validated and in
webmaster@1	378 * appropriate cases, submitted.
webmaster@1	379 *
webmaster@1	380 * @param $form_id
webmaster@1	381 * The unique string identifying the current form.
webmaster@1	382 * @param $form
webmaster@1	383 * An associative array containing the structure of the form.
webmaster@1	384 * @param $form_state
webmaster@1	385 * A keyed array containing the current state of the form. This
webmaster@1	386 * includes the current persistent storage data for the form, and
webmaster@1	387 * any data passed along by earlier steps when displaying a
webmaster@1	388 * multi-step form. Additional information, like the sanitized $_POST
webmaster@1	389 * data, is also accumulated here.
webmaster@1	390 */
webmaster@1	391 function drupal_process_form($form_id, &$form, &$form_state) {
webmaster@1	392 $form_state['values'] = array();
webmaster@1	393
webmaster@1	394 $form = form_builder($form_id, $form, $form_state);
webmaster@1	395 // Only process the form if it is programmed or the form_id coming
webmaster@1	396 // from the POST data is set and matches the current form_id.
webmaster@1	397 if ((!empty($form['#programmed'])) \|\| (!empty($form['#post']) && (isset($form['#post']['form_id']) && ($form['#post']['form_id'] == $form_id)))) {
webmaster@1	398 drupal_validate_form($form_id, $form, $form_state);
webmaster@1	399
webmaster@1	400 // form_clean_id() maintains a cache of element IDs it has seen,
webmaster@1	401 // so it can prevent duplicates. We want to be sure we reset that
webmaster@1	402 // cache when a form is processed, so scenerios that result in
webmaster@1	403 // the form being built behind the scenes and again for the
webmaster@1	404 // browser don't increment all the element IDs needlessly.
webmaster@1	405 form_clean_id(NULL, TRUE);
webmaster@1	406
webmaster@1	407 if ((!empty($form_state['submitted'])) && !form_get_errors() && empty($form_state['rebuild'])) {
webmaster@1	408 $form_state['redirect'] = NULL;
webmaster@1	409 form_execute_handlers('submit', $form, $form_state);
webmaster@1	410
webmaster@1	411 // We'll clear out the cached copies of the form and its stored data
webmaster@1	412 // here, as we've finished with them. The in-memory copies are still
webmaster@1	413 // here, though.
webmaster@1	414 if (variable_get('cache', CACHE_DISABLED) == CACHE_DISABLED && !empty($form_state['values']['form_build_id'])) {
webmaster@1	415 cache_clear_all('form_'. $form_state['values']['form_build_id'], 'cache_form');
webmaster@1	416 cache_clear_all('storage_'. $form_state['values']['form_build_id'], 'cache_form');
webmaster@1	417 }
webmaster@1	418
webmaster@1	419 // If batches were set in the submit handlers, we process them now,
webmaster@1	420 // possibly ending execution. We make sure we do not react to the batch
webmaster@1	421 // that is already being processed (if a batch operation performs a
webmaster@1	422 // drupal_execute).
webmaster@1	423 if ($batch =& batch_get() && !isset($batch['current_set'])) {
webmaster@1	424 // The batch uses its own copies of $form and $form_state for
webmaster@1	425 // late execution of submit handers and post-batch redirection.
webmaster@1	426 $batch['form'] = $form;
webmaster@1	427 $batch['form_state'] = $form_state;
webmaster@1	428 $batch['progressive'] = !$form['#programmed'];
webmaster@1	429 batch_process();
webmaster@1	430 // Execution continues only for programmatic forms.
webmaster@1	431 // For 'regular' forms, we get redirected to the batch processing
webmaster@1	432 // page. Form redirection will be handled in _batch_finished(),
webmaster@1	433 // after the batch is processed.
webmaster@1	434 }
webmaster@1	435
webmaster@1	436 // If no submit handlers have populated the $form_state['storage']
webmaster@1	437 // bundle, and the $form_state['rebuild'] flag has not been set,
webmaster@1	438 // we're finished and should redirect to a new destination page
webmaster@1	439 // if one has been set (and a fresh, unpopulated copy of the form
webmaster@1	440 // if one hasn't). If the form was called by drupal_execute(),
webmaster@1	441 // however, we'll skip this and let the calling function examine
webmaster@1	442 // the resulting $form_state bundle itself.
webmaster@1	443 if (!$form['#programmed'] && empty($form_state['rebuild']) && empty($form_state['storage'])) {
webmaster@1	444 drupal_redirect_form($form, $form_state['redirect']);
webmaster@1	445 }
webmaster@1	446 }
webmaster@1	447 }
webmaster@1	448 }
webmaster@1	449
webmaster@1	450 /**
webmaster@1	451 * Prepares a structured form array by adding required elements,
webmaster@1	452 * executing any hook_form_alter functions, and optionally inserting
webmaster@1	453 * a validation token to prevent tampering.
webmaster@1	454 *
webmaster@1	455 * @param $form_id
webmaster@1	456 * A unique string identifying the form for validation, submission,
webmaster@1	457 * theming, and hook_form_alter functions.
webmaster@1	458 * @param $form
webmaster@1	459 * An associative array containing the structure of the form.
webmaster@1	460 * @param $form_state
webmaster@1	461 * A keyed array containing the current state of the form. Passed
webmaster@1	462 * in here so that hook_form_alter() calls can use it, as well.
webmaster@1	463 */
webmaster@1	464 function drupal_prepare_form($form_id, &$form, &$form_state) {
webmaster@1	465 global $user;
webmaster@1	466
webmaster@1	467 $form['#type'] = 'form';
webmaster@1	468 $form['#programmed'] = isset($form['#post']);
webmaster@1	469
webmaster@1	470 if (isset($form['#build_id'])) {
webmaster@1	471 $form['form_build_id'] = array(
webmaster@1	472 '#type' => 'hidden',
webmaster@1	473 '#value' => $form['#build_id'],
webmaster@1	474 '#id' => $form['#build_id'],
webmaster@1	475 '#name' => 'form_build_id',
webmaster@1	476 );
webmaster@1	477 }
webmaster@1	478
webmaster@1	479 // Add a token, based on either #token or form_id, to any form displayed to
webmaster@1	480 // authenticated users. This ensures that any submitted form was actually
webmaster@1	481 // requested previously by the user and protects against cross site request
webmaster@1	482 // forgeries.
webmaster@1	483 if (isset($form['#token'])) {
webmaster@1	484 if ($form['#token'] === FALSE \|\| $user->uid == 0 \|\| $form['#programmed']) {
webmaster@1	485 unset($form['#token']);
webmaster@1	486 }
webmaster@1	487 else {
webmaster@1	488 $form['form_token'] = array('#type' => 'token', '#default_value' => drupal_get_token($form['#token']));
webmaster@1	489 }
webmaster@1	490 }
webmaster@1	491 else if (isset($user->uid) && $user->uid && !$form['#programmed']) {
webmaster@1	492 $form['#token'] = $form_id;
webmaster@1	493 $form['form_token'] = array(
webmaster@1	494 '#id' => form_clean_id('edit-'. $form_id .'-form-token'),
webmaster@1	495 '#type' => 'token',
webmaster@1	496 '#default_value' => drupal_get_token($form['#token']),
webmaster@1	497 );
webmaster@1	498 }
webmaster@1	499
webmaster@1	500 if (isset($form_id)) {
webmaster@1	501 $form['form_id'] = array(
webmaster@1	502 '#type' => 'hidden',
webmaster@1	503 '#value' => $form_id,
webmaster@1	504 '#id' => form_clean_id("edit-$form_id"),
webmaster@1	505 );
webmaster@1	506 }
webmaster@1	507 if (!isset($form['#id'])) {
webmaster@1	508 $form['#id'] = form_clean_id($form_id);
webmaster@1	509 }
webmaster@1	510
webmaster@1	511 $form += _element_info('form');
webmaster@1	512
webmaster@1	513 if (!isset($form['#validate'])) {
webmaster@1	514 if (function_exists($form_id .'_validate')) {
webmaster@1	515 $form['#validate'] = array($form_id .'_validate');
webmaster@1	516 }
webmaster@1	517 }
webmaster@1	518
webmaster@1	519 if (!isset($form['#submit'])) {
webmaster@1	520 if (function_exists($form_id .'_submit')) {
webmaster@1	521 // We set submit here so that it can be altered.
webmaster@1	522 $form['#submit'] = array($form_id .'_submit');
webmaster@1	523 }
webmaster@1	524 }
webmaster@1	525
webmaster@1	526 // Normally, we would call drupal_alter($form_id, $form, $form_state).
webmaster@1	527 // However, drupal_alter() normally supports just one byref parameter. Using
webmaster@1	528 // the __drupal_alter_by_ref key, we can store any additional parameters
webmaster@1	529 // that need to be altered, and they'll be split out into additional params
webmaster@1	530 // for the hook_form_alter() implementations.
webmaster@1	531 // @todo: Remove this in Drupal 7.
webmaster@1	532 $data = &$form;
webmaster@1	533 $data['__drupal_alter_by_ref'] = array(&$form_state);
webmaster@1	534 drupal_alter('form_'. $form_id, $data);
webmaster@1	535
webmaster@1	536 // __drupal_alter_by_ref is unset in the drupal_alter() function, we need
webmaster@1	537 // to repopulate it to ensure both calls get the data.
webmaster@1	538 $data['__drupal_alter_by_ref'] = array(&$form_state);
webmaster@1	539 drupal_alter('form', $data, $form_id);
webmaster@1	540 }
webmaster@1	541
webmaster@1	542
webmaster@1	543 /**
webmaster@1	544 * Validates user-submitted form data from the $form_state using
webmaster@1	545 * the validate functions defined in a structured form array.
webmaster@1	546 *
webmaster@1	547 * @param $form_id
webmaster@1	548 * A unique string identifying the form for validation, submission,
webmaster@1	549 * theming, and hook_form_alter functions.
webmaster@1	550 * @param $form
webmaster@1	551 * An associative array containing the structure of the form.
webmaster@1	552 * @param $form_state
webmaster@1	553 * A keyed array containing the current state of the form. The current
webmaster@1	554 * user-submitted data is stored in $form_state['values'], though
webmaster@1	555 * form validation functions are passed an explicit copy of the
webmaster@1	556 * values for the sake of simplicity. Validation handlers can also
webmaster@1	557 * $form_state to pass information on to submit handlers. For example:
webmaster@1	558 * $form_state['data_for_submision'] = $data;
webmaster@1	559 * This technique is useful when validation requires file parsing,
webmaster@1	560 * web service requests, or other expensive requests that should
webmaster@1	561 * not be repeated in the submission step.
webmaster@1	562 */
webmaster@1	563 function drupal_validate_form($form_id, $form, &$form_state) {
webmaster@1	564 static $validated_forms = array();
webmaster@1	565
webmaster@1	566 if (isset($validated_forms[$form_id])) {
webmaster@1	567 return;
webmaster@1	568 }
webmaster@1	569
webmaster@1	570 // If the session token was set by drupal_prepare_form(), ensure that it
webmaster@1	571 // matches the current user's session.
webmaster@1	572 if (isset($form['#token'])) {
webmaster@1	573 if (!drupal_valid_token($form_state['values']['form_token'], $form['#token'])) {
webmaster@1	574 // Setting this error will cause the form to fail validation.
webmaster@1	575 form_set_error('form_token', t('Validation error, please try again. If this error persists, please contact the site administrator.'));
webmaster@1	576 }
webmaster@1	577 }
webmaster@1	578
webmaster@1	579 _form_validate($form, $form_state, $form_id);
webmaster@1	580 $validated_forms[$form_id] = TRUE;
webmaster@1	581 }
webmaster@1	582
webmaster@1	583 /**
webmaster@1	584 * Renders a structured form array into themed HTML.
webmaster@1	585 *
webmaster@1	586 * @param $form_id
webmaster@1	587 * A unique string identifying the form for validation, submission,
webmaster@1	588 * theming, and hook_form_alter functions.
webmaster@1	589 * @param $form
webmaster@1	590 * An associative array containing the structure of the form.
webmaster@1	591 * @return
webmaster@15	592 * A string containing the themed HTML.
webmaster@1	593 */
webmaster@1	594 function drupal_render_form($form_id, &$form) {
webmaster@1	595 // Don't override #theme if someone already set it.
webmaster@1	596 if (!isset($form['#theme'])) {
webmaster@1	597 init_theme();
webmaster@1	598 $registry = theme_get_registry();
webmaster@1	599 if (isset($registry[$form_id])) {
webmaster@1	600 $form['#theme'] = $form_id;
webmaster@1	601 }
webmaster@1	602 }
webmaster@1	603
webmaster@1	604 $output = drupal_render($form);
webmaster@1	605 return $output;
webmaster@1	606 }
webmaster@1	607
webmaster@1	608 /**
webmaster@1	609 * Redirect the user to a URL after a form has been processed.
webmaster@1	610 *
webmaster@1	611 * @param $form
webmaster@1	612 * An associative array containing the structure of the form.
webmaster@1	613 * @param $redirect
webmaster@1	614 * An optional value containing the destination path to redirect
webmaster@1	615 * to if none is specified by the form.
webmaster@1	616 */
webmaster@1	617 function drupal_redirect_form($form, $redirect = NULL) {
webmaster@1	618 $goto = NULL;
webmaster@1	619 if (isset($redirect)) {
webmaster@1	620 $goto = $redirect;
webmaster@1	621 }
webmaster@1	622 if ($goto !== FALSE && isset($form['#redirect'])) {
webmaster@1	623 $goto = $form['#redirect'];
webmaster@1	624 }
webmaster@1	625 if (!isset($goto) \|\| ($goto !== FALSE)) {
webmaster@1	626 if (isset($goto)) {
webmaster@1	627 if (is_array($goto)) {
webmaster@1	628 call_user_func_array('drupal_goto', $goto);
webmaster@1	629 }
webmaster@1	630 else {
webmaster@1	631 drupal_goto($goto);
webmaster@1	632 }
webmaster@1	633 }
webmaster@1	634 drupal_goto($_GET['q']);
webmaster@1	635 }
webmaster@1	636 }
webmaster@1	637
webmaster@1	638 /**
webmaster@1	639 * Performs validation on form elements. First ensures required fields are
webmaster@1	640 * completed, #maxlength is not exceeded, and selected options were in the
webmaster@1	641 * list of options given to the user. Then calls user-defined validators.
webmaster@1	642 *
webmaster@1	643 * @param $elements
webmaster@1	644 * An associative array containing the structure of the form.
webmaster@1	645 * @param $form_state
webmaster@1	646 * A keyed array containing the current state of the form. The current
webmaster@1	647 * user-submitted data is stored in $form_state['values'], though
webmaster@1	648 * form validation functions are passed an explicit copy of the
webmaster@1	649 * values for the sake of simplicity. Validation handlers can also
webmaster@1	650 * $form_state to pass information on to submit handlers. For example:
webmaster@1	651 * $form_state['data_for_submision'] = $data;
webmaster@1	652 * This technique is useful when validation requires file parsing,
webmaster@1	653 * web service requests, or other expensive requests that should
webmaster@1	654 * not be repeated in the submission step.
webmaster@1	655 * @param $form_id
webmaster@1	656 * A unique string identifying the form for validation, submission,
webmaster@1	657 * theming, and hook_form_alter functions.
webmaster@1	658 */
webmaster@1	659 function _form_validate($elements, &$form_state, $form_id = NULL) {
webmaster@1	660 static $complete_form;
webmaster@1	661
webmaster@1	662 // Also used in the installer, pre-database setup.
webmaster@1	663 $t = get_t();
webmaster@1	664
webmaster@1	665 // Recurse through all children.
webmaster@1	666 foreach (element_children($elements) as $key) {
webmaster@1	667 if (isset($elements[$key]) && $elements[$key]) {
webmaster@1	668 _form_validate($elements[$key], $form_state);
webmaster@1	669 }
webmaster@1	670 }
webmaster@1	671 // Validate the current input.
webmaster@1	672 if (!isset($elements['#validated']) \|\| !$elements['#validated']) {
webmaster@1	673 if (isset($elements['#needs_validation'])) {
webmaster@1	674 // Make sure a value is passed when the field is required.
webmaster@1	675 // A simple call to empty() will not cut it here as some fields, like
webmaster@1	676 // checkboxes, can return a valid value of '0'. Instead, check the
webmaster@1	677 // length if it's a string, and the item count if it's an array.
webmaster@1	678 if ($elements['#required'] && (!count($elements['#value']) \|\| (is_string($elements['#value']) && strlen(trim($elements['#value'])) == 0))) {
webmaster@1	679 form_error($elements, $t('!name field is required.', array('!name' => $elements['#title'])));
webmaster@1	680 }
webmaster@1	681
webmaster@1	682 // Verify that the value is not longer than #maxlength.
webmaster@1	683 if (isset($elements['#maxlength']) && drupal_strlen($elements['#value']) > $elements['#maxlength']) {
webmaster@1	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']))));
webmaster@1	685 }
webmaster@1	686
webmaster@1	687 if (isset($elements['#options']) && isset($elements['#value'])) {
webmaster@1	688 if ($elements['#type'] == 'select') {
webmaster@1	689 $options = form_options_flatten($elements['#options']);
webmaster@1	690 }
webmaster@1	691 else {
webmaster@1	692 $options = $elements['#options'];
webmaster@1	693 }
webmaster@1	694 if (is_array($elements['#value'])) {
webmaster@1	695 $value = $elements['#type'] == 'checkboxes' ? array_keys(array_filter($elements['#value'])) : $elements['#value'];
webmaster@1	696 foreach ($value as $v) {
webmaster@1	697 if (!isset($options[$v])) {
webmaster@1	698 form_error($elements, $t('An illegal choice has been detected. Please contact the site administrator.'));
webmaster@1	699 watchdog('form', 'Illegal choice %choice in !name element.', array('%choice' => $v, '!name' => empty($elements['#title']) ? $elements['#parents'][0] : $elements['#title']), WATCHDOG_ERROR);
webmaster@1	700 }
webmaster@1	701 }
webmaster@1	702 }
webmaster@1	703 elseif (!isset($options[$elements['#value']])) {
webmaster@1	704 form_error($elements, $t('An illegal choice has been detected. Please contact the site administrator.'));
webmaster@1	705 watchdog('form', 'Illegal choice %choice in %name element.', array('%choice' => $elements['#value'], '%name' => empty($elements['#title']) ? $elements['#parents'][0] : $elements['#title']), WATCHDOG_ERROR);
webmaster@1	706 }
webmaster@1	707 }
webmaster@1	708 }
webmaster@1	709
webmaster@1	710 // Call user-defined form level validators and store a copy of the full
webmaster@1	711 // form so that element-specific validators can examine the entire structure
webmaster@1	712 // if necessary.
webmaster@1	713 if (isset($form_id)) {
webmaster@1	714 form_execute_handlers('validate', $elements, $form_state);
webmaster@1	715 $complete_form = $elements;
webmaster@1	716 }
webmaster@1	717 // Call any element-specific validators. These must act on the element
webmaster@1	718 // #value data.
webmaster@1	719 elseif (isset($elements['#element_validate'])) {
webmaster@1	720 foreach ($elements['#element_validate'] as $function) {
webmaster@1	721 if (function_exists($function)) {
webmaster@1	722 $function($elements, $form_state, $complete_form);
webmaster@1	723 }
webmaster@1	724 }
webmaster@1	725 }
webmaster@1	726 $elements['#validated'] = TRUE;
webmaster@1	727 }
webmaster@1	728 }
webmaster@1	729
webmaster@1	730 /**
webmaster@1	731 * A helper function used to execute custom validation and submission
webmaster@1	732 * handlers for a given form. Button-specific handlers are checked
webmaster@1	733 * first. If none exist, the function falls back to form-level handlers.
webmaster@1	734 *
webmaster@1	735 * @param $type
webmaster@1	736 * The type of handler to execute. 'validate' or 'submit' are the
webmaster@1	737 * defaults used by Form API.
webmaster@1	738 * @param $form
webmaster@1	739 * An associative array containing the structure of the form.
webmaster@1	740 * @param $form_state
webmaster@1	741 * A keyed array containing the current state of the form. If the user
webmaster@1	742 * submitted the form by clicking a button with custom handler functions
webmaster@1	743 * defined, those handlers will be stored here.
webmaster@1	744 */
webmaster@1	745 function form_execute_handlers($type, &$form, &$form_state) {
webmaster@1	746 $return = FALSE;
webmaster@1	747 if (isset($form_state[$type .'_handlers'])) {
webmaster@1	748 $handlers = $form_state[$type .'_handlers'];
webmaster@1	749 }
webmaster@1	750 elseif (isset($form['#'. $type])) {
webmaster@1	751 $handlers = $form['#'. $type];
webmaster@1	752 }
webmaster@1	753 else {
webmaster@1	754 $handlers = array();
webmaster@1	755 }
webmaster@1	756
webmaster@1	757 foreach ($handlers as $function) {
webmaster@1	758 if (function_exists($function)) {
webmaster@1	759 if ($type == 'submit' && ($batch =& batch_get())) {
webmaster@1	760 // Some previous _submit handler has set a batch. We store the call
webmaster@1	761 // in a special 'control' batch set, for execution at the correct
webmaster@1	762 // time during the batch processing workflow.
webmaster@1	763 $batch['sets'][] = array('form_submit' => $function);
webmaster@1	764 }
webmaster@1	765 else {
webmaster@1	766 $function($form, $form_state);
webmaster@1	767 }
webmaster@1	768 $return = TRUE;
webmaster@1	769 }
webmaster@1	770 }
webmaster@1	771 return $return;
webmaster@1	772 }
webmaster@1	773
webmaster@1	774 /**
webmaster@1	775 * File an error against a form element.
webmaster@1	776 *
webmaster@1	777 * @param $name
webmaster@1	778 * The name of the form element. If the #parents property of your form
webmaster@1	779 * element is array('foo', 'bar', 'baz') then you may set an error on 'foo'
webmaster@1	780 * or 'foo][bar][baz'. Setting an error on 'foo' sets an error for every
webmaster@1	781 * element where the #parents array starts with 'foo'.
webmaster@1	782 * @param $message
webmaster@1	783 * The error message to present to the user.
webmaster@11	784 * @param $reset
webmaster@11	785 * Reset the form errors static cache.
webmaster@1	786 * @return
webmaster@1	787 * Never use the return value of this function, use form_get_errors and
webmaster@1	788 * form_get_error instead.
webmaster@1	789 */
webmaster@11	790 function form_set_error($name = NULL, $message = '', $reset = FALSE) {
webmaster@1	791 static $form = array();
webmaster@11	792 if ($reset) {
webmaster@11	793 $form = array();
webmaster@11	794 }
webmaster@1	795 if (isset($name) && !isset($form[$name])) {
webmaster@1	796 $form[$name] = $message;
webmaster@1	797 if ($message) {
webmaster@1	798 drupal_set_message($message, 'error');
webmaster@1	799 }
webmaster@1	800 }
webmaster@1	801 return $form;
webmaster@1	802 }
webmaster@1	803
webmaster@1	804 /**
webmaster@1	805 * Return an associative array of all errors.
webmaster@1	806 */
webmaster@1	807 function form_get_errors() {
webmaster@1	808 $form = form_set_error();
webmaster@1	809 if (!empty($form)) {
webmaster@1	810 return $form;
webmaster@1	811 }
webmaster@1	812 }
webmaster@1	813
webmaster@1	814 /**
webmaster@1	815 * Return the error message filed against the form with the specified name.
webmaster@1	816 */
webmaster@1	817 function form_get_error($element) {
webmaster@1	818 $form = form_set_error();
webmaster@1	819 $key = $element['#parents'][0];
webmaster@1	820 if (isset($form[$key])) {
webmaster@1	821 return $form[$key];
webmaster@1	822 }
webmaster@1	823 $key = implode('][', $element['#parents']);
webmaster@1	824 if (isset($form[$key])) {
webmaster@1	825 return $form[$key];
webmaster@1	826 }
webmaster@1	827 }
webmaster@1	828
webmaster@1	829 /**
webmaster@1	830 * Flag an element as having an error.
webmaster@1	831 */
webmaster@1	832 function form_error(&$element, $message = '') {
webmaster@1	833 form_set_error(implode('][', $element['#parents']), $message);
webmaster@1	834 }
webmaster@1	835
webmaster@1	836 /**
webmaster@1	837 * Walk through the structured form array, adding any required
webmaster@1	838 * properties to each element and mapping the incoming $_POST
webmaster@1	839 * data to the proper elements.
webmaster@1	840 *
webmaster@1	841 * @param $form_id
webmaster@1	842 * A unique string identifying the form for validation, submission,
webmaster@1	843 * theming, and hook_form_alter functions.
webmaster@1	844 * @param $form
webmaster@1	845 * An associative array containing the structure of the form.
webmaster@1	846 * @param $form_state
webmaster@1	847 * A keyed array containing the current state of the form. In this
webmaster@1	848 * context, it is used to accumulate information about which button
webmaster@1	849 * was clicked when the form was submitted, as well as the sanitized
webmaster@1	850 * $_POST data.
webmaster@1	851 */
webmaster@1	852 function form_builder($form_id, $form, &$form_state) {
webmaster@1	853 static $complete_form, $cache;
webmaster@1	854
webmaster@1	855 // Initialize as unprocessed.
webmaster@1	856 $form['#processed'] = FALSE;
webmaster@1	857
webmaster@1	858 // Use element defaults.
webmaster@1	859 if ((!empty($form['#type'])) && ($info = _element_info($form['#type']))) {
webmaster@1	860 // Overlay $info onto $form, retaining preexisting keys in $form.
webmaster@1	861 $form += $info;
webmaster@1	862 }
webmaster@1	863
webmaster@1	864 if (isset($form['#type']) && $form['#type'] == 'form') {
webmaster@1	865 $cache = NULL;
webmaster@1	866 $complete_form = $form;
webmaster@1	867 if (!empty($form['#programmed'])) {
webmaster@1	868 $form_state['submitted'] = TRUE;
webmaster@1	869 }
webmaster@1	870 }
webmaster@1	871
webmaster@1	872 if (isset($form['#input']) && $form['#input']) {
webmaster@1	873 _form_builder_handle_input_element($form_id, $form, $form_state, $complete_form);
webmaster@1	874 }
webmaster@1	875 $form['#defaults_loaded'] = TRUE;
webmaster@1	876
webmaster@1	877 // We start off assuming all form elements are in the correct order.
webmaster@1	878 $form['#sorted'] = TRUE;
webmaster@1	879
webmaster@1	880 // Recurse through all child elements.
webmaster@1	881 $count = 0;
webmaster@1	882 foreach (element_children($form) as $key) {
webmaster@1	883 $form[$key]['#post'] = $form['#post'];
webmaster@1	884 $form[$key]['#programmed'] = $form['#programmed'];
webmaster@1	885 // Don't squash an existing tree value.
webmaster@1	886 if (!isset($form[$key]['#tree'])) {
webmaster@1	887 $form[$key]['#tree'] = $form['#tree'];
webmaster@1	888 }
webmaster@1	889
webmaster@1	890 // Deny access to child elements if parent is denied.
webmaster@1	891 if (isset($form['#access']) && !$form['#access']) {
webmaster@1	892 $form[$key]['#access'] = FALSE;
webmaster@1	893 }
webmaster@1	894
webmaster@1	895 // Don't squash existing parents value.
webmaster@1	896 if (!isset($form[$key]['#parents'])) {
webmaster@1	897 // Check to see if a tree of child elements is present. If so,
webmaster@1	898 // continue down the tree if required.
webmaster@1	899 $form[$key]['#parents'] = $form[$key]['#tree'] && $form['#tree'] ? array_merge($form['#parents'], array($key)) : array($key);
webmaster@1	900 $array_parents = isset($form['#array_parents']) ? $form['#array_parents'] : array();
webmaster@1	901 $array_parents[] = $key;
webmaster@1	902 $form[$key]['#array_parents'] = $array_parents;
webmaster@1	903 }
webmaster@1	904
webmaster@1	905 // Assign a decimal placeholder weight to preserve original array order.
webmaster@1	906 if (!isset($form[$key]['#weight'])) {
webmaster@1	907 $form[$key]['#weight'] = $count/1000;
webmaster@1	908 }
webmaster@1	909 else {
webmaster@1	910 // If one of the child elements has a weight then we will need to sort
webmaster@1	911 // later.
webmaster@1	912 unset($form['#sorted']);
webmaster@1	913 }
webmaster@1	914 $form[$key] = form_builder($form_id, $form[$key], $form_state);
webmaster@1	915 $count++;
webmaster@1	916 }
webmaster@1	917
webmaster@1	918 // The #after_build flag allows any piece of a form to be altered
webmaster@1	919 // after normal input parsing has been completed.
webmaster@1	920 if (isset($form['#after_build']) && !isset($form['#after_build_done'])) {
webmaster@1	921 foreach ($form['#after_build'] as $function) {
webmaster@1	922 $form = $function($form, $form_state);
webmaster@1	923 $form['#after_build_done'] = TRUE;
webmaster@1	924 }
webmaster@1	925 }
webmaster@1	926
webmaster@1	927 // Now that we've processed everything, we can go back to handle the funky
webmaster@1	928 // Internet Explorer button-click scenario.
webmaster@1	929 _form_builder_ie_cleanup($form, $form_state);
webmaster@1	930
webmaster@1	931 // We shoud keep the buttons array until the IE clean up function
webmaster@1	932 // has recognized the submit button so the form has been marked
webmaster@1	933 // as submitted. If we already know which button was submitted,
webmaster@1	934 // we don't need the array.
webmaster@1	935 if (!empty($form_state['submitted'])) {
webmaster@1	936 unset($form_state['buttons']);
webmaster@1	937 }
webmaster@1	938
webmaster@1	939 // If some callback set #cache, we need to flip a static flag so later it
webmaster@1	940 // can be found.
webmaster@11	941 if (!empty($form['#cache'])) {
webmaster@1	942 $cache = $form['#cache'];
webmaster@1	943 }
webmaster@1	944 // We are on the top form, we can copy back #cache if it's set.
webmaster@1	945 if (isset($form['#type']) && $form['#type'] == 'form' && isset($cache)) {
webmaster@1	946 $form['#cache'] = TRUE;
webmaster@1	947 }
webmaster@1	948 return $form;
webmaster@1	949 }
webmaster@1	950
webmaster@1	951 /**
webmaster@1	952 * Populate the #value and #name properties of input elements so they
webmaster@1	953 * can be processed and rendered. Also, execute any #process handlers
webmaster@1	954 * attached to a specific element.
webmaster@1	955 */
webmaster@1	956 function _form_builder_handle_input_element($form_id, &$form, &$form_state, $complete_form) {
webmaster@1	957 if (!isset($form['#name'])) {
webmaster@1	958 $name = array_shift($form['#parents']);
webmaster@1	959 $form['#name'] = $name;
webmaster@1	960 if ($form['#type'] == 'file') {
webmaster@1	961 // To make it easier to handle $_FILES in file.inc, we place all
webmaster@1	962 // file fields in the 'files' array. Also, we do not support
webmaster@1	963 // nested file names.
webmaster@1	964 $form['#name'] = 'files['. $form['#name'] .']';
webmaster@1	965 }
webmaster@1	966 elseif (count($form['#parents'])) {
webmaster@1	967 $form['#name'] .= '['. implode('][', $form['#parents']) .']';
webmaster@1	968 }
webmaster@1	969 array_unshift($form['#parents'], $name);
webmaster@1	970 }
webmaster@1	971 if (!isset($form['#id'])) {
webmaster@1	972 $form['#id'] = form_clean_id('edit-'. implode('-', $form['#parents']));
webmaster@1	973 }
webmaster@1	974
webmaster@1	975 unset($edit);
webmaster@1	976 if (!empty($form['#disabled'])) {
webmaster@1	977 $form['#attributes']['disabled'] = 'disabled';
webmaster@1	978 }
webmaster@1	979
webmaster@1	980 if (!isset($form['#value']) && !array_key_exists('#value', $form)) {
webmaster@1	981 $function = !empty($form['#value_callback']) ? $form['#value_callback'] : 'form_type_'. $form['#type'] .'_value';
webmaster@1	982 if (($form['#programmed']) \|\| ((!isset($form['#access']) \|\| $form['#access']) && isset($form['#post']) && (isset($form['#post']['form_id']) && $form['#post']['form_id'] == $form_id))) {
webmaster@1	983 $edit = $form['#post'];
webmaster@1	984 foreach ($form['#parents'] as $parent) {
webmaster@1	985 $edit = isset($edit[$parent]) ? $edit[$parent] : NULL;
webmaster@1	986 }
webmaster@1	987 if (!$form['#programmed'] \|\| isset($edit)) {
webmaster@1	988 // Call #type_value to set the form value;
webmaster@1	989 if (function_exists($function)) {
webmaster@1	990 $form['#value'] = $function($form, $edit);
webmaster@1	991 }
webmaster@1	992 if (!isset($form['#value']) && isset($edit)) {
webmaster@1	993 $form['#value'] = $edit;
webmaster@1	994 }
webmaster@1	995 }
webmaster@1	996 // Mark all posted values for validation.
webmaster@1	997 if (isset($form['#value']) \|\| (isset($form['#required']) && $form['#required'])) {
webmaster@1	998 $form['#needs_validation'] = TRUE;
webmaster@1	999 }
webmaster@1	1000 }
webmaster@1	1001 // Load defaults.
webmaster@1	1002 if (!isset($form['#value'])) {
webmaster@1	1003 // Call #type_value without a second argument to request default_value handling.
webmaster@1	1004 if (function_exists($function)) {
webmaster@1	1005 $form['#value'] = $function($form);
webmaster@1	1006 }
webmaster@1	1007 // Final catch. If we haven't set a value yet, use the explicit default value.
webmaster@1	1008 // Avoid image buttons (which come with garbage value), so we only get value
webmaster@1	1009 // for the button actually clicked.
webmaster@1	1010 if (!isset($form['#value']) && empty($form['#has_garbage_value'])) {
webmaster@1	1011 $form['#value'] = isset($form['#default_value']) ? $form['#default_value'] : '';
webmaster@1	1012 }
webmaster@1	1013 }
webmaster@1	1014 }
webmaster@1	1015
webmaster@1	1016 // Determine which button (if any) was clicked to submit the form.
webmaster@1	1017 // We compare the incoming values with the buttons defined in the form,
webmaster@1	1018 // and flag the one that matches. We have to do some funky tricks to
webmaster@1	1019 // deal with Internet Explorer's handling of single-button forms, though.
webmaster@1	1020 if (!empty($form['#post']) && isset($form['#executes_submit_callback'])) {
webmaster@1	1021 // First, accumulate a collection of buttons, divided into two bins:
webmaster@1	1022 // those that execute full submit callbacks and those that only validate.
webmaster@1	1023 $button_type = $form['#executes_submit_callback'] ? 'submit' : 'button';
webmaster@1	1024 $form_state['buttons'][$button_type][] = $form;
webmaster@1	1025
webmaster@1	1026 if (_form_button_was_clicked($form)) {
webmaster@1	1027 $form_state['submitted'] = $form_state['submitted'] \|\| $form['#executes_submit_callback'];
webmaster@1	1028
webmaster@1	1029 // In most cases, we want to use form_set_value() to manipulate
webmaster@1	1030 // the global variables. In this special case, we want to make sure that
webmaster@1	1031 // the value of this element is listed in $form_variables under 'op'.
webmaster@1	1032 $form_state['values'][$form['#name']] = $form['#value'];
webmaster@1	1033 $form_state['clicked_button'] = $form;
webmaster@1	1034
webmaster@1	1035 if (isset($form['#validate'])) {
webmaster@1	1036 $form_state['validate_handlers'] = $form['#validate'];
webmaster@1	1037 }
webmaster@1	1038 if (isset($form['#submit'])) {
webmaster@1	1039 $form_state['submit_handlers'] = $form['#submit'];
webmaster@1	1040 }
webmaster@1	1041 }
webmaster@1	1042 }
webmaster@1	1043 // Allow for elements to expand to multiple elements, e.g., radios,
webmaster@1	1044 // checkboxes and files.
webmaster@1	1045 if (isset($form['#process']) && !$form['#processed']) {
webmaster@1	1046 foreach ($form['#process'] as $process) {
webmaster@1	1047 if (function_exists($process)) {
webmaster@1	1048 $form = $process($form, isset($edit) ? $edit : NULL, $form_state, $complete_form);
webmaster@1	1049 }
webmaster@1	1050 }
webmaster@1	1051 $form['#processed'] = TRUE;
webmaster@1	1052 }
webmaster@1	1053 form_set_value($form, $form['#value'], $form_state);
webmaster@1	1054 }
webmaster@1	1055
webmaster@1	1056 /**
webmaster@1	1057 * Helper function to handle the sometimes-convoluted logic of button
webmaster@1	1058 * click detection.
webmaster@1	1059 *
webmaster@1	1060 * In Internet Explorer, if ONLY one submit button is present, AND the
webmaster@1	1061 * enter key is used to submit the form, no form value is sent for it
webmaster@1	1062 * and we'll never detect a match. That special case is handled by
webmaster@1	1063 * _form_builder_ie_cleanup().
webmaster@1	1064 */
webmaster@1	1065 function _form_button_was_clicked($form) {
webmaster@1	1066 // First detect normal 'vanilla' button clicks. Traditionally, all
webmaster@1	1067 // standard buttons on a form share the same name (usually 'op'),
webmaster@1	1068 // and the specific return value is used to determine which was
webmaster@1	1069 // clicked. This ONLY works as long as $form['#name'] puts the
webmaster@1	1070 // value at the top level of the tree of $_POST data.
webmaster@1	1071 if (isset($form['#post'][$form['#name']]) && $form['#post'][$form['#name']] == $form['#value']) {
webmaster@1	1072 return TRUE;
webmaster@1	1073 }
webmaster@1	1074 // When image buttons are clicked, browsers do NOT pass the form element
webmaster@1	1075 // value in $_POST. Instead they pass an integer representing the
webmaster@1	1076 // coordinates of the click on the button image. This means that image
webmaster@1	1077 // buttons MUST have unique $form['#name'] values, but the details of
webmaster@1	1078 // their $_POST data should be ignored.
webmaster@1	1079 elseif (!empty($form['#has_garbage_value']) && isset($form['#value']) && $form['#value'] !== '') {
webmaster@1	1080 return TRUE;
webmaster@1	1081 }
webmaster@1	1082 return FALSE;
webmaster@1	1083 }
webmaster@1	1084
webmaster@1	1085 /**
webmaster@1	1086 * In IE, if only one submit button is present, AND the enter key is
webmaster@1	1087 * used to submit the form, no form value is sent for it and our normal
webmaster@1	1088 * button detection code will never detect a match. We call this
webmaster@1	1089 * function after all other button-detection is complete to check
webmaster@1	1090 * for the proper conditions, and treat the single button on the form
webmaster@1	1091 * as 'clicked' if they are met.
webmaster@1	1092 */
webmaster@1	1093 function _form_builder_ie_cleanup($form, &$form_state) {
webmaster@1	1094 // Quick check to make sure we're always looking at the full form
webmaster@1	1095 // and not a sub-element.
webmaster@1	1096 if (!empty($form['#type']) && $form['#type'] == 'form') {
webmaster@1	1097 // If we haven't recognized a submission yet, and there's a single
webmaster@1	1098 // submit button, we know that we've hit the right conditions. Grab
webmaster@1	1099 // the first one and treat it as the clicked button.
webmaster@1	1100 if (empty($form_state['submitted']) && !empty($form_state['buttons']['submit']) && empty($form_state['buttons']['button'])) {
webmaster@1	1101 $button = $form_state['buttons']['submit'][0];
webmaster@1	1102
webmaster@1	1103 // Set up all the $form_state information that would have been
webmaster@1	1104 // populated had the button been recognized earlier.
webmaster@1	1105 $form_state['submitted'] = TRUE;
webmaster@1	1106 $form_state['submit_handlers'] = empty($button['#submit']) ? NULL : $button['#submit'];
webmaster@1	1107 $form_state['validate_handlers'] = empty($button['#validate']) ? NULL : $button['#validate'];
webmaster@1	1108 $form_state['values'][$button['#name']] = $button['#value'];
webmaster@1	1109 $form_state['clicked_button'] = $button;
webmaster@1	1110 }
webmaster@1	1111 }
webmaster@1	1112 }
webmaster@1	1113
webmaster@1	1114 /**
webmaster@1	1115 * Helper function to determine the value for an image button form element.
webmaster@1	1116 *
webmaster@1	1117 * @param $form
webmaster@1	1118 * The form element whose value is being populated.
webmaster@1	1119 * @param $edit
webmaster@1	1120 * The incoming POST data to populate the form element. If this is FALSE,
webmaster@1	1121 * the element's default value should be returned.
webmaster@1	1122 * @return
webmaster@1	1123 * The data that will appear in the $form_state['values'] collection
webmaster@1	1124 * for this element. Return nothing to use the default.
webmaster@1	1125 */
webmaster@1	1126 function form_type_image_button_value($form, $edit = FALSE) {
webmaster@1	1127 if ($edit !== FALSE) {
webmaster@1	1128 if (!empty($edit)) {
webmaster@1	1129 // If we're dealing with Mozilla or Opera, we're lucky. It will
webmaster@1	1130 // return a proper value, and we can get on with things.
webmaster@1	1131 return $form['#return_value'];
webmaster@1	1132 }
webmaster@1	1133 else {
webmaster@1	1134 // Unfortunately, in IE we never get back a proper value for THIS
webmaster@1	1135 // form element. Instead, we get back two split values: one for the
webmaster@1	1136 // X and one for the Y coordinates on which the user clicked the
webmaster@1	1137 // button. We'll find this element in the #post data, and search
webmaster@1	1138 // in the same spot for its name, with '_x'.
webmaster@1	1139 $post = $form['#post'];
webmaster@1	1140 foreach (split('\[', $form['#name']) as $element_name) {
webmaster@1	1141 // chop off the ] that may exist.
webmaster@1	1142 if (substr($element_name, -1) == ']') {
webmaster@1	1143 $element_name = substr($element_name, 0, -1);
webmaster@1	1144 }
webmaster@1	1145
webmaster@1	1146 if (!isset($post[$element_name])) {
webmaster@1	1147 if (isset($post[$element_name .'_x'])) {
webmaster@1	1148 return $form['#return_value'];
webmaster@1	1149 }
webmaster@1	1150 return NULL;
webmaster@1	1151 }
webmaster@1	1152 $post = $post[$element_name];
webmaster@1	1153 }
webmaster@1	1154 return $form['#return_value'];
webmaster@1	1155 }
webmaster@1	1156 }
webmaster@1	1157 }
webmaster@1	1158
webmaster@1	1159 /**
webmaster@1	1160 * Helper function to determine the value for a checkbox form element.
webmaster@1	1161 *
webmaster@1	1162 * @param $form
webmaster@1	1163 * The form element whose value is being populated.
webmaster@1	1164 * @param $edit
webmaster@1	1165 * The incoming POST data to populate the form element. If this is FALSE,
webmaster@1	1166 * the element's default value should be returned.
webmaster@1	1167 * @return
webmaster@1	1168 * The data that will appear in the $form_state['values'] collection
webmaster@1	1169 * for this element. Return nothing to use the default.
webmaster@1	1170 */
webmaster@1	1171 function form_type_checkbox_value($form, $edit = FALSE) {
webmaster@1	1172 if ($edit !== FALSE) {
webmaster@1	1173 return !empty($edit) ? $form['#return_value'] : 0;
webmaster@1	1174 }
webmaster@1	1175 }
webmaster@1	1176
webmaster@1	1177 /**
webmaster@1	1178 * Helper function to determine the value for a checkboxes form element.
webmaster@1	1179 *
webmaster@1	1180 * @param $form
webmaster@1	1181 * The form element whose value is being populated.
webmaster@1	1182 * @param $edit
webmaster@1	1183 * The incoming POST data to populate the form element. If this is FALSE,
webmaster@1	1184 * the element's default value should be returned.
webmaster@1	1185 * @return
webmaster@1	1186 * The data that will appear in the $form_state['values'] collection
webmaster@1	1187 * for this element. Return nothing to use the default.
webmaster@1	1188 */
webmaster@1	1189 function form_type_checkboxes_value($form, $edit = FALSE) {
webmaster@1	1190 if ($edit === FALSE) {
webmaster@1	1191 $value = array();
webmaster@1	1192 $form += array('#default_value' => array());
webmaster@1	1193 foreach ($form['#default_value'] as $key) {
webmaster@1	1194 $value[$key] = 1;
webmaster@1	1195 }
webmaster@1	1196 return $value;
webmaster@1	1197 }
webmaster@1	1198 elseif (!isset($edit)) {
webmaster@1	1199 return array();
webmaster@1	1200 }
webmaster@1	1201 }
webmaster@1	1202
webmaster@1	1203 /**
webmaster@1	1204 * Helper function to determine the value for a password_confirm form
webmaster@1	1205 * element.
webmaster@1	1206 *
webmaster@1	1207 * @param $form
webmaster@1	1208 * The form element whose value is being populated.
webmaster@1	1209 * @param $edit
webmaster@1	1210 * The incoming POST data to populate the form element. If this is FALSE,
webmaster@1	1211 * the element's default value should be returned.
webmaster@1	1212 * @return
webmaster@1	1213 * The data that will appear in the $form_state['values'] collection
webmaster@1	1214 * for this element. Return nothing to use the default.
webmaster@1	1215 */
webmaster@1	1216 function form_type_password_confirm_value($form, $edit = FALSE) {
webmaster@1	1217 if ($edit === FALSE) {
webmaster@1	1218 $form += array('#default_value' => array());
webmaster@1	1219 return $form['#default_value'] + array('pass1' => '', 'pass2' => '');
webmaster@1	1220 }
webmaster@1	1221 }
webmaster@1	1222
webmaster@1	1223 /**
webmaster@1	1224 * Helper function to determine the value for a select form element.
webmaster@1	1225 *
webmaster@1	1226 * @param $form
webmaster@1	1227 * The form element whose value is being populated.
webmaster@1	1228 * @param $edit
webmaster@1	1229 * The incoming POST data to populate the form element. If this is FALSE,
webmaster@1	1230 * the element's default value should be returned.
webmaster@1	1231 * @return
webmaster@1	1232 * The data that will appear in the $form_state['values'] collection
webmaster@1	1233 * for this element. Return nothing to use the default.
webmaster@1	1234 */
webmaster@1	1235 function form_type_select_value($form, $edit = FALSE) {
webmaster@1	1236 if ($edit !== FALSE) {
webmaster@1	1237 if (isset($form['#multiple']) && $form['#multiple']) {
webmaster@1	1238 return (is_array($edit)) ? drupal_map_assoc($edit) : array();
webmaster@1	1239 }
webmaster@1	1240 else {
webmaster@1	1241 return $edit;
webmaster@1	1242 }
webmaster@1	1243 }
webmaster@1	1244 }
webmaster@1	1245
webmaster@1	1246 /**
webmaster@1	1247 * Helper function to determine the value for a textfield form element.
webmaster@1	1248 *
webmaster@1	1249 * @param $form
webmaster@1	1250 * The form element whose value is being populated.
webmaster@1	1251 * @param $edit
webmaster@1	1252 * The incoming POST data to populate the form element. If this is FALSE,
webmaster@1	1253 * the element's default value should be returned.
webmaster@1	1254 * @return
webmaster@1	1255 * The data that will appear in the $form_state['values'] collection
webmaster@1	1256 * for this element. Return nothing to use the default.
webmaster@1	1257 */
webmaster@1	1258 function form_type_textfield_value($form, $edit = FALSE) {
webmaster@1	1259 if ($edit !== FALSE) {
webmaster@1	1260 // Equate $edit to the form value to ensure it's marked for
webmaster@1	1261 // validation.
webmaster@1	1262 return str_replace(array("\r", "\n"), '', $edit);
webmaster@1	1263 }
webmaster@1	1264 }
webmaster@1	1265
webmaster@1	1266 /**
webmaster@1	1267 * Helper function to determine the value for form's token value.
webmaster@1	1268 *
webmaster@1	1269 * @param $form
webmaster@1	1270 * The form element whose value is being populated.
webmaster@1	1271 * @param $edit
webmaster@1	1272 * The incoming POST data to populate the form element. If this is FALSE,
webmaster@1	1273 * the element's default value should be returned.
webmaster@1	1274 * @return
webmaster@1	1275 * The data that will appear in the $form_state['values'] collection
webmaster@1	1276 * for this element. Return nothing to use the default.
webmaster@1	1277 */
webmaster@1	1278 function form_type_token_value($form, $edit = FALSE) {
webmaster@1	1279 if ($edit !== FALSE) {
webmaster@1	1280 return (string)$edit;
webmaster@1	1281 }
webmaster@1	1282 }
webmaster@1	1283
webmaster@1	1284 /**
webmaster@7	1285 * Change submitted form values during the form processing cycle.
webmaster@1	1286 *
webmaster@7	1287 * Use this function to change the submitted value of a form item in the
webmaster@7	1288 * validation phase so that it persists in $form_state through to the
webmaster@7	1289 * submission handlers in the submission phase.
webmaster@1	1290 *
webmaster@7	1291 * Since $form_state['values'] can either be a flat array of values, or a tree
webmaster@7	1292 * of nested values, some care must be taken when using this function.
webmaster@7	1293 * Specifically, $form_item['#parents'] is an array that describes the branch of
webmaster@7	1294 * the tree whose value should be updated. For example, if we wanted to update
webmaster@7	1295 * $form_state['values']['one']['two'] to 'new value', we'd pass in
webmaster@7	1296 * $form_item['#parents'] = array('one', 'two') and $value = 'new value'.
webmaster@7	1297 *
webmaster@7	1298 * @param $form_item
webmaster@7	1299 * The form item that should have its value updated. Keys used: #parents,
webmaster@7	1300 * #value. In most cases you can just pass in the right element from the $form
webmaster@7	1301 * array.
webmaster@1	1302 * @param $value
webmaster@7	1303 * The new value for the form item.
webmaster@7	1304 * @param $form_state
webmaster@7	1305 * The array where the value change should be recorded.
webmaster@1	1306 */
webmaster@7	1307 function form_set_value($form_item, $value, &$form_state) {
webmaster@7	1308 _form_set_value($form_state['values'], $form_item, $form_item['#parents'], $value);
webmaster@1	1309 }
webmaster@1	1310
webmaster@1	1311 /**
webmaster@1	1312 * Helper function for form_set_value().
webmaster@1	1313 *
webmaster@1	1314 * We iterate over $parents and create nested arrays for them
webmaster@1	1315 * in $form_state['values'] if needed. Then we insert the value into
webmaster@1	1316 * the right array.
webmaster@1	1317 */
webmaster@7	1318 function _form_set_value(&$form_values, $form_item, $parents, $value) {
webmaster@1	1319 $parent = array_shift($parents);
webmaster@1	1320 if (empty($parents)) {
webmaster@1	1321 $form_values[$parent] = $value;
webmaster@1	1322 }
webmaster@1	1323 else {
webmaster@1	1324 if (!isset($form_values[$parent])) {
webmaster@1	1325 $form_values[$parent] = array();
webmaster@1	1326 }
webmaster@7	1327 _form_set_value($form_values[$parent], $form_item, $parents, $value);
webmaster@1	1328 }
webmaster@1	1329 }
webmaster@1	1330
webmaster@1	1331 /**
webmaster@1	1332 * Retrieve the default properties for the defined element type.
webmaster@1	1333 */
webmaster@1	1334 function _element_info($type, $refresh = NULL) {
webmaster@1	1335 static $cache;
webmaster@1	1336
webmaster@1	1337 $basic_defaults = array(
webmaster@1	1338 '#description' => NULL,
webmaster@1	1339 '#attributes' => array(),
webmaster@1	1340 '#required' => FALSE,
webmaster@1	1341 '#tree' => FALSE,
webmaster@1	1342 '#parents' => array()
webmaster@1	1343 );
webmaster@1	1344 if (!isset($cache) \|\| $refresh) {
webmaster@1	1345 $cache = array();
webmaster@1	1346 foreach (module_implements('elements') as $module) {
webmaster@1	1347 $elements = module_invoke($module, 'elements');
webmaster@1	1348 if (isset($elements) && is_array($elements)) {
webmaster@1	1349 $cache = array_merge_recursive($cache, $elements);
webmaster@1	1350 }
webmaster@1	1351 }
webmaster@1	1352 if (sizeof($cache)) {
webmaster@1	1353 foreach ($cache as $element_type => $info) {
webmaster@1	1354 $cache[$element_type] = array_merge_recursive($basic_defaults, $info);
webmaster@1	1355 }
webmaster@1	1356 }
webmaster@1	1357 }
webmaster@1	1358
webmaster@1	1359 return $cache[$type];
webmaster@1	1360 }
webmaster@1	1361
webmaster@1	1362 function form_options_flatten($array, $reset = TRUE) {
webmaster@1	1363 static $return;
webmaster@1	1364
webmaster@1	1365 if ($reset) {
webmaster@1	1366 $return = array();
webmaster@1	1367 }
webmaster@1	1368
webmaster@1	1369 foreach ($array as $key => $value) {
webmaster@1	1370 if (is_object($value)) {
webmaster@1	1371 form_options_flatten($value->option, FALSE);
webmaster@1	1372 }
webmaster@1	1373 else if (is_array($value)) {
webmaster@1	1374 form_options_flatten($value, FALSE);
webmaster@1	1375 }
webmaster@1	1376 else {
webmaster@1	1377 $return[$key] = 1;
webmaster@1	1378 }
webmaster@1	1379 }
webmaster@1	1380
webmaster@1	1381 return $return;
webmaster@1	1382 }
webmaster@1	1383
webmaster@1	1384 /**
webmaster@1	1385 * Format a dropdown menu or scrolling selection box.
webmaster@1	1386 *
webmaster@1	1387 * @param $element
webmaster@1	1388 * An associative array containing the properties of the element.
webmaster@1	1389 * Properties used: title, value, options, description, extra, multiple, required
webmaster@1	1390 * @return
webmaster@1	1391 * A themed HTML string representing the form element.
webmaster@1	1392 *
webmaster@1	1393 * @ingroup themeable
webmaster@1	1394 *
webmaster@1	1395 * It is possible to group options together; to do this, change the format of
webmaster@1	1396 * $options to an associative array in which the keys are group labels, and the
webmaster@1	1397 * values are associative arrays in the normal $options format.
webmaster@1	1398 */
webmaster@1	1399 function theme_select($element) {
webmaster@1	1400 $select = '';
webmaster@1	1401 $size = $element['#size'] ? ' size="'. $element['#size'] .'"' : '';
webmaster@1	1402 _form_set_class($element, array('form-select'));
webmaster@1	1403 $multiple = $element['#multiple'];
webmaster@1	1404 return theme('form_element', $element, '<select name="'. $element['#name'] .''. ($multiple ? '[]' : '') .'"'. ($multiple ? ' multiple="multiple" ' : '') . drupal_attributes($element['#attributes']) .' id="'. $element['#id'] .'" '. $size .'>'. form_select_options($element) .'</select>');
webmaster@1	1405 }
webmaster@1	1406
webmaster@1	1407 function form_select_options($element, $choices = NULL) {
webmaster@1	1408 if (!isset($choices)) {
webmaster@1	1409 $choices = $element['#options'];
webmaster@1	1410 }
webmaster@1	1411 // array_key_exists() accommodates the rare event where $element['#value'] is NULL.
webmaster@1	1412 // isset() fails in this situation.
webmaster@1	1413 $value_valid = isset($element['#value']) \|\| array_key_exists('#value', $element);
webmaster@1	1414 $value_is_array = is_array($element['#value']);
webmaster@1	1415 $options = '';
webmaster@1	1416 foreach ($choices as $key => $choice) {
webmaster@1	1417 if (is_array($choice)) {
webmaster@1	1418 $options .= '<optgroup label="'. $key .'">';
webmaster@1	1419 $options .= form_select_options($element, $choice);
webmaster@1	1420 $options .= '</optgroup>';
webmaster@1	1421 }
webmaster@1	1422 elseif (is_object($choice)) {
webmaster@1	1423 $options .= form_select_options($element, $choice->option);
webmaster@1	1424 }
webmaster@1	1425 else {
webmaster@1	1426 $key = (string)$key;
webmaster@1	1427 if ($value_valid && (!$value_is_array && (string)$element['#value'] === $key \|\| ($value_is_array && in_array($key, $element['#value'])))) {
webmaster@1	1428 $selected = ' selected="selected"';
webmaster@1	1429 }
webmaster@1	1430 else {
webmaster@1	1431 $selected = '';
webmaster@1	1432 }
webmaster@1	1433 $options .= '<option value="'. check_plain($key) .'"'. $selected .'>'. check_plain($choice) .'</option>';
webmaster@1	1434 }
webmaster@1	1435 }
webmaster@1	1436 return $options;
webmaster@1	1437 }
webmaster@1	1438
webmaster@1	1439 /**
webmaster@1	1440 * Traverses a select element's #option array looking for any values
webmaster@1	1441 * that hold the given key. Returns an array of indexes that match.
webmaster@1	1442 *
webmaster@1	1443 * This function is useful if you need to modify the options that are
webmaster@1	1444 * already in a form element; for example, to remove choices which are
webmaster@1	1445 * not valid because of additional filters imposed by another module.
webmaster@1	1446 * One example might be altering the choices in a taxonomy selector.
webmaster@1	1447 * To correctly handle the case of a multiple hierarchy taxonomy,
webmaster@1	1448 * #options arrays can now hold an array of objects, instead of a
webmaster@1	1449 * direct mapping of keys to labels, so that multiple choices in the
webmaster@1	1450 * selector can have the same key (and label). This makes it difficult
webmaster@1	1451 * to manipulate directly, which is why this helper function exists.
webmaster@1	1452 *
webmaster@1	1453 * This function does not support optgroups (when the elements of the
webmaster@1	1454 * #options array are themselves arrays), and will return FALSE if
webmaster@1	1455 * arrays are found. The caller must either flatten/restore or
webmaster@1	1456 * manually do their manipulations in this case, since returning the
webmaster@1	1457 * index is not sufficient, and supporting this would make the
webmaster@1	1458 * "helper" too complicated and cumbersome to be of any help.
webmaster@1	1459 *
webmaster@1	1460 * As usual with functions that can return array() or FALSE, do not
webmaster@1	1461 * forget to use === and !== if needed.
webmaster@1	1462 *
webmaster@1	1463 * @param $element
webmaster@1	1464 * The select element to search.
webmaster@1	1465 * @param $key
webmaster@1	1466 * The key to look for.
webmaster@1	1467 * @return
webmaster@1	1468 * An array of indexes that match the given $key. Array will be
webmaster@1	1469 * empty if no elements were found. FALSE if optgroups were found.
webmaster@1	1470 */
webmaster@1	1471 function form_get_options($element, $key) {
webmaster@1	1472 $keys = array();
webmaster@1	1473 foreach ($element['#options'] as $index => $choice) {
webmaster@1	1474 if (is_array($choice)) {
webmaster@1	1475 return FALSE;
webmaster@1	1476 }
webmaster@1	1477 else if (is_object($choice)) {
webmaster@1	1478 if (isset($choice->option[$key])) {
webmaster@1	1479 $keys[] = $index;
webmaster@1	1480 }
webmaster@1	1481 }
webmaster@1	1482 else if ($index == $key) {
webmaster@1	1483 $keys[] = $index;
webmaster@1	1484 }
webmaster@1	1485 }
webmaster@1	1486 return $keys;
webmaster@1	1487 }
webmaster@1	1488
webmaster@1	1489 /**
webmaster@1	1490 * Format a group of form items.
webmaster@1	1491 *
webmaster@1	1492 * @param $element
webmaster@1	1493 * An associative array containing the properties of the element.
webmaster@1	1494 * Properties used: attributes, title, value, description, children, collapsible, collapsed
webmaster@1	1495 * @return
webmaster@1	1496 * A themed HTML string representing the form item group.
webmaster@1	1497 *
webmaster@1	1498 * @ingroup themeable
webmaster@1	1499 */
webmaster@1	1500 function theme_fieldset($element) {
webmaster@15	1501 if (!empty($element['#collapsible'])) {
webmaster@1	1502 drupal_add_js('misc/collapse.js');
webmaster@1	1503
webmaster@1	1504 if (!isset($element['#attributes']['class'])) {
webmaster@1	1505 $element['#attributes']['class'] = '';
webmaster@1	1506 }
webmaster@1	1507
webmaster@1	1508 $element['#attributes']['class'] .= ' collapsible';
webmaster@15	1509 if (!empty($element['#collapsed'])) {
webmaster@1	1510 $element['#attributes']['class'] .= ' collapsed';
webmaster@1	1511 }
webmaster@1	1512 }
webmaster@1	1513
webmaster@7	1514 return '<fieldset'. drupal_attributes($element['#attributes']) .'>'. ($element['#title'] ? '<legend>'. $element['#title'] .'</legend>' : '') . (isset($element['#description']) && $element['#description'] ? '<div class="description">'. $element['#description'] .'</div>' : '') . (!empty($element['#children']) ? $element['#children'] : '') . (isset($element['#value']) ? $element['#value'] : '') ."</fieldset>\n";
webmaster@1	1515 }
webmaster@1	1516
webmaster@1	1517 /**
webmaster@1	1518 * Format a radio button.
webmaster@1	1519 *
webmaster@1	1520 * @param $element
webmaster@1	1521 * An associative array containing the properties of the element.
webmaster@1	1522 * Properties used: required, return_value, value, attributes, title, description
webmaster@1	1523 * @return
webmaster@1	1524 * A themed HTML string representing the form item group.
webmaster@1	1525 *
webmaster@1	1526 * @ingroup themeable
webmaster@1	1527 */
webmaster@1	1528 function theme_radio($element) {
webmaster@1	1529 _form_set_class($element, array('form-radio'));
webmaster@1	1530 $output = '<input type="radio" ';
webmaster@9	1531 $output .= 'id="'. $element['#id'] .'" ';
webmaster@1	1532 $output .= 'name="'. $element['#name'] .'" ';
webmaster@1	1533 $output .= 'value="'. $element['#return_value'] .'" ';
webmaster@1	1534 $output .= (check_plain($element['#value']) == $element['#return_value']) ? ' checked="checked" ' : ' ';
webmaster@1	1535 $output .= drupal_attributes($element['#attributes']) .' />';
webmaster@1	1536 if (!is_null($element['#title'])) {
webmaster@1	1537 $output = '<label class="option">'. $output .' '. $element['#title'] .'</label>';
webmaster@1	1538 }
webmaster@1	1539
webmaster@1	1540 unset($element['#title']);
webmaster@1	1541 return theme('form_element', $element, $output);
webmaster@1	1542 }
webmaster@1	1543
webmaster@1	1544 /**
webmaster@1	1545 * Format a set of radio buttons.
webmaster@1	1546 *
webmaster@1	1547 * @param $element
webmaster@1	1548 * An associative array containing the properties of the element.
webmaster@1	1549 * Properties used: title, value, options, description, required and attributes.
webmaster@1	1550 * @return
webmaster@1	1551 * A themed HTML string representing the radio button set.
webmaster@1	1552 *
webmaster@1	1553 * @ingroup themeable
webmaster@1	1554 */
webmaster@1	1555 function theme_radios($element) {
webmaster@1	1556 $class = 'form-radios';
webmaster@1	1557 if (isset($element['#attributes']['class'])) {
webmaster@1	1558 $class .= ' '. $element['#attributes']['class'];
webmaster@1	1559 }
webmaster@1	1560 $element['#children'] = '<div class="'. $class .'">'. (!empty($element['#children']) ? $element['#children'] : '') .'</div>';
webmaster@1	1561 if ($element['#title'] \|\| $element['#description']) {
webmaster@1	1562 unset($element['#id']);
webmaster@1	1563 return theme('form_element', $element, $element['#children']);
webmaster@1	1564 }
webmaster@1	1565 else {
webmaster@1	1566 return $element['#children'];
webmaster@1	1567 }
webmaster@1	1568 }
webmaster@1	1569
webmaster@1	1570 /**
webmaster@1	1571 * Format a password_confirm item.
webmaster@1	1572 *
webmaster@1	1573 * @param $element
webmaster@1	1574 * An associative array containing the properties of the element.
webmaster@1	1575 * Properties used: title, value, id, required, error.
webmaster@1	1576 * @return
webmaster@1	1577 * A themed HTML string representing the form item.
webmaster@1	1578 *
webmaster@1	1579 * @ingroup themeable
webmaster@1	1580 */
webmaster@1	1581 function theme_password_confirm($element) {
webmaster@1	1582 return theme('form_element', $element, $element['#children']);
webmaster@1	1583 }
webmaster@1	1584
webmaster@1	1585 /**
webmaster@1	1586 * Expand a password_confirm field into two text boxes.
webmaster@1	1587 */
webmaster@1	1588 function expand_password_confirm($element) {
webmaster@1	1589 $element['pass1'] = array(
webmaster@1	1590 '#type' => 'password',
webmaster@1	1591 '#title' => t('Password'),
webmaster@1	1592 '#value' => empty($element['#value']) ? NULL : $element['#value']['pass1'],
webmaster@1	1593 '#required' => $element['#required'],
webmaster@1	1594 '#attributes' => array('class' => 'password-field'),
webmaster@1	1595 );
webmaster@1	1596 $element['pass2'] = array(
webmaster@1	1597 '#type' => 'password',
webmaster@1	1598 '#title' => t('Confirm password'),
webmaster@1	1599 '#value' => empty($element['#value']) ? NULL : $element['#value']['pass2'],
webmaster@1	1600 '#required' => $element['#required'],
webmaster@1	1601 '#attributes' => array('class' => 'password-confirm'),
webmaster@1	1602 );
webmaster@1	1603 $element['#element_validate'] = array('password_confirm_validate');
webmaster@1	1604 $element['#tree'] = TRUE;
webmaster@1	1605
webmaster@1	1606 if (isset($element['#size'])) {
webmaster@1	1607 $element['pass1']['#size'] = $element['pass2']['#size'] = $element['#size'];
webmaster@1	1608 }
webmaster@1	1609
webmaster@1	1610 return $element;
webmaster@1	1611 }
webmaster@1	1612
webmaster@1	1613 /**
webmaster@1	1614 * Validate password_confirm element.
webmaster@1	1615 */
webmaster@1	1616 function password_confirm_validate($form, &$form_state) {
webmaster@1	1617 $pass1 = trim($form['pass1']['#value']);
webmaster@1	1618 if (!empty($pass1)) {
webmaster@1	1619 $pass2 = trim($form['pass2']['#value']);
webmaster@1	1620 if ($pass1 != $pass2) {
webmaster@1	1621 form_error($form, t('The specified passwords do not match.'));
webmaster@1	1622 }
webmaster@1	1623 }
webmaster@1	1624 elseif ($form['#required'] && !empty($form['#post'])) {
webmaster@1	1625 form_error($form, t('Password field is required.'));
webmaster@1	1626 }
webmaster@1	1627
webmaster@1	1628 // Password field must be converted from a two-element array into a single
webmaster@1	1629 // string regardless of validation results.
webmaster@1	1630 form_set_value($form['pass1'], NULL, $form_state);
webmaster@1	1631 form_set_value($form['pass2'], NULL, $form_state);
webmaster@1	1632 form_set_value($form, $pass1, $form_state);
webmaster@1	1633
webmaster@1	1634 return $form;
webmaster@1	1635
webmaster@1	1636 }
webmaster@1	1637
webmaster@1	1638 /**
webmaster@1	1639 * Format a date selection element.
webmaster@1	1640 *
webmaster@1	1641 * @param $element
webmaster@1	1642 * An associative array containing the properties of the element.
webmaster@1	1643 * Properties used: title, value, options, description, required and attributes.
webmaster@1	1644 * @return
webmaster@1	1645 * A themed HTML string representing the date selection boxes.
webmaster@1	1646 *
webmaster@1	1647 * @ingroup themeable
webmaster@1	1648 */
webmaster@1	1649 function theme_date($element) {
webmaster@1	1650 return theme('form_element', $element, '<div class="container-inline">'. $element['#children'] .'</div>');
webmaster@1	1651 }
webmaster@1	1652
webmaster@1	1653 /**
webmaster@1	1654 * Roll out a single date element.
webmaster@1	1655 */
webmaster@1	1656 function expand_date($element) {
webmaster@1	1657 // Default to current date
webmaster@1	1658 if (empty($element['#value'])) {
webmaster@1	1659 $element['#value'] = array('day' => format_date(time(), 'custom', 'j'),
webmaster@1	1660 'month' => format_date(time(), 'custom', 'n'),
webmaster@1	1661 'year' => format_date(time(), 'custom', 'Y'));
webmaster@1	1662 }
webmaster@1	1663
webmaster@1	1664 $element['#tree'] = TRUE;
webmaster@1	1665
webmaster@1	1666 // Determine the order of day, month, year in the site's chosen date format.
webmaster@1	1667 $format = variable_get('date_format_short', 'm/d/Y - H:i');
webmaster@1	1668 $sort = array();
webmaster@1	1669 $sort['day'] = max(strpos($format, 'd'), strpos($format, 'j'));
webmaster@1	1670 $sort['month'] = max(strpos($format, 'm'), strpos($format, 'M'));
webmaster@1	1671 $sort['year'] = strpos($format, 'Y');
webmaster@1	1672 asort($sort);
webmaster@1	1673 $order = array_keys($sort);
webmaster@1	1674
webmaster@1	1675 // Output multi-selector for date.
webmaster@1	1676 foreach ($order as $type) {
webmaster@1	1677 switch ($type) {
webmaster@1	1678 case 'day':
webmaster@1	1679 $options = drupal_map_assoc(range(1, 31));
webmaster@1	1680 break;
webmaster@1	1681 case 'month':
webmaster@1	1682 $options = drupal_map_assoc(range(1, 12), 'map_month');
webmaster@1	1683 break;
webmaster@1	1684 case 'year':
webmaster@1	1685 $options = drupal_map_assoc(range(1900, 2050));
webmaster@1	1686 break;
webmaster@1	1687 }
webmaster@1	1688 $parents = $element['#parents'];
webmaster@1	1689 $parents[] = $type;
webmaster@1	1690 $element[$type] = array(
webmaster@1	1691 '#type' => 'select',
webmaster@1	1692 '#value' => $element['#value'][$type],
webmaster@1	1693 '#attributes' => $element['#attributes'],
webmaster@1	1694 '#options' => $options,
webmaster@1	1695 );
webmaster@1	1696 }
webmaster@1	1697
webmaster@1	1698 return $element;
webmaster@1	1699 }
webmaster@1	1700
webmaster@1	1701 /**
webmaster@1	1702 * Validates the date type to stop dates like February 30, 2006.
webmaster@1	1703 */
webmaster@1	1704 function date_validate($form) {
webmaster@1	1705 if (!checkdate($form['#value']['month'], $form['#value']['day'], $form['#value']['year'])) {
webmaster@1	1706 form_error($form, t('The specified date is invalid.'));
webmaster@1	1707 }
webmaster@1	1708 }
webmaster@1	1709
webmaster@1	1710 /**
webmaster@1	1711 * Helper function for usage with drupal_map_assoc to display month names.
webmaster@1	1712 */
webmaster@1	1713 function map_month($month) {
webmaster@1	1714 return format_date(gmmktime(0, 0, 0, $month, 2, 1970), 'custom', 'M', 0);
webmaster@1	1715 }
webmaster@1	1716
webmaster@1	1717 /**
webmaster@1	1718 * If no default value is set for weight select boxes, use 0.
webmaster@1	1719 */
webmaster@1	1720 function weight_value(&$form) {
webmaster@1	1721 if (isset($form['#default_value'])) {
webmaster@1	1722 $form['#value'] = $form['#default_value'];
webmaster@1	1723 }
webmaster@1	1724 else {
webmaster@1	1725 $form['#value'] = 0;
webmaster@1	1726 }
webmaster@1	1727 }
webmaster@1	1728
webmaster@1	1729 /**
webmaster@1	1730 * Roll out a single radios element to a list of radios,
webmaster@1	1731 * using the options array as index.
webmaster@1	1732 */
webmaster@1	1733 function expand_radios($element) {
webmaster@1	1734 if (count($element['#options']) > 0) {
webmaster@1	1735 foreach ($element['#options'] as $key => $choice) {
webmaster@1	1736 if (!isset($element[$key])) {
webmaster@1	1737 // Generate the parents as the autogenerator does, so we will have a
webmaster@1	1738 // unique id for each radio button.
webmaster@1	1739 $parents_for_id = array_merge($element['#parents'], array($key));
webmaster@1	1740 $element[$key] = array(
webmaster@1	1741 '#type' => 'radio',
webmaster@1	1742 '#title' => $choice,
webmaster@1	1743 '#return_value' => check_plain($key),
webmaster@1	1744 '#default_value' => isset($element['#default_value']) ? $element['#default_value'] : NULL,
webmaster@1	1745 '#attributes' => $element['#attributes'],
webmaster@1	1746 '#parents' => $element['#parents'],
webmaster@1	1747 '#id' => form_clean_id('edit-'. implode('-', $parents_for_id)),
webmaster@9	1748 '#ahah' => isset($element['#ahah']) ? $element['#ahah'] : NULL,
webmaster@1	1749 );
webmaster@1	1750 }
webmaster@1	1751 }
webmaster@1	1752 }
webmaster@1	1753 return $element;
webmaster@1	1754 }
webmaster@1	1755
webmaster@1	1756 /**
webmaster@1	1757 * Add AHAH information about a form element to the page to communicate with
webmaster@1	1758 * javascript. If #ahah[path] is set on an element, this additional javascript is
webmaster@1	1759 * added to the page header to attach the AHAH behaviors. See ahah.js for more
webmaster@1	1760 * information.
webmaster@1	1761 *
webmaster@1	1762 * @param $element
webmaster@1	1763 * An associative array containing the properties of the element.
webmaster@1	1764 * Properties used: ahah_event, ahah_path, ahah_wrapper, ahah_parameters,
webmaster@1	1765 * ahah_effect.
webmaster@1	1766 * @return
webmaster@1	1767 * None. Additional code is added to the header of the page using
webmaster@1	1768 * drupal_add_js.
webmaster@1	1769 */
webmaster@1	1770 function form_expand_ahah($element) {
webmaster@1	1771 static $js_added = array();
webmaster@1	1772 // Add a reasonable default event handler if none specified.
webmaster@1	1773 if (isset($element['#ahah']['path']) && !isset($element['#ahah']['event'])) {
webmaster@1	1774 switch ($element['#type']) {
webmaster@1	1775 case 'submit':
webmaster@1	1776 case 'button':
webmaster@1	1777 case 'image_button':
webmaster@1	1778 // Use the mousedown instead of the click event because form
webmaster@1	1779 // submission via pressing the enter key triggers a click event on
webmaster@1	1780 // submit inputs, inappropriately triggering AHAH behaviors.
webmaster@1	1781 $element['#ahah']['event'] = 'mousedown';
webmaster@1	1782 // Attach an additional event handler so that AHAH behaviours
webmaster@1	1783 // can be triggered still via keyboard input.
webmaster@1	1784 $element['#ahah']['keypress'] = TRUE;
webmaster@1	1785 break;
webmaster@1	1786 case 'password':
webmaster@1	1787 case 'textfield':
webmaster@1	1788 case 'textarea':
webmaster@1	1789 $element['#ahah']['event'] = 'blur';
webmaster@1	1790 break;
webmaster@1	1791 case 'radio':
webmaster@1	1792 case 'checkbox':
webmaster@1	1793 case 'select':
webmaster@1	1794 $element['#ahah']['event'] = 'change';
webmaster@1	1795 break;
webmaster@1	1796 }
webmaster@1	1797 }
webmaster@1	1798
webmaster@1	1799 // Adding the same javascript settings twice will cause a recursion error,
webmaster@1	1800 // we avoid the problem by checking if the javascript has already been added.
webmaster@1	1801 if (isset($element['#ahah']['path']) && isset($element['#ahah']['event']) && !isset($js_added[$element['#id']])) {
webmaster@1	1802 drupal_add_js('misc/jquery.form.js');
webmaster@1	1803 drupal_add_js('misc/ahah.js');
webmaster@1	1804
webmaster@1	1805 $ahah_binding = array(
webmaster@1	1806 'url' => url($element['#ahah']['path']),
webmaster@1	1807 'event' => $element['#ahah']['event'],
webmaster@1	1808 'keypress' => empty($element['#ahah']['keypress']) ? NULL : $element['#ahah']['keypress'],
webmaster@1	1809 'wrapper' => empty($element['#ahah']['wrapper']) ? NULL : $element['#ahah']['wrapper'],
webmaster@1	1810 'selector' => empty($element['#ahah']['selector']) ? '#'. $element['#id'] : $element['#ahah']['selector'],
webmaster@1	1811 'effect' => empty($element['#ahah']['effect']) ? 'none' : $element['#ahah']['effect'],
webmaster@1	1812 'method' => empty($element['#ahah']['method']) ? 'replace' : $element['#ahah']['method'],
webmaster@1	1813 'progress' => empty($element['#ahah']['progress']) ? array('type' => 'throbber') : $element['#ahah']['progress'],
webmaster@1	1814 'button' => isset($element['#executes_submit_callback']) ? array($element['#name'] => $element['#value']) : FALSE,
webmaster@1	1815 );
webmaster@1	1816
webmaster@1	1817 // Convert a simple #ahah[progress] type string into an array.
webmaster@1	1818 if (is_string($ahah_binding['progress'])) {
webmaster@1	1819 $ahah_binding['progress'] = array('type' => $ahah_binding['progress']);
webmaster@1	1820 }
webmaster@1	1821 // Change progress path to a full url.
webmaster@1	1822 if (isset($ahah_binding['progress']['path'])) {
webmaster@1	1823 $ahah_binding['progress']['url'] = url($ahah_binding['progress']['path']);
webmaster@1	1824 }
webmaster@1	1825
webmaster@1	1826 // Add progress.js if we're doing a bar display.
webmaster@1	1827 if ($ahah_binding['progress']['type'] == 'bar') {
webmaster@1	1828 drupal_add_js('misc/progress.js');
webmaster@1	1829 }
webmaster@1	1830
webmaster@1	1831 drupal_add_js(array('ahah' => array($element['#id'] => $ahah_binding)), 'setting');
webmaster@1	1832
webmaster@1	1833 $js_added[$element['#id']] = TRUE;
webmaster@1	1834 $element['#cache'] = TRUE;
webmaster@1	1835 }
webmaster@1	1836 return $element;
webmaster@1	1837 }
webmaster@1	1838
webmaster@1	1839 /**
webmaster@1	1840 * Format a form item.
webmaster@1	1841 *
webmaster@1	1842 * @param $element
webmaster@1	1843 * An associative array containing the properties of the element.
webmaster@1	1844 * Properties used: title, value, description, required, error
webmaster@1	1845 * @return
webmaster@1	1846 * A themed HTML string representing the form item.
webmaster@1	1847 *
webmaster@1	1848 * @ingroup themeable
webmaster@1	1849 */
webmaster@1	1850 function theme_item($element) {
webmaster@1	1851 return theme('form_element', $element, $element['#value'] . (!empty($element['#children']) ? $element['#children'] : ''));
webmaster@1	1852 }
webmaster@1	1853
webmaster@1	1854 /**
webmaster@1	1855 * Format a checkbox.
webmaster@1	1856 *
webmaster@1	1857 * @param $element
webmaster@1	1858 * An associative array containing the properties of the element.
webmaster@1	1859 * Properties used: title, value, return_value, description, required
webmaster@1	1860 * @return
webmaster@1	1861 * A themed HTML string representing the checkbox.
webmaster@1	1862 *
webmaster@1	1863 * @ingroup themeable
webmaster@1	1864 */
webmaster@1	1865 function theme_checkbox($element) {
webmaster@1	1866 _form_set_class($element, array('form-checkbox'));
webmaster@1	1867 $checkbox = '<input ';
webmaster@1	1868 $checkbox .= 'type="checkbox" ';
webmaster@1	1869 $checkbox .= 'name="'. $element['#name'] .'" ';
webmaster@1	1870 $checkbox .= 'id="'. $element['#id'] .'" ' ;
webmaster@1	1871 $checkbox .= 'value="'. $element['#return_value'] .'" ';
webmaster@1	1872 $checkbox .= $element['#value'] ? ' checked="checked" ' : ' ';
webmaster@1	1873 $checkbox .= drupal_attributes($element['#attributes']) .' />';
webmaster@1	1874
webmaster@1	1875 if (!is_null($element['#title'])) {
webmaster@1	1876 $checkbox = '<label class="option">'. $checkbox .' '. $element['#title'] .'</label>';
webmaster@1	1877 }
webmaster@1	1878
webmaster@1	1879 unset($element['#title']);
webmaster@1	1880 return theme('form_element', $element, $checkbox);
webmaster@1	1881 }
webmaster@1	1882
webmaster@1	1883 /**
webmaster@1	1884 * Format a set of checkboxes.
webmaster@1	1885 *
webmaster@1	1886 * @param $element
webmaster@1	1887 * An associative array containing the properties of the element.
webmaster@1	1888 * @return
webmaster@1	1889 * A themed HTML string representing the checkbox set.
webmaster@1	1890 *
webmaster@1	1891 * @ingroup themeable
webmaster@1	1892 */
webmaster@1	1893 function theme_checkboxes($element) {
webmaster@1	1894 $class = 'form-checkboxes';
webmaster@1	1895 if (isset($element['#attributes']['class'])) {
webmaster@1	1896 $class .= ' '. $element['#attributes']['class'];
webmaster@1	1897 }
webmaster@1	1898 $element['#children'] = '<div class="'. $class .'">'. (!empty($element['#children']) ? $element['#children'] : '') .'</div>';
webmaster@1	1899 if ($element['#title'] \|\| $element['#description']) {
webmaster@1	1900 unset($element['#id']);
webmaster@1	1901 return theme('form_element', $element, $element['#children']);
webmaster@1	1902 }
webmaster@1	1903 else {
webmaster@1	1904 return $element['#children'];
webmaster@1	1905 }
webmaster@1	1906 }
webmaster@1	1907
webmaster@1	1908 function expand_checkboxes($element) {
webmaster@1	1909 $value = is_array($element['#value']) ? $element['#value'] : array();
webmaster@1	1910 $element['#tree'] = TRUE;
webmaster@1	1911 if (count($element['#options']) > 0) {
webmaster@1	1912 if (!isset($element['#default_value']) \|\| $element['#default_value'] == 0) {
webmaster@1	1913 $element['#default_value'] = array();
webmaster@1	1914 }
webmaster@1	1915 foreach ($element['#options'] as $key => $choice) {
webmaster@1	1916 if (!isset($element[$key])) {
webmaster@15	1917 $element[$key] = array(
webmaster@15	1918 '#type' => 'checkbox',
webmaster@15	1919 '#processed' => TRUE,
webmaster@15	1920 '#title' => $choice,
webmaster@15	1921 '#return_value' => $key,
webmaster@15	1922 '#default_value' => isset($value[$key]),
webmaster@15	1923 '#attributes' => $element['#attributes'],
webmaster@15	1924 '#ahah' => isset($element['#ahah']) ? $element['#ahah'] : NULL,
webmaster@15	1925 );
webmaster@1	1926 }
webmaster@1	1927 }
webmaster@1	1928 }
webmaster@1	1929 return $element;
webmaster@1	1930 }
webmaster@1	1931
webmaster@1	1932 /**
webmaster@1	1933 * Theme a form submit button.
webmaster@1	1934 *
webmaster@1	1935 * @ingroup themeable
webmaster@1	1936 */
webmaster@1	1937 function theme_submit($element) {
webmaster@1	1938 return theme('button', $element);
webmaster@1	1939 }
webmaster@1	1940
webmaster@1	1941 /**
webmaster@1	1942 * Theme a form button.
webmaster@1	1943 *
webmaster@1	1944 * @ingroup themeable
webmaster@1	1945 */
webmaster@1	1946 function theme_button($element) {
webmaster@1	1947 // Make sure not to overwrite classes.
webmaster@1	1948 if (isset($element['#attributes']['class'])) {
webmaster@1	1949 $element['#attributes']['class'] = 'form-'. $element['#button_type'] .' '. $element['#attributes']['class'];
webmaster@1	1950 }
webmaster@1	1951 else {
webmaster@1	1952 $element['#attributes']['class'] = 'form-'. $element['#button_type'];
webmaster@1	1953 }
webmaster@1	1954
webmaster@1	1955 return '<input type="submit" '. (empty($element['#name']) ? '' : 'name="'. $element['#name'] .'" ') .'id="'. $element['#id'] .'" value="'. check_plain($element['#value']) .'" '. drupal_attributes($element['#attributes']) ." />\n";
webmaster@1	1956 }
webmaster@1	1957
webmaster@1	1958 /**
webmaster@1	1959 * Theme a form image button.
webmaster@1	1960 *
webmaster@1	1961 * @ingroup themeable
webmaster@1	1962 */
webmaster@1	1963 function theme_image_button($element) {
webmaster@1	1964 // Make sure not to overwrite classes.
webmaster@1	1965 if (isset($element['#attributes']['class'])) {
webmaster@1	1966 $element['#attributes']['class'] = 'form-'. $element['#button_type'] .' '. $element['#attributes']['class'];
webmaster@1	1967 }
webmaster@1	1968 else {
webmaster@1	1969 $element['#attributes']['class'] = 'form-'. $element['#button_type'];
webmaster@1	1970 }
webmaster@1	1971
webmaster@1	1972 return '<input type="image" name="'. $element['#name'] .'" '.
webmaster@1	1973 (!empty($element['#value']) ? ('value="'. check_plain($element['#value']) .'" ') : '') .
webmaster@1	1974 'id="'. $element['#id'] .'" '.
webmaster@1	1975 drupal_attributes($element['#attributes']) .
webmaster@1	1976 ' src="'. base_path() . $element['#src'] .'" '.
webmaster@1	1977 (!empty($element['#title']) ? 'alt="'. check_plain($element['#title']) .'" title="'. check_plain($element['#title']) .'" ' : '' ) .
webmaster@1	1978 "/>\n";
webmaster@1	1979 }
webmaster@1	1980
webmaster@1	1981 /**
webmaster@1	1982 * Format a hidden form field.
webmaster@1	1983 *
webmaster@1	1984 * @param $element
webmaster@1	1985 * An associative array containing the properties of the element.
webmaster@1	1986 * Properties used: value, edit
webmaster@1	1987 * @return
webmaster@1	1988 * A themed HTML string representing the hidden form field.
webmaster@1	1989 *
webmaster@1	1990 * @ingroup themeable
webmaster@1	1991 */
webmaster@1	1992 function theme_hidden($element) {
webmaster@1	1993 return '<input type="hidden" name="'. $element['#name'] .'" id="'. $element['#id'] .'" value="'. check_plain($element['#value']) ."\" ". drupal_attributes($element['#attributes']) ." />\n";
webmaster@1	1994 }
webmaster@1	1995
webmaster@1	1996 /**
webmaster@1	1997 * Format a form token.
webmaster@1	1998 *
webmaster@1	1999 * @ingroup themeable
webmaster@1	2000 */
webmaster@1	2001 function theme_token($element) {
webmaster@1	2002 return theme('hidden', $element);
webmaster@1	2003 }
webmaster@1	2004
webmaster@1	2005 /**
webmaster@1	2006 * Format a textfield.
webmaster@1	2007 *
webmaster@1	2008 * @param $element
webmaster@1	2009 * An associative array containing the properties of the element.
webmaster@1	2010 * Properties used: title, value, description, size, maxlength, required, attributes autocomplete_path
webmaster@1	2011 * @return
webmaster@1	2012 * A themed HTML string representing the textfield.
webmaster@1	2013 *
webmaster@1	2014 * @ingroup themeable
webmaster@1	2015 */
webmaster@1	2016 function theme_textfield($element) {
webmaster@1	2017 $size = empty($element['#size']) ? '' : ' size="'. $element['#size'] .'"';
webmaster@1	2018 $maxlength = empty($element['#maxlength']) ? '' : ' maxlength="'. $element['#maxlength'] .'"';
webmaster@1	2019 $class = array('form-text');
webmaster@1	2020 $extra = '';
webmaster@1	2021 $output = '';
webmaster@1	2022
webmaster@13	2023 if ($element['#autocomplete_path'] && menu_valid_path(array('link_path' => $element['#autocomplete_path']))) {
webmaster@1	2024 drupal_add_js('misc/autocomplete.js');
webmaster@1	2025 $class[] = 'form-autocomplete';
webmaster@1	2026 $extra = '<input class="autocomplete" type="hidden" id="'. $element['#id'] .'-autocomplete" value="'. check_url(url($element['#autocomplete_path'], array('absolute' => TRUE))) .'" disabled="disabled" />';
webmaster@1	2027 }
webmaster@1	2028 _form_set_class($element, $class);
webmaster@1	2029
webmaster@1	2030 if (isset($element['#field_prefix'])) {
webmaster@1	2031 $output .= '<span class="field-prefix">'. $element['#field_prefix'] .'</span> ';
webmaster@1	2032 }
webmaster@1	2033
webmaster@1	2034 $output .= '<input type="text"'. $maxlength .' name="'. $element['#name'] .'" id="'. $element['#id'] .'"'. $size .' value="'. check_plain($element['#value']) .'"'. drupal_attributes($element['#attributes']) .' />';
webmaster@1	2035
webmaster@1	2036 if (isset($element['#field_suffix'])) {
webmaster@1	2037 $output .= ' <span class="field-suffix">'. $element['#field_suffix'] .'</span>';
webmaster@1	2038 }
webmaster@1	2039
webmaster@1	2040 return theme('form_element', $element, $output) . $extra;
webmaster@1	2041 }
webmaster@1	2042
webmaster@1	2043 /**
webmaster@1	2044 * Format a form.
webmaster@1	2045 *
webmaster@1	2046 * @param $element
webmaster@1	2047 * An associative array containing the properties of the element.
webmaster@1	2048 * Properties used: action, method, attributes, children
webmaster@1	2049 * @return
webmaster@1	2050 * A themed HTML string representing the form.
webmaster@1	2051 *
webmaster@1	2052 * @ingroup themeable
webmaster@1	2053 */
webmaster@1	2054 function theme_form($element) {
webmaster@1	2055 // Anonymous div to satisfy XHTML compliance.
webmaster@1	2056 $action = $element['#action'] ? 'action="'. check_url($element['#action']) .'" ' : '';
webmaster@1	2057 return '<form '. $action .' accept-charset="UTF-8" method="'. $element['#method'] .'" id="'. $element['#id'] .'"'. drupal_attributes($element['#attributes']) .">\n<div>". $element['#children'] ."\n</div></form>\n";
webmaster@1	2058 }
webmaster@1	2059
webmaster@1	2060 /**
webmaster@1	2061 * Format a textarea.
webmaster@1	2062 *
webmaster@1	2063 * @param $element
webmaster@1	2064 * An associative array containing the properties of the element.
webmaster@1	2065 * Properties used: title, value, description, rows, cols, required, attributes
webmaster@1	2066 * @return
webmaster@1	2067 * A themed HTML string representing the textarea.
webmaster@1	2068 *
webmaster@1	2069 * @ingroup themeable
webmaster@1	2070 */
webmaster@1	2071 function theme_textarea($element) {
webmaster@1	2072 $class = array('form-textarea');
webmaster@1	2073
webmaster@1	2074 // Add teaser behavior (must come before resizable)
webmaster@1	2075 if (!empty($element['#teaser'])) {
webmaster@1	2076 drupal_add_js('misc/teaser.js');
webmaster@1	2077 // Note: arrays are merged in drupal_get_js().
webmaster@1	2078 drupal_add_js(array('teaserCheckbox' => array($element['#id'] => $element['#teaser_checkbox'])), 'setting');
webmaster@1	2079 drupal_add_js(array('teaser' => array($element['#id'] => $element['#teaser'])), 'setting');
webmaster@1	2080 $class[] = 'teaser';
webmaster@1	2081 }
webmaster@1	2082
webmaster@1	2083 // Add resizable behavior
webmaster@1	2084 if ($element['#resizable'] !== FALSE) {
webmaster@1	2085 drupal_add_js('misc/textarea.js');
webmaster@1	2086 $class[] = 'resizable';
webmaster@1	2087 }
webmaster@1	2088
webmaster@1	2089 _form_set_class($element, $class);
webmaster@1	2090 return theme('form_element', $element, '<textarea cols="'. $element['#cols'] .'" rows="'. $element['#rows'] .'" name="'. $element['#name'] .'" id="'. $element['#id'] .'" '. drupal_attributes($element['#attributes']) .'>'. check_plain($element['#value']) .'</textarea>');
webmaster@1	2091 }
webmaster@1	2092
webmaster@1	2093 /**
webmaster@1	2094 * Format HTML markup for use in forms.
webmaster@1	2095 *
webmaster@1	2096 * This is used in more advanced forms, such as theme selection and filter format.
webmaster@1	2097 *
webmaster@1	2098 * @param $element
webmaster@1	2099 * An associative array containing the properties of the element.
webmaster@1	2100 * Properties used: value, children.
webmaster@1	2101 * @return
webmaster@1	2102 * A themed HTML string representing the HTML markup.
webmaster@1	2103 *
webmaster@1	2104 * @ingroup themeable
webmaster@1	2105 */
webmaster@1	2106
webmaster@1	2107 function theme_markup($element) {
webmaster@1	2108 return (isset($element['#value']) ? $element['#value'] : '') . (isset($element['#children']) ? $element['#children'] : '');
webmaster@1	2109 }
webmaster@1	2110
webmaster@1	2111 /**
webmaster@1	2112 * Format a password field.
webmaster@1	2113 *
webmaster@1	2114 * @param $element
webmaster@1	2115 * An associative array containing the properties of the element.
webmaster@1	2116 * Properties used: title, value, description, size, maxlength, required, attributes
webmaster@1	2117 * @return
webmaster@1	2118 * A themed HTML string representing the form.
webmaster@1	2119 *
webmaster@1	2120 * @ingroup themeable
webmaster@1	2121 */
webmaster@1	2122 function theme_password($element) {
webmaster@1	2123 $size = $element['#size'] ? ' size="'. $element['#size'] .'" ' : '';
webmaster@1	2124 $maxlength = $element['#maxlength'] ? ' maxlength="'. $element['#maxlength'] .'" ' : '';
webmaster@1	2125
webmaster@1	2126 _form_set_class($element, array('form-text'));
webmaster@1	2127 $output = '<input type="password" name="'. $element['#name'] .'" id="'. $element['#id'] .'" '. $maxlength . $size . drupal_attributes($element['#attributes']) .' />';
webmaster@1	2128 return theme('form_element', $element, $output);
webmaster@1	2129 }
webmaster@1	2130
webmaster@1	2131 /**
webmaster@1	2132 * Expand weight elements into selects.
webmaster@1	2133 */
webmaster@1	2134 function process_weight($element) {
webmaster@1	2135 for ($n = (-1 * $element['#delta']); $n <= $element['#delta']; $n++) {
webmaster@1	2136 $weights[$n] = $n;
webmaster@1	2137 }
webmaster@1	2138 $element['#options'] = $weights;
webmaster@1	2139 $element['#type'] = 'select';
webmaster@1	2140 $element['#is_weight'] = TRUE;
webmaster@1	2141 $element += _element_info('select');
webmaster@1	2142 return $element;
webmaster@1	2143 }
webmaster@1	2144
webmaster@1	2145 /**
webmaster@1	2146 * Format a file upload field.
webmaster@1	2147 *
webmaster@1	2148 * @param $title
webmaster@1	2149 * The label for the file upload field.
webmaster@1	2150 * @param $name
webmaster@1	2151 * The internal name used to refer to the field.
webmaster@1	2152 * @param $size
webmaster@1	2153 * A measure of the visible size of the field (passed directly to HTML).
webmaster@1	2154 * @param $description
webmaster@1	2155 * Explanatory text to display after the form item.
webmaster@1	2156 * @param $required
webmaster@1	2157 * Whether the user must upload a file to the field.
webmaster@1	2158 * @return
webmaster@1	2159 * A themed HTML string representing the field.
webmaster@1	2160 *
webmaster@1	2161 * @ingroup themeable
webmaster@1	2162 *
webmaster@1	2163 * For assistance with handling the uploaded file correctly, see the API
webmaster@1	2164 * provided by file.inc.
webmaster@1	2165 */
webmaster@1	2166 function theme_file($element) {
webmaster@1	2167 _form_set_class($element, array('form-file'));
webmaster@1	2168 return theme('form_element', $element, '<input type="file" name="'. $element['#name'] .'"'. ($element['#attributes'] ? ' '. drupal_attributes($element['#attributes']) : '') .' id="'. $element['#id'] .'" size="'. $element['#size'] ."\" />\n");
webmaster@1	2169 }
webmaster@1	2170
webmaster@1	2171 /**
webmaster@1	2172 * Return a themed form element.
webmaster@1	2173 *
webmaster@1	2174 * @param element
webmaster@1	2175 * An associative array containing the properties of the element.
webmaster@1	2176 * Properties used: title, description, id, required
webmaster@1	2177 * @param $value
webmaster@1	2178 * The form element's data.
webmaster@1	2179 * @return
webmaster@1	2180 * A string representing the form element.
webmaster@1	2181 *
webmaster@1	2182 * @ingroup themeable
webmaster@1	2183 */
webmaster@1	2184 function theme_form_element($element, $value) {
webmaster@1	2185 // This is also used in the installer, pre-database setup.
webmaster@1	2186 $t = get_t();
webmaster@1	2187
webmaster@1	2188 $output = '<div class="form-item"';
webmaster@1	2189 if (!empty($element['#id'])) {
webmaster@1	2190 $output .= ' id="'. $element['#id'] .'-wrapper"';
webmaster@1	2191 }
webmaster@1	2192 $output .= ">\n";
webmaster@1	2193 $required = !empty($element['#required']) ? '<span class="form-required" title="'. $t('This field is required.') .'">*</span>' : '';
webmaster@1	2194
webmaster@1	2195 if (!empty($element['#title'])) {
webmaster@1	2196 $title = $element['#title'];
webmaster@1	2197 if (!empty($element['#id'])) {
webmaster@1	2198 $output .= ' <label for="'. $element['#id'] .'">'. $t('!title: !required', array('!title' => filter_xss_admin($title), '!required' => $required)) ."</label>\n";
webmaster@1	2199 }
webmaster@1	2200 else {
webmaster@1	2201 $output .= ' <label>'. $t('!title: !required', array('!title' => filter_xss_admin($title), '!required' => $required)) ."</label>\n";
webmaster@1	2202 }
webmaster@1	2203 }
webmaster@1	2204
webmaster@1	2205 $output .= " $value\n";
webmaster@1	2206
webmaster@1	2207 if (!empty($element['#description'])) {
webmaster@1	2208 $output .= ' <div class="description">'. $element['#description'] ."</div>\n";
webmaster@1	2209 }
webmaster@1	2210
webmaster@1	2211 $output .= "</div>\n";
webmaster@1	2212
webmaster@1	2213 return $output;
webmaster@1	2214 }
webmaster@1	2215
webmaster@1	2216 /**
webmaster@1	2217 * Sets a form element's class attribute.
webmaster@1	2218 *
webmaster@1	2219 * Adds 'required' and 'error' classes as needed.
webmaster@1	2220 *
webmaster@1	2221 * @param &$element
webmaster@1	2222 * The form element.
webmaster@1	2223 * @param $name
webmaster@1	2224 * Array of new class names to be added.
webmaster@1	2225 */
webmaster@1	2226 function _form_set_class(&$element, $class = array()) {
webmaster@1	2227 if ($element['#required']) {
webmaster@1	2228 $class[] = 'required';
webmaster@1	2229 }
webmaster@1	2230 if (form_get_error($element)) {
webmaster@1	2231 $class[] = 'error';
webmaster@1	2232 }
webmaster@1	2233 if (isset($element['#attributes']['class'])) {
webmaster@1	2234 $class[] = $element['#attributes']['class'];
webmaster@1	2235 }
webmaster@1	2236 $element['#attributes']['class'] = implode(' ', $class);
webmaster@1	2237 }
webmaster@1	2238
webmaster@1	2239 /**
webmaster@1	2240 * Prepare an HTML ID attribute string for a form item.
webmaster@1	2241 *
webmaster@1	2242 * Remove invalid characters and guarantee uniqueness.
webmaster@1	2243 *
webmaster@1	2244 * @param $id
webmaster@1	2245 * The ID to clean.
webmaster@1	2246 * @param $flush
webmaster@1	2247 * If set to TRUE, the function will flush and reset the static array
webmaster@1	2248 * which is built to test the uniqueness of element IDs. This is only
webmaster@1	2249 * used if a form has completed the validation process. This parameter
webmaster@1	2250 * should never be set to TRUE if this function is being called to
webmaster@1	2251 * assign an ID to the #ID element.
webmaster@1	2252 * @return
webmaster@1	2253 * The cleaned ID.
webmaster@1	2254 */
webmaster@1	2255 function form_clean_id($id = NULL, $flush = FALSE) {
webmaster@1	2256 static $seen_ids = array();
webmaster@1	2257
webmaster@1	2258 if ($flush) {
webmaster@1	2259 $seen_ids = array();
webmaster@1	2260 return;
webmaster@1	2261 }
webmaster@1	2262 $id = str_replace(array('][', '_', ' '), '-', $id);
webmaster@1	2263
webmaster@1	2264 // Ensure IDs are unique. The first occurrence is held but left alone.
webmaster@1	2265 // Subsequent occurrences get a number appended to them. This incrementing
webmaster@1	2266 // will almost certainly break code that relies on explicit HTML IDs in
webmaster@1	2267 // forms that appear more than once on the page, but the alternative is
webmaster@1	2268 // outputting duplicate IDs, which would break JS code and XHTML
webmaster@1	2269 // validity anyways. For now, it's an acceptable stopgap solution.
webmaster@1	2270 if (isset($seen_ids[$id])) {
webmaster@1	2271 $id = $id .'-'. $seen_ids[$id]++;
webmaster@1	2272 }
webmaster@1	2273 else {
webmaster@1	2274 $seen_ids[$id] = 1;
webmaster@1	2275 }
webmaster@1	2276
webmaster@1	2277 return $id;
webmaster@1	2278 }
webmaster@1	2279
webmaster@1	2280 /**
webmaster@1	2281 * @} End of "defgroup form_api".
webmaster@1	2282 */
webmaster@1	2283
webmaster@1	2284 /**
webmaster@1	2285 * @defgroup batch Batch operations
webmaster@1	2286 * @{
webmaster@1	2287 * Functions allowing forms processing to be spread out over several page
webmaster@1	2288 * requests, thus ensuring that the processing does not get interrupted
webmaster@1	2289 * because of a PHP timeout, while allowing the user to receive feedback
webmaster@1	2290 * on the progress of the ongoing operations.
webmaster@1	2291 *
webmaster@1	2292 * The API is primarily designed to integrate nicely with the Form API
webmaster@1	2293 * workflow, but can also be used by non-FAPI scripts (like update.php)
webmaster@1	2294 * or even simple page callbacks (which should probably be used sparingly).
webmaster@1	2295 *
webmaster@1	2296 * Example:
webmaster@1	2297 * @code
webmaster@1	2298 * $batch = array(
webmaster@1	2299 * 'title' => t('Exporting'),
webmaster@1	2300 * 'operations' => array(
webmaster@1	2301 * array('my_function_1', array($account->uid, 'story')),
webmaster@1	2302 * array('my_function_2', array()),
webmaster@1	2303 * ),
webmaster@1	2304 * 'finished' => 'my_finished_callback',
webmaster@1	2305 * );
webmaster@1	2306 * batch_set($batch);
webmaster@1	2307 * // only needed if not inside a form _submit handler :
webmaster@1	2308 * batch_process();
webmaster@1	2309 * @endcode
webmaster@1	2310 *
webmaster@1	2311 * Sample batch operations:
webmaster@1	2312 * @code
webmaster@1	2313 * // Simple and artificial: load a node of a given type for a given user
webmaster@1	2314 * function my_function_1($uid, $type, &$context) {
webmaster@1	2315 * // The $context array gathers batch context information about the execution (read),
webmaster@1	2316 * // as well as 'return values' for the current operation (write)
webmaster@1	2317 * // The following keys are provided :
webmaster@1	2318 * // 'results' (read / write): The array of results gathered so far by
webmaster@1	2319 * // the batch processing, for the current operation to append its own.
webmaster@1	2320 * // 'message' (write): A text message displayed in the progress page.
webmaster@1	2321 * // The following keys allow for multi-step operations :
webmaster@1	2322 * // 'sandbox' (read / write): An array that can be freely used to
webmaster@1	2323 * // store persistent data between iterations. It is recommended to
webmaster@1	2324 * // use this instead of $_SESSION, which is unsafe if the user
webmaster@1	2325 * // continues browsing in a separate window while the batch is processing.
webmaster@1	2326 * // 'finished' (write): A float number between 0 and 1 informing
webmaster@1	2327 * // the processing engine of the completion level for the operation.
webmaster@1	2328 * // 1 (or no value explicitly set) means the operation is finished
webmaster@1	2329 * // and the batch processing can continue to the next operation.
webmaster@1	2330 *
webmaster@1	2331 * $node = node_load(array('uid' => $uid, 'type' => $type));
webmaster@1	2332 * $context['results'][] = $node->nid .' : '. $node->title;
webmaster@1	2333 * $context['message'] = $node->title;
webmaster@1	2334 * }
webmaster@1	2335 *
webmaster@1	2336 * // More advanced example: multi-step operation - load all nodes, five by five
webmaster@1	2337 * function my_function_2(&$context) {
webmaster@1	2338 * if (empty($context['sandbox'])) {
webmaster@1	2339 * $context['sandbox']['progress'] = 0;
webmaster@1	2340 * $context['sandbox']['current_node'] = 0;
webmaster@1	2341 * $context['sandbox']['max'] = db_result(db_query('SELECT COUNT(DISTINCT nid) FROM {node}'));
webmaster@1	2342 * }
webmaster@1	2343 * $limit = 5;
webmaster@1	2344 * $result = db_query_range("SELECT nid FROM {node} WHERE nid > %d ORDER BY nid ASC", $context['sandbox']['current_node'], 0, $limit);
webmaster@1	2345 * while ($row = db_fetch_array($result)) {
webmaster@1	2346 * $node = node_load($row['nid'], NULL, TRUE);
webmaster@1	2347 * $context['results'][] = $node->nid .' : '. $node->title;
webmaster@1	2348 * $context['sandbox']['progress']++;
webmaster@1	2349 * $context['sandbox']['current_node'] = $node->nid;
webmaster@1	2350 * $context['message'] = $node->title;
webmaster@1	2351 * }
webmaster@1	2352 * if ($context['sandbox']['progress'] != $context['sandbox']['max']) {
webmaster@1	2353 * $context['finished'] = $context['sandbox']['progress'] / $context['sandbox']['max'];
webmaster@1	2354 * }
webmaster@1	2355 * }
webmaster@1	2356 * @endcode
webmaster@1	2357 *
webmaster@1	2358 * Sample 'finished' callback:
webmaster@1	2359 * @code
webmaster@1	2360 * function batch_test_finished($success, $results, $operations) {
webmaster@1	2361 * if ($success) {
webmaster@1	2362 * $message = format_plural(count($results), 'One post processed.', '@count posts processed.');
webmaster@1	2363 * }
webmaster@1	2364 * else {
webmaster@1	2365 * $message = t('Finished with an error.');
webmaster@1	2366 * }
webmaster@1	2367 * drupal_set_message($message);
webmaster@1	2368 * // Providing data for the redirected page is done through $_SESSION.
webmaster@1	2369 * foreach ($results as $result) {
webmaster@1	2370 * $items[] = t('Loaded node %title.', array('%title' => $result));
webmaster@1	2371 * }
webmaster@1	2372 * $_SESSION['my_batch_results'] = $items;
webmaster@1	2373 * }
webmaster@1	2374 * @endcode
webmaster@1	2375 */
webmaster@1	2376
webmaster@1	2377 /**
webmaster@1	2378 * Open a new batch.
webmaster@1	2379 *
webmaster@1	2380 * @param $batch
webmaster@1	2381 * An array defining the batch. The following keys can be used:
webmaster@1	2382 * 'operations': an array of function calls to be performed.
webmaster@1	2383 * Example:
webmaster@1	2384 * @code
webmaster@1	2385 * array(
webmaster@1	2386 * array('my_function_1', array($arg1)),
webmaster@1	2387 * array('my_function_2', array($arg2_1, $arg2_2)),
webmaster@1	2388 * )
webmaster@1	2389 * @endcode
webmaster@1	2390 * All the other values below are optional.
webmaster@1	2391 * batch_init() provides default values for the messages.
webmaster@1	2392 * 'title': title for the progress page.
webmaster@1	2393 * Defaults to t('Processing').
webmaster@1	2394 * 'init_message': message displayed while the processing is initialized.
webmaster@1	2395 * Defaults to t('Initializing.').
webmaster@1	2396 * 'progress_message': message displayed while processing the batch.
webmaster@1	2397 * Available placeholders are @current, @remaining, @total and @percent.
webmaster@1	2398 * Defaults to t('Remaining @remaining of @total.').
webmaster@1	2399 * 'error_message': message displayed if an error occurred while processing
webmaster@1	2400 * the batch.
webmaster@1	2401 * Defaults to t('An error has occurred.').
webmaster@1	2402 * 'finished': the name of a function to be executed after the batch has
webmaster@1	2403 * completed. This should be used to perform any result massaging that
webmaster@1	2404 * may be needed, and possibly save data in $_SESSION for display after
webmaster@1	2405 * final page redirection.
webmaster@1	2406 * 'file': the path to the file containing the definitions of the
webmaster@1	2407 * 'operations' and 'finished' functions, for instance if they don't
webmaster@1	2408 * reside in the original '.module' file. The path should be relative to
webmaster@1	2409 * the base_path(), and thus should be built using drupal_get_path().
webmaster@1	2410 *
webmaster@1	2411 * Operations are added as new batch sets. Batch sets are used to ensure
webmaster@1	2412 * clean code independence, ensuring that several batches submitted by
webmaster@1	2413 * different parts of the code (core / contrib modules) can be processed
webmaster@1	2414 * correctly while not interfering or having to cope with each other. Each
webmaster@1	2415 * batch set gets to specify his own UI messages, operates on its own set
webmaster@1	2416 * of operations and results, and triggers its own 'finished' callback.
webmaster@1	2417 * Batch sets are processed sequentially, with the progress bar starting
webmaster@1	2418 * fresh for every new set.
webmaster@1	2419 */
webmaster@1	2420 function batch_set($batch_definition) {
webmaster@1	2421 if ($batch_definition) {
webmaster@1	2422 $batch =& batch_get();
webmaster@1	2423 // Initialize the batch
webmaster@1	2424 if (empty($batch)) {
webmaster@1	2425 $batch = array(
webmaster@1	2426 'sets' => array(),
webmaster@1	2427 );
webmaster@1	2428 }
webmaster@1	2429
webmaster@1	2430 $init = array(
webmaster@1	2431 'sandbox' => array(),
webmaster@1	2432 'results' => array(),
webmaster@1	2433 'success' => FALSE,
webmaster@1	2434 );
webmaster@1	2435 // Use get_t() to allow batches at install time.
webmaster@1	2436 $t = get_t();
webmaster@1	2437 $defaults = array(
webmaster@1	2438 'title' => $t('Processing'),
webmaster@1	2439 'init_message' => $t('Initializing.'),
webmaster@1	2440 'progress_message' => $t('Remaining @remaining of @total.'),
webmaster@1	2441 'error_message' => $t('An error has occurred.'),
webmaster@1	2442 );
webmaster@1	2443 $batch_set = $init + $batch_definition + $defaults;
webmaster@1	2444
webmaster@1	2445 // Tweak init_message to avoid the bottom of the page flickering down after init phase.
webmaster@1	2446 $batch_set['init_message'] .= '<br/> ';
webmaster@1	2447 $batch_set['total'] = count($batch_set['operations']);
webmaster@1	2448
webmaster@1	2449 // If the batch is being processed (meaning we are executing a stored submit handler),
webmaster@1	2450 // insert the new set after the current one.
webmaster@1	2451 if (isset($batch['current_set'])) {
webmaster@1	2452 // array_insert does not exist...
webmaster@1	2453 $slice1 = array_slice($batch['sets'], 0, $batch['current_set'] + 1);
webmaster@1	2454 $slice2 = array_slice($batch['sets'], $batch['current_set'] + 1);
webmaster@1	2455 $batch['sets'] = array_merge($slice1, array($batch_set), $slice2);
webmaster@1	2456 }
webmaster@1	2457 else {
webmaster@1	2458 $batch['sets'][] = $batch_set;
webmaster@1	2459 }
webmaster@1	2460 }
webmaster@1	2461 }
webmaster@1	2462
webmaster@1	2463 /**
webmaster@1	2464 * Process the batch.
webmaster@1	2465 *
webmaster@1	2466 * Unless the batch has been marked with 'progressive' = FALSE, the function
webmaster@1	2467 * issues a drupal_goto and thus ends page execution.
webmaster@1	2468 *
webmaster@1	2469 * This function is not needed in form submit handlers; Form API takes care
webmaster@1	2470 * of batches that were set during form submission.
webmaster@1	2471 *
webmaster@1	2472 * @param $redirect
webmaster@1	2473 * (optional) Path to redirect to when the batch has finished processing.
webmaster@1	2474 * @param $url
webmaster@1	2475 * (optional - should only be used for separate scripts like update.php)
webmaster@1	2476 * URL of the batch processing page.
webmaster@1	2477 */
webmaster@1	2478 function batch_process($redirect = NULL, $url = NULL) {
webmaster@1	2479 $batch =& batch_get();
webmaster@1	2480
webmaster@1	2481 if (isset($batch)) {
webmaster@1	2482 // Add process information
webmaster@1	2483 $url = isset($url) ? $url : 'batch';
webmaster@1	2484 $process_info = array(
webmaster@1	2485 'current_set' => 0,
webmaster@1	2486 'progressive' => TRUE,
webmaster@1	2487 'url' => isset($url) ? $url : 'batch',
webmaster@1	2488 'source_page' => $_GET['q'],
webmaster@1	2489 'redirect' => $redirect,
webmaster@1	2490 );
webmaster@1	2491 $batch += $process_info;
webmaster@1	2492
webmaster@1	2493 if ($batch['progressive']) {
webmaster@1	2494 // Clear the way for the drupal_goto redirection to the batch processing
webmaster@1	2495 // page, by saving and unsetting the 'destination' if any, on both places
webmaster@1	2496 // drupal_goto looks for it.
webmaster@1	2497 if (isset($_REQUEST['destination'])) {
webmaster@1	2498 $batch['destination'] = $_REQUEST['destination'];
webmaster@1	2499 unset($_REQUEST['destination']);
webmaster@1	2500 }
webmaster@1	2501 elseif (isset($_REQUEST['edit']['destination'])) {
webmaster@1	2502 $batch['destination'] = $_REQUEST['edit']['destination'];
webmaster@1	2503 unset($_REQUEST['edit']['destination']);
webmaster@1	2504 }
webmaster@1	2505
webmaster@1	2506 // Initiate db storage in order to get a batch id. We have to provide
webmaster@1	2507 // at least an empty string for the (not null) 'token' column.
webmaster@1	2508 db_query("INSERT INTO {batch} (token, timestamp) VALUES ('', %d)", time());
webmaster@1	2509 $batch['id'] = db_last_insert_id('batch', 'bid');
webmaster@1	2510
webmaster@1	2511 // Now that we have a batch id, we can generate the redirection link in
webmaster@1	2512 // the generic error message.
webmaster@1	2513 $t = get_t();
webmaster@1	2514 $batch['error_message'] = $t('Please continue to <a href="@error_url">the error page</a>', array('@error_url' => url($url, array('query' => array('id' => $batch['id'], 'op' => 'finished')))));
webmaster@1	2515
webmaster@1	2516 // Actually store the batch data and the token generated form the batch id.
webmaster@1	2517 db_query("UPDATE {batch} SET token = '%s', batch = '%s' WHERE bid = %d", drupal_get_token($batch['id']), serialize($batch), $batch['id']);
webmaster@1	2518
webmaster@1	2519 drupal_goto($batch['url'], 'op=start&id='. $batch['id']);
webmaster@1	2520 }
webmaster@1	2521 else {
webmaster@1	2522 // Non-progressive execution: bypass the whole progressbar workflow
webmaster@1	2523 // and execute the batch in one pass.
webmaster@1	2524 require_once './includes/batch.inc';
webmaster@1	2525 _batch_process();
webmaster@1	2526 }
webmaster@1	2527 }
webmaster@1	2528 }
webmaster@1	2529
webmaster@1	2530 /**
webmaster@1	2531 * Retrieve the current batch.
webmaster@1	2532 */
webmaster@1	2533 function &batch_get() {
webmaster@1	2534 static $batch = array();
webmaster@1	2535 return $batch;
webmaster@1	2536 }
webmaster@1	2537
webmaster@1	2538 /**
webmaster@1	2539 * @} End of "defgroup batch".
webmaster@1	2540 */

Mercurial > defr > drupal > core

annotate includes/form.inc @ 15:4347c45bb494 6.7