drupal_redirect_form

Versions
5 – 6
drupal_redirect_form($form, $redirect = NULL)
7
drupal_redirect_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.

There are several triggers that may prevent a redirection though:

  • If $form_state['redirect'] is FALSE, a form builder function or form validation/submit handler does not want a user to be redirected, which means that drupal_goto() is not invoked. For most forms, the redirection logic will be the same regardless of whether $form_state['redirect'] is undefined or FALSE. However, in case it was not defined and the current request contains a 'destination' query string, drupal_goto() will redirect to that given destination instead. Only setting $form_state['redirect'] to FALSE will prevent any redirection.
  • If $form_state['no_redirect'] is TRUE, then the callback that originally built the form explicitly disallows any redirection, regardless of the redirection value in $form_state['redirect']. For example, ajax_get_form() defines $form_state['no_redirect'] when building a form in an AJAX callback to prevent any redirection. $form_state['no_redirect'] should NOT be altered by form builder functions or form validation/submit handlers.
  • If $form_state['programmed'] is TRUE, the form submission was usually invoked via drupal_form_submit(), so any redirection would break the script that invoked drupal_form_submit().
  • If $form_state['rebuild'] is TRUE, the form needs to be rebuilt without redirection.

See also

drupal_process_form()

@see drupal_build_form()

Parameters

$form_state A keyed array containing the current state of the form.

Related topics

▾ 3 functions call drupal_redirect_form()

drupal_process_form in includes/form.inc
Processes a form submission.
openid_authentication in modules/openid/openid.module
Authenticate a user or attempt registration.
_batch_finished in includes/batch.inc
End the batch processing.

Code

includes/form.inc, line 784

<?php
function drupal_redirect_form($form_state) {
  // Skip redirection for form submissions invoked via drupal_form_submit().
  if (!empty($form_state['programmed'])) {
    return;
  }
  // Skip redirection if rebuild is activated.
  if (!empty($form_state['rebuild'])) {
    return;
  }
  // Skip redirection if it was explicitly disallowed.
  if (!empty($form_state['no_redirect'])) {
    return;
  }
  // Only invoke drupal_goto() if redirect value was not set to FALSE.
  if (!isset($form_state['redirect']) || $form_state['redirect'] !== FALSE) {
    if (isset($form_state['redirect'])) {
      if (is_array($form_state['redirect'])) {
        call_user_func_array('drupal_goto', $form_state['redirect']);
      }
      else {
        // This function can be called from the installer, which guarantees
        // that $redirect will always be a string, so catch that case here
        // and use the appropriate redirect function.
        $function = drupal_installation_attempted() ? 'install_goto' : 'drupal_goto';
        $function($form_state['redirect']);
      }
    }
    drupal_goto($_GET['q']);
  }
}
?>
Login or register to post comments
 
 

All source code and documentation on this site is released under the terms of the GNU General Public License, version 2 and later. Drupal is a registered trademark of Dries Buytaert.