drupal_redirect_form

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'], 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':

$form_state['redirect'] = 'node';

Or to redirect to 'node/123?foo=bar#baz':

$form_state['redirect'] = array(
  'node/123',
  array(
    'query' => array(
      'foo' => 'bar',
    ),
    'fragment' => 'baz',
  ),
);

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.

Parameters

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

See also

drupal_process_form()

drupal_build_form()

Related topics

Form generation

Functions to enable the processing and display of HTML forms.

2 calls to drupal_redirect_form()

File

includes/form.inc, line 1214

Functions for form and batch generation and processing.

Code

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']);
  }
}