Skip to content
GitLab
Projects
Groups
Snippets
Help
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Sign in
Toggle navigation
D
drupal
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Locked Files
Custom Issue Tracker
Custom Issue Tracker
Labels
Merge Requests
222
Merge Requests
222
Requirements
Requirements
List
Security & Compliance
Security & Compliance
Dependency List
License Compliance
Analytics
Analytics
Code Review
Insights
Issue
Repository
Value Stream
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Commits
Open sidebar
project
drupal
Commits
6bde912a
Commit
6bde912a
authored
Sep 28, 2011
by
catch
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Issue
#859970
by jn2, sun, rfay: Cleanup form_api() () docs.
parent
72656c79
Changes
1
Hide whitespace changes
Inline
Side-by-side
Showing
1 changed file
with
99 additions
and
88 deletions
+99
-88
includes/form.inc
includes/form.inc
+99
-88
No files found.
includes/form.inc
View file @
6bde912a
...
...
@@ -76,7 +76,7 @@
* workflow, see the
* @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html Form API reference @endlink
* and the
* @link http://drupal.org/node/37775 Form API
section of the handbook
. @endlink
* @link http://drupal.org/node/37775 Form API
documentation section
. @endlink
* In addition, there is a set of Form API tutorials in
* @link form_example_tutorial.inc the Form Example Tutorial @endlink which
* provide basics all the way up through multistep forms.
...
...
@@ -86,73 +86,7 @@
* passed by reference to most functions, so they use it to communicate with
* the form system and each other.
*
* The $form_state keys are:
* - 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.)
* - '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().
* - 'redirect': $form_state['redirect'] is used to redirect the form on
* submission. It may either be a string containing the destination URL, or
* an array of arguments compatible with drupal_goto(). 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
* 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
* $form_state (other than the keys listed here and other reserved ones used
* by Form API internals) for this kind of storage. The recommended way to
* ensure that the chosen key doesn't conflict with ones used by the Form API
* or other modules is to use the module name as the key name or a prefix for
* the key name. For example, the Node module uses $form_state['node'] in node
* 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'
* 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
* 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
* 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'.
* See drupal_build_form() for documentation of $form_state keys.
*/
/**
...
...
@@ -211,22 +145,25 @@ function drupal_get_form($form_id) {
* 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 b
e
* available:
* - args: A
n array of arguments to pass to the form builde
r.
* - build_info:
Internal. An associative array of information stored by Form
*
API that is necessary to build and rebuild the form from cache when th
e
*
original context may no longer be
available:
* - args: A
list of arguments to pass to the form constructo
r.
* - 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.
* router item's 'file' definition is added, if any. Use
* form_load_include() to add include files from a form constructor.
* - rebuild_info: Internal. Similar to 'build_info', but pertaining to
* drupal_rebuild_form().
* - rebuild: Normally, after the entire form processing is completed and
* submit handlers
ra
n, a form is considered to be done and
* submit handlers
have ru
n, 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
* 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
...
...
@@ -234,32 +171,106 @@ function drupal_get_form($form_id) {
* 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).
* - redirect: Used to redirect the form on submission. It may either be a
* string containing the destination URL, or an array of arguments
* compatible with drupal_goto(). See drupal_redirect_form() for complete
* information.
* - no_redirect: If set to TRUE the form will NOT perform a drupal_goto(),
* even if 'redirect' is set.
* - 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.
* forms that do not change data, as that is exclusively the domain of
* 'post.'
* - cache: If set to TRUE the original, unprocessed form structure will be
* cached, which allows to rebuild the entire form from cache.
* cached, which allows the entire form to be rebuilt from cache. A typical
* form workflow involves two page requests; first, a form is built and
* rendered 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. Often, 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. 'cache' can be set
* to TRUE to do this. A prominent example is an Ajax-enabled form, in which
* ajax_process_form() enables form caching for all forms that include an
* element with the #ajax property. (The Ajax handler has no way to build
* the form itself, so must rely on the cached version.) Note that the
* persistence of $form and $form_state happens automatically for
* (multi-step) forms having the 'rebuild' flag set, regardless of the value
* for 'cache'.
* - no_cache: If set to TRUE the form will NOT be cached, even if 'cache' is
* set.
* - 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.)
* - 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.
* - 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
* - 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.
* likely to occur during Ajax operations.
* - programmed: If TRUE, the form was submitted programmatically, usually
* invoked via drupal_form_submit(). Defaults to FALSE.
* - 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.
* - submitted: If TRUE, the form has been submitted. Defaults to FALSE.
* - executed: If TRUE, the form was submitted and has been processed and
* executed. Defaults to FALSE.
* - 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 key is
* often used to distinguish between various buttons in a submit handler,
* and is also used in Ajax handlers.
* - has_file_element: Internal. If TRUE, there is a file element and Form API
* will set the appropriate 'enctype' HTML attribute on the form.
* - groups: Internal. An array containing references to fieldsets to render
* them within vertical tabs.
* - storage: $form_state['storage'] is not a special key, and no specific
* 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 $form_state (other than the keys listed here and other reserved
* ones used by Form API internals) for this kind of storage. The
* recommended way to ensure that the chosen key doesn't conflict with ones
* used by the Form API or other modules is to use the module name as the
* key name or a prefix for the key name. For example, the Node module uses
* $form_state['node'] in node 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.
* - buttons: A list containing copies of all submit and button elements in
* the form.
* - complete_form: A reference to the $form variable containing the complete
* form structure. #process, #after_build, #element_validate, and other
* handlers being invoked on a form element may use this reference to access
* other information in the form the element is contained in.
* - 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.
* page request only. All $form_state properties that are not reserved keys
* (see form_state_keys_no_cache()) persist throughout a multistep form
* sequence. Form API provides this key for modules to communicate
* information across form-related functions during a single page request.
* It may be used to temporarily save data that does not need to or should
* not be cached during the whole form workflow; e.g., data that needs to be
* accessed during the current form build process only. There is no use-case
* for this functionality in Drupal core.
* - 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
...
...
@@ -268,8 +279,8 @@ function drupal_get_form($form_id) {
* 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().
*
Information on how certain $form_state properties control redirection
*
behavior after
form submission may be found in drupal_redirect_form().
*
* @return
* The rendered form. This function may also perform a redirect and hence may
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment