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

annotate includes/form.inc @ 5:2427550111ae 6.2

Drupal 6.2

author	Franck Deroche <webmaster@defr.org>
date	Tue, 23 Dec 2008 14:30:08 +0100
parents	c1f4ac30525a
children	fff6d4c8c043

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

Mercurial > defr > drupal > core

annotate includes/form.inc @ 5:2427550111ae 6.2