Creating a wizard

by Gisle Hannemyr

This chapter is a tutorial about designing a wizard based on ctools modal forms.

Table of contents

Drupal projects discussed in this chapter: Chaos tool suite.

Introduction

A wizard is an interaction pattern that is used to guide a user through a complex or infrequent workflow.

About wizards:

Sources:

When you create a Drupal content type, Drupal will automatically create a single page form to create content of that type.

If you need a more complex workflow to create content, a wizard is probably what you need.

The functions

This tutorial only shows the functions. To see the code, visit the sandbox Wizard Demo.

We start by implementing hook_menu(). Two pages are registered with the menu system: The page of the multi-step form and and the start page.

function wizard_demo_menu() {
  …
}

Then, create a callback page that will be the state page of the wizard. We populate this with a render array.

function wizard_demo_start() {
  …
}

Then, setup multistep processing. This function sets up the order, and handles form processing.

function wizard_demo_form($js = NULL, $step = NULL) {
  …
}

We need some place to keep the interim results in. For this we use the object-cache provided by Ctools.

function wizard_demo_cache_clear($id) {
  …
}

function wizard_demo_cache_set($id, $object) {
  …
}

function wizard_demo_cache_get($id) {
  …
}

We also need separate functions reserved for “Continue”, “Cancel” and “Finish” buttons.

function wizard_demo_wizard_next(&$form_state) {
  …
}

function wizard_demo_wizard_cancel(&$form_state) {
  …
}

function wizard_demo_wizard_finish(&$form_state) {
  …
}

Create the forms. In the demo module, there are 4 forms (with names using enumerators “first” to “fourth”). Each form require two functions, one to populate the form, and one submit handler.

function wizard_demo_form_first($form, &$form_state) {
  …
}

function wizard_demo_form_first_submit($form, &$form_state) {
  …
}

Finally, craete a function to return form results.

function wizard_demo_get_result($object) {
  …
}

Final word

[TBA]

Last update: 2019-05-11 [gh].