Issue #1096448 by bfroehle: Changed drupal_redirect_form() needs better documentation of form_state['redirect'].

1 files changed, 26 insertions, 6 deletions

diff --git a/includes/form.inc b/includes/form.inc
index b024918a3..38ef41cf0 100644
--- a/includes/form.inc
+++ b/includes/form.inc
@@ -104,8 +104,10 @@
  *   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.
+ * - '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
@@ -1128,10 +1130,28 @@ function drupal_validate_form($form_id, &$form, &$form_state) {
  * Redirects the user to a URL after a form has been processed.
  *
  * After a form was executed, the data in $form_state controls whether the form
- * is redirected. By default, we redirect to a new destination page. The path of
- * the destination page can be set in $form_state['redirect']. If that is not
- * set, the user is redirected to the current page to display a fresh,
- * unpopulated copy of the form.
+ * is redirected. By default, we redirect to a new destination page. The path
+ * of the destination page can be set in $form_state['redirect'], as either a
+ * string containing the destination or an array of arguments compatible with
+ * drupal_goto(). If that is not set, the user is redirected to the current
+ * page to display a fresh, unpopulated copy of the form.
+ *
+ * For example, to redirect to 'node':
+ * @code
+ * $form_state['redirect'] = 'node';
+ * @endcode
+ * Or to redirect to 'node/123?foo=bar#baz':
+ * @code
+ * $form_state['redirect'] = array(
+ *   'node/123',
+ *   array(
+ *     'query' => array(
+ *       'foo' => 'bar',
+ *     ),
+ *     'fragment' => 'baz',
+ *   ),
+ * );
+ * @endcode
  *
  * There are several triggers that may prevent a redirection though:
  * - If $form_state['redirect'] is FALSE, a form builder function or form