Drupal 6: Creating a multipage form using the Forms API
Recently I’ve been struggling with creating a multi-step CCK node form in Drupal 5. I was able to implement a solution that used a combination of form_alter and jQuery, but due to the amount of jQuery, it was too slow. I then attempted the same functionality in Drupal 6, but due to the number of changes in the Forms API, I decided to take a step back. Here’s my first successful attempt at creating a multi-step form using a Drupal 6 module and the Forms API. The following code adds the ability to jump to any step of the form, save at any point, and dynamically creates steps based on the number of fieldsets. My next step will be transposing this code to work with a CCK node form.
Screenshot:
<?php
function multipage_menu() {
$items = array();
$items['multiStepForm'] = array(
'title' => t('Multi Step Form'),
'page callback' => 'drupal_get_form',
'page arguments' => array('multipage_test_form'),
'access arguments' => array('access content'),
);
return $items;
}
function multipage_test_form(&$form_state) {
// enable/disable debugging output
$form_state['storage']['#navigation']['debugging'] = false;
// per debugging
if ($form_state['storage']['#navigation']['debugging']) echo "<HR>LOADING FUNCTION: multipage_test_form<HR>";
// ensure step is set in storage
if (empty($form_state['storage']['#navigation']['step'])) {
$form_state['storage']['#navigation']['step'] = 1;
} elseif ($form_state['storage']['#navigation']['newStep']) {
// if the form has been submitted, check for a new step
$form_state['storage']['#navigation']['step'] = $form_state['storage']['#navigation']['newStep'];
unset ($form_state['storage']['#navigation']['newStep']);
}
$form = array();
// add form fields
_multipage_test_form_add_fields($form, $form_state);
// calculate max number of steps
_multipage_test_form_max_steps($form, $form_state);
// create tabs
_multipage_test_form_create_tabs($form, $form_state);
// remove form fields per step
_multipage_test_form_remove_fields($form, $form_state);
// add tabs to form
_multipage_test_form_add_tabs($form, $form_state);
// add buttons to form
_multipage_test_form_add_buttons($form, $form_state);
return $form;
}
function _multipage_test_form_add_fields(&$form, &$form_state) {
// per debugging
if ($form_state['storage']['#navigation']['debugging']) echo "<hr> ADDING FIELDS<hr>";
// Fieldset A
$form['fieldset_a'] = array(
'#type' => 'fieldset',
'#title' => t('Fieldset A'),
);
$form['fieldset_a']['textfield_a1'] = array(
'#type' => 'textfield',
'#title' => t('Textfield A1'),
'#default_value' => $form_state['storage']['textfield_a1'],
);
$form['fieldset_a']['textfield_a2'] = array(
'#type' => 'textfield',
'#title' => t('Textfield A2'),
'#default_value' => $form_state['storage']['textfield_a2'],
);
$form['fieldset_a']['textfield_a3'] = array(
'#type' => 'textfield',
'#title' => t('Textfield A3'),
'#default_value' => $form_state['storage']['textfield_a3'],
);
// Fieldset B
$form['fieldset_b'] = array(
'#type' => 'fieldset',
'#title' => t('Fieldset B'),
);
$form['fieldset_b']['textfield_b1'] = array(
'#type' => 'textfield',
'#title' => t('Textfield B1'),
'#default_value' => $form_state['storage']['textfield_b1'],
);
$form['fieldset_b']['textfield_b2'] = array(
'#type' => 'textfield',
'#title' => t('Textfield B2'),
'#default_value' => $form_state['storage']['textfield_b2'],
);
$form['fieldset_b']['textfield_b3'] = array(
'#type' => 'textfield',
'#title' => t('Textfield B3'),
'#default_value' => $form_state['storage']['textfield_b3'],
);
// Fieldset C
$form['fieldset_c'] = array(
'#type' => 'fieldset',
'#title' => t('Fieldset C'),
);
$form['fieldset_c']['textfield_c1'] = array(
'#type' => 'textfield',
'#title' => t('Textfield C1'),
'#default_value' => $form_state['storage']['textfield_c1'],
);
$form['fieldset_c']['textfield_c2'] = array(
'#type' => 'textfield',
'#title' => t('Textfield C2'),
'#default_value' => $form_state['storage']['textfield_c2'],
);
$form['fieldset_c']['textfield_c3'] = array(
'#type' => 'textfield',
'#title' => t('Textfield C3'),
'#default_value' => $form_state['storage']['textfield_c3'],
);
// Fields not in a fieldset
$form['textfield_d1'] = array(
'#type' => 'textfield',
'#title' => t('Textfield D1'),
'#default_value' => $form_state['storage']['textfield_d1'],
);
$form['textfield_d2'] = array(
'#type' => 'textfield',
'#title' => t('Textfield D2'),
'#default_value' => $form_state['storage']['textfield_d2'],
);
$form['textfield_d3'] = array(
'#type' => 'textfield',
'#title' => t('Textfield D3'),
'#default_value' => $form_state['storage']['textfield_d3'],
);
}
function _multipage_test_form_max_steps($form, &$form_state) {
// calculate max stpes if empty
if (empty($form_state['storage']['#navigation']['maxSteps'])) {
$fieldsetCount = 0;
$otherFields = false;
// loop through form elements
foreach ($form as $k => $v) {
// check for fieldset
if (substr($k,0,9)=='fieldset_' && is_array($v) && $v['#type']=='fieldset') {
$fieldsetCount++;
} else {
$otherFields = true;
}
}
// if there are other fields, increment max steps
if ($otherFields) {
$fieldsetCount++;
$form_state['storage']['#navigation']['otherFields'] = true;
}
// add count to storage
$form_state['storage']['#navigation']['maxSteps'] = $fieldsetCount;
}
}
function _multipage_test_form_create_tabs(&$form, &$form_state) {
// per debugging
if ($form_state['storage']['#navigation']['debugging']) echo "<hr> CREATING TABS<hr>";
// create list of tabs if not set in storage
if (empty($form_state['storage']['#navigation']['tabs'])) {
$tabCount = 0;
$tabs = array();
// check for other fields
if ($form_state['storage']['#navigation']['otherFields']) {
$tabsCount++;
$tabs[$tabsCount] = "Start";
}
// loop through form items
foreach ($form as $k => $v) {
if (substr($k,0,9)=='fieldset_' && is_array($v) && $v['#type']=='fieldset') {
$tabsCount++;
$tabs[$tabsCount] = $v['#title'];
}
}
// add tabs to storage
$form_state['storage']['#navigation']['tabs'] = $tabs;
}
}
function _multipage_test_form_remove_fields(&$form, &$form_state) {
// per debugging
if ($form_state['storage']['#navigation']['debugging']) echo "<HR> REMOVING FIELDS<HR>";
// set fieldset counter based on otherfields
if ($form_state['storage']['#navigation']['otherFields']) {
$fieldsetCount = 1;
} else {
$fieldsetCount = 0;
}
// loop though form fields
foreach ($form as $k => $v) {
// ensure this form item is a fieldset
if (substr($k,0,9)=='fieldset_' && is_array($v) && $v['#type']=='fieldset') {
// increment count of fieldsets
$fieldsetCount++;
// unset fieldset
if ($form_state['storage']['#navigation']['step'] != $fieldsetCount) unset($form[$k]);
} elseif (is_array($v) && $form_state['storage']['#navigation']['otherFields'] && $form_state['storage']['#navigation']['step']>1) {
// unset field
unset($form[$k]);
}
}
}
function _multipage_test_form_add_tabs(&$form, $form_state) {
// per debugging
if ($form_state['storage']['#navigation']['debugging']) echo "<HR> ADDING TABS<HR>";
$tabsArray = array();
$tabsCount = 0;
// loop through tabs and create buttons for each one
foreach ($form_state['storage']['#navigation']['tabs'] as $k => $v) {
$tabsCount++;
$tabsArray['tab_'.$k] = array(
'#type' => 'submit',
'#value' => t($v),
'#attributes' => array(
'class' => 'tabs' . ($tabsCount == $form_state['storage']['#navigation']['step'] ? ' active' : '')
),
);
}
// add tab buttons to beginning of form
$form = array_merge($tabsArray, $form);
}
function _multipage_test_form_add_buttons(&$form, &$form_state) {
// per debugging
if ($form_state['storage']['#navigation']['debugging']) echo "<HR> ADDING BUTTONS<HR>";
// add previous button
if ($form_state['storage']['#navigation']['step']>1) {
$form['previous'] = array(
'#type' => 'submit',
'#value' => t('Previous'),
);
}
// add next button
if ($form_state['storage']['#navigation']['step']<$form_state['storage']['#navigation']['maxSteps']) {
$form['next'] = array(
'#type' => 'submit',
'#value' => t('Next'),
);
}
// add save button
$form['submit'] = array(
'#type' => 'submit',
'#value' => t('Save'),
);
}
function multipage_test_form_validate($form, &$form_state) {
// per debugging
if ($form_state['storage']['#navigation']['debugging']) echo "<hr>FORM VALIDATED<hr>";
}
function multipage_test_form_submit($form, &$form_state) {
// per debugging
if ($form_state['storage']['#navigation']['debugging']) echo "<hr>FORM SUBMITTED<hr>";
// loop through submitted form values
foreach ($form_state['values'] as $k => $v) {
// add certain fields to storage
if (substr($k, 0, 10)=='textfield_') {
$form_state['storage'][$k] = $v;
}
}
// handle button action
switch ($form_state['clicked_button']['#value']) {
case 'Previous':
// set the state to rebuild
$form_state['rebuild'] = TRUE;
// set new step
if ($form_state['storage']['#navigation']['step']>1) {
$form_state['storage']['#navigation']['newStep'] = $form_state['storage']['#navigation']['step']-1;
}
break;
case 'Next':
// set the state to rebuild
$form_state['rebuild'] = TRUE;
// set new step
if ($form_state['storage']['#navigation']['step']<$form_state['storage']['#navigation']['maxSteps']) {
$form_state['storage']['#navigation']['newStep'] = $form_state['storage']['#navigation']['step']+1;
}
break;
case 'Save':
// TODO
break;
// tabs
default:
// check if the button value maps to a tab
$key = array_search($form_state['clicked_button']['#value'], $form_state['storage']['#navigation']['tabs']);
if ($key) {
$form_state['storage']['#navigation']['newStep'] = $key;
}
break;
}
}
?>