$output .= '<div class="delegator-explanation">' . t('Before proceeding, you must configure your new "@type"', array('@type' => $plugin['title'])) . '</div>';
Form wizards, or multi-step forms, are a process by which the user goes through or can use an arbitrary number of different forms to create a single object or perform a single task. Traditionally the multi-step form is difficult in Drupal because there is no easy place to put data in between forms. No longer! The form wizard tool allows a single entry point to easily set up a wizard of multiple forms, provide callbacks to handle data storage and updates between forms and when forms are completed. This tool pairs well with the <ahref="&topic:ctools/object-cache&">object cache</a> tool for storage.
'id' => An id for this multistep. Will be used for things like trail theming.
<h3>The form info array</h3>
'path' => /path/to/form/%step,
The wizard starts with an array of data that describes all of the forms available to the wizard and sets options for how the wizard will present and control the flow. Here is an example of the $form_info array as used in the delegator module:
'return path' => Where to go when exiting the wizard. Required if 'return' is shown.
<pre>
'show trail' => (default false),
$form_info = array(
'show back' => (default false) -- show a back button
'id' => 'delegator_page',
'show return' => (default false) show a return button
The above array starts with an <b>id</b> which is used to identify the wizard in various places and a <b>path</b> which is needed to redirect to the next step between forms. It then creates some <b>settings</b> which control which pieces are displayed. In this case, it displays a form trail and a 'back' button, but not the 'return' button. Then there are the <b>wizard callbacks</b> which allow the wizard to act appropriately when forms are submitted. Finally it contains a <b>list of forms</b> and their <b>order</b> so that it knows which forms to use and what order to use them by default. Note that the keys in the order and list of forms match; that key is called the <b>step</b> and is used to identify each individual step of the wizard.
Here is a full list of every item that can be in the form info array:
<dl>
<dt>id</dt>
<dd>An id for wizard. This will primarily be used for things like trail theming.</dd>
<dt>path</dt>
<dd>The path to use when redirecting between forms. <strong>%step</strong> will be replaced with the key for the form.</dd>
<dt>return path</dt>
<dd>When a form is complete, this is the path to go to. This is required if the 'return' button is shown and not using AJAX. It is also used for the 'Finish' button. If it is not present and needed, the cancel path will also be checked.</dd>
<dt>cancel path</dt>
<dd>When a form is canceled, this is the path to go to. This is required if the 'cancel' is shown and not using AJAX.</dd>
<dt>show trail</dt>
<dd>If set to TRUE, the form trail will be shown like a breadcrumb at the top of each form. Defaults to FALSE.</dd>
<dt>show back</dt>
<dd>If set to TRUE, show a back button on each form. Defaults to FALSE.</dd>
<dt>show return</dt>
<dd>If set to TRUE, show a return button. Defaults to FALSE.</dd>
<dt>show cancel</dt>
<dd>If set to TRUE, show a cancel button. Defaults to FALSE.</dd>
<dt>back text</dt>
<dd>Set the text of the 'back' button. Defaults to t('Back').</dd>
<dt>next text</dt>
<dd>Set the text of the 'next' button. Defaults to t('Continue').</dd>
<dt>return text</dt>
<dd>Set the text of the 'return' button. Defaults to t('Update and return').</dd>
<dt>finish text</dt>
<dd>Set the text of the 'finish' button. Defaults to t('Finish').</dd>
<dt>cancel text</dt>
<dd>Set the text of the 'cancel' button. Defaults to t('Cancel').</dd>
<dt>ajax</dt>
<dd>Turn on AJAX capabilities, using CTools' ajax.inc. Defaults to FALSE.</dd>
<dt>modal</dt>
<dd>Put the wizard in the modal tool. The modal must already be open and called from an ajax button for this to work, which is easily accomplished using functions provided by the modal tool.</dd>
<dt>ajax render</dt>
<dd>A callback to display the rendered form via ajax. This is not required if using the modal tool, but is required otherwise since ajax by itself does not know how to render the results. Params: &$form_state, $output.</dd>
<dt>finish callback</dt>
<dd>The function to call when a form is complete and the finish button has been clicked. This function should finalize all data. Params: &$form_state.</dd>
<dt>cancel callback</dt>
<dd>The function to call when a form is canceled by the user. This function should clean up any data that is cached. Params: &$form_state.</dd>
<dt>return callback</dt>
<dd>The function to call when a form is complete and the return button has been clicked. This is often the same as the finish callback. Params: &$form_state.</dd>
<dt>next callback</dt>
<dd>The function to call when the next button has been clicked. This function should take the submitted data and cache it for later use by the finish callback. Params: &$form_state.</dd>
<dt>order</dt>
<dd>An array of forms, keyed by the step, which represents the default order the forms will be displayed in. Note that submit callbacks can override the order so that branching logic can be used.</dd>
<dt>forms</dt>
<dd>An array of form info arrays, keyed by step, describing every form available to the wizard. Each array contains:
<dl>
<dt>form id</dt>
<dd>The id of the form, as used in the Drupal form system. This is also the name of the function that represents the form builder.</dd>
<dt>include</dt>
<dd>The name of a file to include which contains the code for this form. This makes it easy to include the form wizard in another file or set of files. This must be the full path of the file, so be sure to use drupal_get_path() when setting this. This can also be an array of files if multiple files need to be included.</dd>
<dt>title</dt>
<dd>The title of the form, to be optionally set via drupal_get_title. This is required when using the modal if $form_state['title'] is not set.</dd>
</dl>
</dd>
</dl>
<h3>Invoking the form wizard</h3>
Your module should create a page callback via hook_menu, and this callback should contain an argument for the step. The path that leads to this page callback should be the same as the 'path' set in the $form_info array.
The page callback should set up the $form_info, and figure out what the default step should be if no step is provided (note that the wizard does not do this for you; you MUST specify a step). Then invoke the form wizard:
If using AJAX or the modal, This part is actually done! If not, you have one more small step:
<pre>
return $output;
</pre>
<h3>Forms and their callbacks</h3>
Each form within the wizard is a complete, independent form using Drupal's Form API system. It has a form builder callback as well as submit and validate callbacks and can be form altered. The primary difference between these forms and a normal Drupal form is that the submit handler should not save any data. Instead, it should make any changes to a cached object (usually placed on the $form_state) and only the _finish or _return handler should actually save any real data.
How you handle this is completely up to you. The recommended best practice is to use the CTools Object cache, and a good way to do this is to write a couple of wrapper functions around the cache that look like these example functions:
Using these wrappers, when performing a get_cache operation, it defaults to loading the real object. It then checks to see if another user has this object cached using the ctools_object_cache_test() function, which automatically sets a lock (which can be used to prevent writes later on).
With this set up, the _next, _finish and _cancel callbacks are quite simple:
<pre>
/**
* Callback generated when the add page process is finished.
*/
function delegator_page_add_subtask_finish(&$form_state) {
All that's needed to tie this together is to understand how the changes made it into the cache in the first place. This happened in the various form _submit handlers, which made changes to $form_state['page'] based upon the values set in the form:
<pre>
/**
* Store the values from the basic settings form.
*/
function delegator_page_form_basic_submit(&$form, &$form_state) {
if (!isset($form_state['page']->pid) && empty($form_state['page']->import)) {
