123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325 |
- <?php
- /**
- * @file
- * Extensible wizard form example.
- */
- /**
- * Extensible wizard form example.
- *
- * This is an example of a multistep form using a wizard style. It will include
- * the 'Previous' and 'Next' buttons when required, and a 'Finish' button at the
- * last stage of the form submission.
- *
- * This example is an extensible skeleton that can include (even
- * programmatically) more steps. The demonstration form includes three steps,
- * each step having its own validation functions.
- *
- * How to extend this example:
- * - Steps are defined in the _form_example_steps() function. Include or alter
- * the steps as you require.
- * - For each step, implement the corresponding 'form' function (see
- * 'form_example_wizard_personal_info' for the first step in this example.)
- * Each step is a regular form, and the wizard collects all the values of the
- * included forms.
- * - Optionally, you may include custom validation functions using the regular
- * validation hook (formname_validate). The wizard uses these validation
- * functions for each step.
- * - The most important customization step is to change the submit handler and
- * do whatever you want with the collected information. In this case, the
- * example just shows the collected values in the various steps.
- * @ingroup form_example
- */
- /**
- * Returns the list of steps and their associated forms.
- *
- * This has been separated to clarify and easy the understanding of this
- * example. You should edit this function to include the steps your
- * wizard/multistep form requires.
- *
- * @return array
- * List of steps and their forms.
- *
- * @ingroup form_example
- */
- function _form_example_steps() {
- return array(
- 1 => array(
- 'form' => 'form_example_wizard_personal_info',
- ),
- 2 => array(
- 'form' => 'form_example_wizard_location_info',
- ),
- 3 => array(
- 'form' => 'form_example_wizard_other_info',
- ),
- );
- }
- /**
- * The primary formbuilder function for the wizard form.
- *
- * This is the form that you should call with drupal_get_form() from your code,
- * and it will include the rest of the step forms defined. You are not required
- * to change this function, as this will handle all the step actions for you.
- *
- * This form has two defined submit handlers to process the different steps:
- * - Previous: handles the way to get back one step in the wizard.
- * - Next: handles each step form submission,
- *
- * The third handler, the finish button handler, is the default form_submit
- * handler used to process the information.
- *
- * You are not required to change the next or previous handlers, but you must
- * change the form_example_wizard_submit handler to perform the operations you
- * need on the collected information.
- *
- * @ingroup form_example
- */
- function form_example_wizard($form, &$form_state) {
- // Initialize a description of the steps for the wizard.
- if (empty($form_state['step'])) {
- $form_state['step'] = 1;
- // This array contains the function to be called at each step to get the
- // relevant form elements. It will also store state information for each
- // step.
- $form_state['step_information'] = _form_example_steps();
- }
- $step = &$form_state['step'];
- drupal_set_title(t('Extensible Wizard: Step @step', array('@step' => $step)));
- // Call the function named in $form_state['step_information'] to get the
- // form elements to display for this step.
- $form = $form_state['step_information'][$step]['form']($form, $form_state);
- // Show the 'previous' button if appropriate. Note that #submit is set to
- // a special submit handler, and that we use #limit_validation_errors to
- // skip all complaints about validation when using the back button. The
- // values entered will be discarded, but they will not be validated, which
- // would be annoying in a "back" button.
- if ($step > 1) {
- $form['prev'] = array(
- '#type' => 'submit',
- '#value' => t('Previous'),
- '#name' => 'prev',
- '#submit' => array('form_example_wizard_previous_submit'),
- '#limit_validation_errors' => array(),
- );
- }
- // Show the Next button only if there are more steps defined.
- if ($step < count($form_state['step_information'])) {
- // The Next button should be included on every step.
- $form['next'] = array(
- '#type' => 'submit',
- '#value' => t('Next'),
- '#name' => 'next',
- '#submit' => array('form_example_wizard_next_submit'),
- );
- }
- else {
- // Just in case there are no more steps, we use the default submit handler
- // of the form wizard. Call this button Finish, Submit, or whatever you
- // want to show. When this button is clicked, the
- // form_example_wizard_submit handler will be called.
- $form['finish'] = array(
- '#type' => 'submit',
- '#value' => t('Finish'),
- );
- }
- // Include each validation function defined for the different steps.
- if (function_exists($form_state['step_information'][$step]['form'] . '_validate')) {
- $form['next']['#validate'] = array($form_state['step_information'][$step]['form'] . '_validate');
- }
- return $form;
- }
- /**
- * Submit handler for the "previous" button.
- *
- * This function:
- * - Stores away $form_state['values']
- * - Decrements the step counter
- * - Replaces $form_state['values'] with the values from the previous state.
- * - Forces form rebuild.
- *
- * You are not required to change this function.
- *
- * @ingroup form_example
- */
- function form_example_wizard_previous_submit($form, &$form_state) {
- $current_step = &$form_state['step'];
- $form_state['step_information'][$current_step]['stored_values'] = $form_state['input'];
- if ($current_step > 1) {
- $current_step--;
- $form_state['values'] = $form_state['step_information'][$current_step]['stored_values'];
- }
- $form_state['rebuild'] = TRUE;
- }
- /**
- * Submit handler for the 'next' button.
- *
- * This function:
- * - Saves away $form_state['values']
- * - Increments the step count.
- * - Replace $form_state['values'] from the last time we were at this page
- * or with array() if we haven't been here before.
- * - Force form rebuild.
- *
- * You are not required to change this function.
- *
- * @ingroup form_example
- */
- function form_example_wizard_next_submit($form, &$form_state) {
- $current_step = &$form_state['step'];
- $form_state['step_information'][$current_step]['stored_values'] = $form_state['values'];
- if ($current_step < count($form_state['step_information'])) {
- $current_step++;
- if (!empty($form_state['step_information'][$current_step]['stored_values'])) {
- $form_state['values'] = $form_state['step_information'][$current_step]['stored_values'];
- }
- else {
- $form_state['values'] = array();
- }
- // Force rebuild with next step.
- $form_state['rebuild'] = TRUE;
- return;
- }
- }
- /**
- * The previous code was a 'skeleton' of a multistep wizard form. You are not
- * required to change a line on the previous code (apart from defining your own
- * steps in the _form_example_steps() function.
- *
- * All the code included from here is the content of the wizard, the steps of
- * the form.
- *
- * First, let's show the defined steps for the wizard example.
- * @ingroup form_example
- */
- /**
- * Returns form elements for the 'personal info' page of the wizard.
- *
- * This is the first step of the wizard, asking for two textfields: first name
- * and last name.
- *
- * @ingroup form_example
- */
- function form_example_wizard_personal_info($form, &$form_state) {
- $form = array();
- $form['first_name'] = array(
- '#type' => 'textfield',
- '#title' => t('First Name'),
- '#default_value' => !empty($form_state['values']['first_name']) ? $form_state['values']['first_name'] : '',
- );
- $form['last_name'] = array(
- '#type' => 'textfield',
- '#title' => t('Last Name'),
- '#default_value' => !empty($form_state['values']['last_name']) ? $form_state['values']['last_name'] : '',
- );
- return $form;
- }
- /**
- * Returns form elements for the 'location info' page of the wizard.
- *
- * This is the second step of the wizard. This step asks for a textfield value:
- * a City. This step also includes a validation declared later.
- *
- * @ingroup form_example
- */
- function form_example_wizard_location_info($form, &$form_state) {
- $form = array();
- $form['city'] = array(
- '#type' => 'textfield',
- '#title' => t('City'),
- '#description' => t('Hint: Do not enter "San Francisco", and do not leave this out.'),
- '#required' => TRUE,
- '#default_value' => !empty($form_state['values']['city']) ? $form_state['values']['city'] : '',
- );
- return $form;
- }
- /**
- * Custom validation form for the 'location info' page of the wizard.
- *
- * This is the validation function for the second step of the wizard.
- * The city cannot be empty or be "San Francisco".
- *
- * @ingroup form_example
- */
- function form_example_wizard_location_info_validate($form, &$form_state) {
- if ($form_state['values']['city'] == 'San Francisco') {
- form_set_error('city', t('You were warned not to enter "San Francisco"'));
- }
- }
- /**
- * Returns form elements for the 'other info' page of the wizard.
- *
- * This is the third and last step of the example wizard.
- *
- * @ingroup form_example
- */
- function form_example_wizard_other_info($form, &$form_state) {
- $form = array();
- $form['aunts_name'] = array(
- '#type' => 'textfield',
- '#title' => t("Your first cousin's aunt's Social Security number"),
- '#default_value' => !empty($form_state['values']['aunts_name']) ? $form_state['values']['aunts_name'] : '',
- );
- return $form;
- }
- /**
- * Wizard form submit handler.
- *
- * This function:
- * - Saves away $form_state['values']
- * - Process all the form values.
- *
- * And now comes the magic of the wizard, the function that should handle all
- * the inputs from the user on each different step.
- *
- * This demonstration handler just do a drupal_set_message() with the
- * information collected on each different step of the wizard.
- *
- * @ingroup form_example
- */
- function form_example_wizard_submit($form, &$form_state) {
- $current_step = &$form_state['step'];
- $form_state['step_information'][$current_step]['stored_values'] = $form_state['values'];
- // In this case we've completed the final page of the wizard, so process the
- // submitted information.
- drupal_set_message(t('This information was collected by this wizard:'));
- foreach ($form_state['step_information'] as $index => $value) {
- // Remove FAPI fields included in the values (form_token, form_id and
- // form_build_id. This is not required, you may access the values using
- // $value['stored_values'] but I'm removing them to make a more clear
- // representation of the collected information as the complete array will
- // be passed through drupal_set_message().
- unset($value['stored_values']['form_id']);
- unset($value['stored_values']['form_build_id']);
- unset($value['stored_values']['form_token']);
- // Now show all the values.
- drupal_set_message(t('Step @num collected the following values: <pre>@result</pre>',
- array(
- '@num' => $index,
- '@result' => print_r($value['stored_values'], TRUE),
- )
- ));
- }
- }
|