From e8111d956e4e9039714fdee0f854481ea205165a Mon Sep 17 00:00:00 2001
From: webchick <webchick@24967.no-reply.drupal.org>
Date: Tue, 21 Jun 2011 23:11:46 -0700
Subject: [PATCH] Issue #1096448 by bfroehle: Changed drupal_redirect_form()
needs better documentation of form_state['redirect'].
---
includes/form.inc | 32 ++++++++++++++++++++++++++------
1 file changed, 26 insertions(+), 6 deletions(-)
diff --git a/includes/form.inc b/includes/form.inc
index 8f2ee2632eaa..9c2a9c168f62 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
--
GitLab