From 75442c9675cc2c2656f382431320b54696cd7dfc Mon Sep 17 00:00:00 2001
From: Dries Buytaert <dries@buytaert.net>
Date: Tue, 15 Jun 2010 15:52:04 +0000
Subject: [PATCH] - Patch #802746 by rfay, jhodgdon: document () and form
builder function in form_api() group.
---
includes/form.inc | 110 +++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 99 insertions(+), 11 deletions(-)
diff --git a/includes/form.inc b/includes/form.inc
index 445a911a7100..11e8c686c632 100644
--- a/includes/form.inc
+++ b/includes/form.inc
@@ -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:
--
GitLab