From c09f78f9ac1935f67e8d0c5ff90187e712382930 Mon Sep 17 00:00:00 2001 From: Nancy Nicoles Date: Thu, 2 Jun 2011 15:37:12 -0500 Subject: [PATCH] Issue #859970 by jn2, rfay: Changed form_state keys docs to eliminate duplication and add missing keys. --- includes/form.inc | 200 +++++++++++++++++++++++++++-------------------------- 1 files changed, 101 insertions(+), 99 deletions(-) diff --git a/includes/form.inc b/includes/form.inc index 8f2ee26..c1a916e 100644 --- a/includes/form.inc +++ b/includes/form.inc @@ -87,27 +87,84 @@ * the form system and each other. * * The $form_state keys are: - * - build_info: Do not change; internal information stored by Form API to be + * - 'always_process': If TRUE and the method is GET, a form_id is not + * necessary. This should only be used on RESTful GET forms that do NOT + * write data, as this could lead to security issues. It is useful so that + * searches do not need to have a form_id in their query arguments to + * trigger the search. + * - 'build_info': Do not change; internal information stored by Form API to be * able to build and rebuild the form: - * - args: A list of arguments used to rebuild the form from cache. - * - files: A list of include files to be loaded to rebuild the form. See - * form_load_include(). - * - 'values': An associative array of values submitted to the form. The - * validation functions and submit functions use this array for nearly all - * their decision making. (Note that - * @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html/7#tree #tree @endlink - * determines whether the values are a flat array or an array whose structure - * parallels the $form array.) + * - 'args': A list of arguments used to rebuild the form from cache. + * - 'files': An optional array defining include files that need to be loaded + * for building the form. See form_load_include(). Each array entry may be + * the path to a file or another array containing values for the parameters + * 'type', 'module' and 'name' as needed by module_load_include(). The files + * listed here are automatically loaded by form_get_cache(). By default the + * current menu router item's 'file' definition is added, if it exists. + * - 'buttons': An array of names of the buttons in the form. + * - 'cache': The typical form workflow involves two page requests. During the + * first page request, a form is built and returned for the user to fill in. + * Then the user fills the form in and submits it, triggering a second page + * request in which the form must be built and processed. By default, $form + * and $form_state are built from scratch during each of these page requests. + * In some special use-cases, it is necessary or desired to persist the $form + * and $form_state variables from the initial page request to the one that + * processes the submission. A form builder function can set 'cache' to TRUE + * to do this. One example where this is needed is to handle Ajax submissions, + * so ajax_process_form() sets this for all forms that include an element with + * a #ajax property. (In Ajax, the handler has no way to build the form + * itself, so must rely on the cached version created on each page load. It's + * a classic example of this use case.) Note that the persistence of $form + * and $form_state across successive submissions of a multi-step form happens + * automatically regardless of the value for 'cache'. + * - 'complete form': Copy of the complete form; same as $form. + * - 'executed': Boolean flag. If TRUE, the form has been processed and + * executed. Defaults to FALSE. + * - 'groups': Array for handling fieldsets, including vertical tabs. + * - 'has_file_element': Boolean flag. If TRUE, there is a file element and + * Drupal will set the form encoding. + * - 'input': The array of values as they were submitted by the user. These are + * raw and unvalidated, so should not be used without a thorough understanding + * of security implications. In almost all cases, code should use the data in + * the 'values' array exclusively. The most common use of this key is for + * multi-step forms that need to clear some of the user input when setting + * 'rebuild'. The values correspond to $_POST or $_GET, depending on the + * 'method' chosen (see below). + * - 'method': The HTTP form method to use for finding the input for this form. + * May be 'post' or 'get'. Defaults to 'post'. Note that 'get' method + * forms do not use form ids so are always considered to be submitted, which + * can have unexpected effects. The 'get' method should only be used on + * forms that do not change data, as that is exclusively the domain of 'post'. + * - 'must_validate': Ordinarily, a form is only validated once, but there are + * times when a form is resubmitted internally and should be validated + * again. Setting this to TRUE will force that to happen. This is most + * likely to occur during Ajax operations. + * - 'no_cache': If set to TRUE the form will NOT be cached, even if 'cache' is + * set. + * - 'no_redirect': If set to TRUE the form will NOT perform a drupal_goto(), + * even if 'redirect' is set. + * - 'process_input': Boolean flag. TRUE signifies correct form submission. + * This is always TRUE for programmed forms coming from drupal_form_submit() + * (see 'programmed' key), or if the form_id coming from the $_POST data is + * set and matches the current form_id. + * - 'programmed': Boolean flag. If TRUE, form was submitted programmatically, + * usually invoked via drupal_form_submit(). Defaults to FALSE. * - 'rebuild': If the submit function sets $form_state['rebuild'] to TRUE, * submission is not completed and instead the form is rebuilt using any * information that the submit function has made available to the form builder * function via $form_state. This is commonly used for wizard-style - * multi-step forms, add-more buttons, and the like. For further information - * see drupal_build_form(). + * multi-step forms, add-more buttons, and the like. Normally, + * $form_state['rebuild'] is set by a submit handler, since it is usually + * logic within a submit handler that determines whether a form is complete or + * requires another step. However, a validation handler may set + * $form_state['rebuild'] to cause form processing to bypass submit handlers + * and rebuild the form instead, even without validation errors. For further + * information see drupal_build_form(). + * - 'rebuild_info': * - 'redirect': a URL that will be used to redirect the form on submission. * See drupal_redirect_form() for complete information. * - 'storage': $form_state['storage'] is not a special key, and no specific - * support is provided for it in the Form API, but by tradition it was + * support is provided for it in the Form API. By tradition it was * the location where application-specific data was stored for communication * between the submit, validation, and form builder functions, especially * in a multi-step-style form. Form implementations may use any key(s) within @@ -119,38 +176,37 @@ * editing forms to store information about the node being edited, and this * information stays available across successive clicks of the "Preview" * button as well as when the "Save" button is finally clicked. - * - 'temporary': Since values for all non-reserved keys in $form_state persist - * throughout a multistep form sequence, the Form API provides the 'temporary' + * - 'submitted': Boolean. If TRUE, form has been submitted. Defaults to FALSE. + * - 'temporary': An array holding temporary data accessible during the current + * page request only. Since values for all non-reserved keys in $form_state + * persist throughout a multistep form sequence, the Form API provides this * key for modules to use for communicating information across form-related - * functions during a single page request only. There is no use-case for this + * functions during a single page request. There is no use-case for this * functionality in core. * - 'triggering_element': (read-only) The form element that triggered * submission. This is the same as the deprecated * $form_state['clicked_button']. It is the element that caused submission, - * which may or may not be a button (in the case of Ajax forms.) This is + * which may or may not be a button (in the case of Ajax forms). This key is * often used to distinguish between various buttons in a submit handler, * and is also used in Ajax handlers. - * - 'cache': The typical form workflow involves two page requests. During the - * first page request, a form is built and returned for the user to fill in. - * Then the user fills the form in and submits it, triggering a second page - * request in which the form must be built and processed. By default, $form - * and $form_state are built from scratch during each of these page requests. - * In some special use-cases, it is necessary or desired to persist the $form - * and $form_state variables from the initial page request to the one that - * processes the submission. A form builder function can set 'cache' to TRUE - * to do this. One example where this is needed is to handle Ajax submissions, - * so ajax_process_form() sets this for all forms that include an element with - * a #ajax property. (In Ajax, the handler has no way to build the form - * itself, so must rely on the cached version created on each page load, so - * it's a classic example of this use case.) Note that the persistence of - * $form and $form_state across successive submissions of a multi-step form - * happens automatically regardless of the value for 'cache'. - * - 'input': The array of values as they were submitted by the user. These are - * raw and unvalidated, so should not be used without a thorough understanding - * of security implications. In almost all cases, code should use the data in - * the 'values' array exclusively. The most common use of this key is for - * multi-step forms that need to clear some of the user input when setting - * 'rebuild'. + * - 'values': An associative array of values submitted to the form. The + * validation functions and submit functions use this array for nearly all + * their decision making. (Note that + * @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html/7#tree #tree @endlink + * determines whether the values are a flat array or an array whose structure + * parallels the $form array.) + * - 'wrapper_callback': Modules that wish to pre-populate certain forms with + * common elements, such as back/next/save buttons in multi-step form + * wizards, may define a form builder function name that returns a form + * structure, which is passed on to the actual form builder function. + * Such implementations may either define the 'wrapper_callback' via + * hook_forms() or invoke drupal_build_form() (instead of + * drupal_get_form()) on their own in a custom menu callback to prepare + * $form_state. See drupal_build_form(). + * + * A discussion of how the values of certain $form_state keys affect + * redirection behavior after form submission may be found in + * drupal_redirect_form(). */ /** @@ -207,67 +263,13 @@ function drupal_get_form($form_id) { * when the form submission process is complete. Furthermore, it may be used * to store information related to the processed data in the form, which will * persist across page requests when the 'cache' or 'rebuild' flag is set. - * The following parameters may be set in $form_state to affect how the form - * is rendered: - * - build_info: A keyed array of build information that is necessary to - * rebuild the form from cache when the original context may no longer be - * available: - * - args: An array of arguments to pass to the form builder. - * - files: An optional array defining include files that need to be loaded - * for building the form. Each array entry may be the path to a file or - * another array containing values for the parameters 'type', 'module' and - * 'name' as needed by module_load_include(). The files listed here are - * automatically loaded by form_get_cache(). By default the current menu - * router item's 'file' definition is added, if existent. - * - rebuild: Normally, after the entire form processing is completed and - * submit handlers ran, a form is considered to be done and - * drupal_redirect_form() will redirect the user to a new page using a GET - * request (so a browser refresh does not re-submit the form). However, if - * 'rebuild' has been set to TRUE, then a new copy of the form is - * immediately built and sent to the browser; instead of a redirect. This is - * used for multi-step forms, such as wizards and confirmation forms. - * Normally, $form_state['rebuild'] is set by a submit handler, since it is - * usually logic within a submit handler that determines whether a form is - * done or requires another step. However, a validation handler may already - * set $form_state['rebuild'] to cause the form processing to bypass submit - * handlers and rebuild the form instead, even if there are no validation - * errors. - * - input: An array of input that corresponds to $_POST or $_GET, depending - * on the 'method' chosen (see below). - * - method: The HTTP form method to use for finding the input for this form. - * May be 'post' or 'get'. Defaults to 'post'. Note that 'get' method - * forms do not use form ids so are always considered to be submitted, which - * can have unexpected effects. The 'get' method should only be used on - * forms that do not change data, as that is exclusively the domain of post. - * - no_redirect: If set to TRUE the form will NOT perform a drupal_goto(), - * even if 'redirect' is set. - * - cache: If set to TRUE the original, unprocessed form structure will be - * cached, which allows to rebuild the entire form from cache. - * - no_cache: If set to TRUE the form will NOT be cached, even if 'cache' is - * set. - * - always_process: If TRUE and the method is GET, a form_id is not - * necessary. This should only be used on RESTful GET forms that do NOT - * write data, as this could lead to security issues. It is useful so that - * searches do not need to have a form_id in their query arguments to - * trigger the search. - * - must_validate: Ordinarily, a form is only validated once but there are - * times when a form is resubmitted internally and should be validated - * again. Setting this to TRUE will force that to happen. This is most - * likely to occur during AHAH or Ajax operations. - * - temporary: An array holding temporary data accessible during the current - * page request only. It may be used to temporary save any data that doesn't - * need to or shouldn't be cached during the whole form workflow, e.g. data - * that needs to be accessed during the current form build process only. - * - wrapper_callback: Modules that wish to pre-populate certain forms with - * common elements, such as back/next/save buttons in multi-step form - * wizards, may define a form builder function name that returns a form - * structure, which is passed on to the actual form builder function. - * Such implementations may either define the 'wrapper_callback' via - * hook_forms() or have to invoke drupal_build_form() (instead of - * drupal_get_form()) on their own in a custom menu callback to prepare - * $form_state accordingly. - * Further $form_state properties controlling the redirection behavior after - * form submission may be found in drupal_redirect_form(). + * + * The various $form_state keys are enumerated in + * @link form_api Form Generation @endlink. + * + * A discussion of how the values of certain $form_state keys affect + * redirection behavior after form submission may be found in + * drupal_redirect_form(). * * @return * The rendered form or NULL, depending upon the $form_state flags that were set. -- 1.7.1