From b5ff7dd4134ca457d24c9fd6e553ab914771e2d2 Mon Sep 17 00:00:00 2001
From: Dries Buytaert <dries@buytaert.net>
Date: Wed, 16 Jun 2010 05:06:15 +0000
Subject: [PATCH] - Patch #802746 by effulgentsia: documentation fixes.
---
includes/form.inc | 17 ++++++++++++++++-
1 file changed, 16 insertions(+), 1 deletion(-)
diff --git a/includes/form.inc b/includes/form.inc
index 11e8c686c632..a115bf09be25 100644
--- a/includes/form.inc
+++ b/includes/form.inc
@@ -47,6 +47,7 @@
* '#type' => 'submit',
* '#value' => t('Submit'),
* );
+ * return $form;
* }
* function my_module_example_form_validate($form, &$form_state) {
* // Validation logic.
@@ -66,6 +67,7 @@
* '#type' => 'submit',
* '#value' => $extra,
* );
+ * return $form;
* }
* @endcode
*
@@ -104,7 +106,20 @@
* 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.
+ * 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,
--
GitLab