function ctools_wizard_multistep_form in Chaos Tool Suite (ctools) 6

Same name and namespace in other branches

1. 7 includes/wizard.inc \ctools_wizard_multistep_form()

Display a multi-step form.

Aside from the addition of the $form_info which contains an array of information and configuration so the multi-step wizard can do its thing, this function works a lot like ctools_build_form.

Remember that the form builders for this form will receive &$form, &$form_state, NOT just &$form_state and no additional args.

Do NOT use #required => TRUE with these forms as that validation cannot be skipped for the CANCEL button.

Parameters

$form_info: An array of form info. @todo document the array.

$step: The current form step.

&$form_state: The form state array; this is a reference so the caller can get back whatever information the form(s) involved left for it.

8 calls to ctools_wizard_multistep_form()

ctools_ajax_sample_animal in ctools_ajax_sample/ctools_ajax_sample.module

A modal login callback.

ctools_content_form in includes/content.inc

Get the config form.

ctools_export_ui::edit_execute_form_wizard in plugins/export_ui/ctools_export_ui.class.php

Execute the wizard for editing.

ctools_stylizer_edit_style in includes/stylizer.inc

Add a new style of the specified type.

page_manager_page_add_subtask in page_manager/plugins/tasks/page.admin.inc

Page callback to add a subtask.

... See full list

File

includes/wizard.inc, line 48

CTools' multi-step form wizard tool.

Code

function ctools_wizard_multistep_form($form_info, $step, &$form_state) {

  // allow order array to be optional
  if (empty($form_info['order'])) {
    foreach ($form_info['forms'] as $step_id => $params) {
      $form_info['order'][$step_id] = $params['title'];
    }
  }
  if (!isset($step)) {
    $keys = array_keys($form_info['order']);
    $step = array_shift($keys);
  }
  ctools_wizard_defaults($form_info);
  $form_state['step'] = $step;
  $form_state['form_info'] = $form_info;

  // Ensure we have form information for the current step.
  if (!isset($form_info['forms'][$step])) {
    return;
  }

  // Ensure that whatever include file(s) were requested by the form info are
  // actually included.
  $info = $form_info['forms'][$step];
  if (!empty($info['include'])) {
    if (is_array($info['include'])) {
      foreach ($info['include'] as $file) {
        require_once './' . $file;
      }
    }
    else {
      require_once './' . $info['include'];
    }
  }

  // This tells ctools_build_form to apply our wrapper to the form. It
  // will give it buttons and the like.
  $form_state['wrapper callback'] = 'ctools_wizard_wrapper';
  if (!isset($form_state['rerender'])) {
    $form_state['rerender'] = FALSE;
  }
  $form_state['no_redirect'] = TRUE;
  ctools_include('form');
  $output = ctools_build_form($info['form id'], $form_state);
  if (empty($form_state['executed']) || !empty($form_state['rerender'])) {
    if (empty($form_state['title']) && !empty($info['title'])) {
      $form_state['title'] = $info['title'];
    }
    if (!empty($form_state['ajax render'])) {

      // Any include files should already be included by this point:
      return $form_state['ajax render']($form_state, $output);
    }

    // Automatically use the modal tool if set to true.
    if (!empty($form_state['modal']) && empty($form_state['modal return'])) {
      ctools_include('modal');

      // This overwrites any previous commands.
      $form_state['commands'] = ctools_modal_form_render($form_state, $output);
    }
  }
  if (!empty($form_state['executed'])) {

    // We use the plugins get_function format because it's powerful and
    // not limited to just functions.
    ctools_include('plugins');
    if (isset($form_state['clicked_button']['#wizard type'])) {
      $type = $form_state['clicked_button']['#wizard type'];

      // If we have a callback depending upon the type of button that was
      // clicked, call it.
      if ($function = ctools_plugin_get_function($form_info, "{$type} callback")) {
        $function($form_state);
      }

      // If the modal is in use, some special code for it:
      if (!empty($form_state['modal']) && empty($form_state['modal return'])) {
        if ($type != 'next') {

          // Automatically dismiss the modal if we're not going to another form.
          ctools_include('modal');
          $form_state['commands'][] = ctools_modal_command_dismiss();
        }
      }
    }
    if (empty($form_state['ajax'])) {

      // redirect, if one is set.
      if ($form_state['redirect']) {
        return drupal_redirect_form(array(), $form_state['redirect']);
      }
    }
    else {
      if (isset($form_state['ajax next'])) {

        // Clear a few items off the form state so we don't double post:
        $next = $form_state['ajax next'];
        unset($form_state['ajax next']);
        unset($form_state['executed']);
        unset($form_state['post']);
        unset($form_state['next']);
        return ctools_wizard_multistep_form($form_info, $next, $form_state);
      }
    }

    // If the callbacks wanted to do something besides go to the next form,
    // it needs to have set $form_state['commands'] with something that can
    // be rendered.
  }

  // Render ajax commands if we have any.
  if (isset($form_state['ajax']) && !empty($form_state['commands'])) {
    return ctools_ajax_render($form_state['commands']);
  }

  // Otherwise, return the output.
  return $output;
}