Commit 75442c96 authored by Dries's avatar Dries

- Patch #802746 by rfay, jhodgdon: document () and form builder function in form_api() group.

parent 9cf21be9
......@@ -29,21 +29,109 @@
* presentation, while simplifying code and reducing the amount of HTML that
* must be explicitly generated by modules.
*
* The drupal_get_form() function handles retrieving and processing an HTML
* form for modules automatically. For example:
* The primary function used with forms is drupal_get_form(), which is
* used for forms presented interactively to a user. Forms can also be built and
* submitted programmatically without any user input using the
* drupal_form_submit() function.
*
* drupal_get_form() handles retrieving, processing, and displaying a rendered
* HTML form for modules automatically.
*
* Here is an example of how to use drupal_get_form() and a form builder
* function:
* @code
* // Display the user registration form.
* $output = drupal_get_form('user_register_form');
* $form = drupal_get_form('my_module_example_form');
* ...
* function my_module_example_form($form, &$form_state) {
* $form['submit'] = array(
* '#type' => 'submit',
* '#value' => t('Submit'),
* );
* }
* function my_module_example_form_validate($form, &$form_state) {
* // Validation logic.
* }
* function my_module_example_form_submit($form, &$form_state) {
* // Submission logic.
* }
* @endcode
*
* Forms can also be built and submitted programmatically without any user input
* using the drupal_form_submit() function.
* Or with any number of additional arguments:
* @code
* $extra = "extra";
* $form = drupal_get_form('my_module_example_form', $extra);
* ...
* function my_module_example_form($form, &$form_state, $extra) {
* $form['submit'] = array(
* '#type' => 'submit',
* '#value' => $extra,
* );
* }
* @endcode
*
* For information on the format of the structured arrays used to define forms,
* and more detailed explanations of the Form API workflow, see the
* @link http://api.drupal.org/api/file/developer/topics/forms_api_reference.html reference @endlink
* and the @link http://api.drupal.org/api/file/developer/topics/forms_api.html quickstart guide. @endlink
* The $form argument to form-related functions is a structured array containing
* the elements and properties of the form. For information on the array
* components and format, and more detailed explanations of the Form API
* 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
* 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.
*
* In the form builder, validation, submission, and other form functions,
* $form_state is the primary influence on the processing of the form and is
* passed by reference to most functions, so they use it to communicate with
* the form system and each other.
*
* The $form_state keys are:
* - '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': 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
* 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.
* - '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'.
*/
/**
......@@ -3211,7 +3299,7 @@ function _form_set_class(&$element, $class = array()) {
* on the progress of the ongoing operations.
*
* The API is primarily designed to integrate nicely with the Form API
* workflow, but can also be used by non-FAPI scripts (like update.php)
* workflow, but can also be used by non-Form API scripts (like update.php)
* or even simple page callbacks (which should probably be used sparingly).
*
* Example:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment