' . $help . '
'; - } + $markup = t('The form example module provides a tutorial, extensible multistep example, and a #states example'); + return array('#markup' => $markup); } \ No newline at end of file Index: form_example.test =================================================================== RCS file: /cvs/drupal-contrib/contributions/modules/examples/form_example/form_example.test,v retrieving revision 1.8 diff -u -r1.8 form_example.test --- form_example/form_example.test 1 Sep 2010 11:44:40 -0000 1.8 +++ form_example/form_example.test 19 Sep 2010 10:03:01 -0000 @@ -106,5 +106,29 @@ $this->assertText(t('@num: firstname @num lastname @num (@year)', array('@num' => $i, '@year' => 1950 + $i))); } } + + /** + * Test Wizard tutorial + * @TODO improve this using drupal_form_submit + */ + function testWizard() { + // Is the wizard there + $this->drupalGet('examples/form_example/wizard'); + $this->assertText(t('Extensible wizard example')); + + $first_name = $this->randomName(8); + $last_name = $this->randomName(8); + + // Submit the first step of the wizard + $options = array( + 'first_name' => $first_name, + 'last_name' => $last_name, + ); + $this->drupalPost('examples/form_example/wizard', $options, t('Next')); + + // A label city is created, and two buttons appear, Preivous and Next + $this->assertText(t('Hint: Do not enter "San Francisco", and do not leave this out.')); + } + } --- form_example/form_example_wizard.inc +++ form_example/form_example_wizard.inc @@ -0,0 +1,285 @@ + 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 directly 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, is the default form _submit handler used to + * process the information. + * + * You are not required to change the next nor previous handlers, but you must + * change the form_example_wizard_sbumit handler to perform the operations you + * need on the collected information. + */ +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']; + + // Call the function named in $form_state['step_information'] to get the + // form elements to display for this step. + // Note: Not passing $form_state as reference because of php5.3 warnings.. + // should this work in php5.2? + $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 + // assumption is that we'll get to the errors when we return and use the + // 'next' 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. + * - Stores aways $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 + */ +function form_example_wizard_previous_submit($form, &$form_state) { + $current_step = &$form_state['step']; + $form_state['step_information'][$current_step]['stored_values'] = $form_state['values']; + 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. + * - Saves away $form_state['values'] + * - Increment 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 + * + * @param unknown_type $form + * @param unknown_type $form_state + */ +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(); + } + $form_state['rebuild'] = TRUE; // Force rebuild with next step. + return; + } +} + +// The previous code was a 'skeleton' of a multistep wizard form. You are not +// required to change a line on the previous code (appart of 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, lets show the defined steps for the wizard 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. + */ +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. + */ +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". + */ +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 + * thid and last step of the example wizard. + */ +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; +} + +// And now comes the magic of the wizard, the function that should handle all the +// inputs from the user on each different step. +/** + * Wizard form Submit handler. + * - Saves away $form_state['values'] + * - Process all the form values. + * + * This demostration handler just do a drupal_set_message() with the information + * collected on each different step of the wizard. + * + * @param unknown_type $form + * @param unknown_type $form_state + */ +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('The step @num collected the following values:@result', array('@num' => $index, '@result' => print_r($value['stored_values'], TRUE)))); + } +}