/[drupal]/contributions/docs/developer/examples/multipage_form_example.module
ViewVC logotype

Contents of /contributions/docs/developer/examples/multipage_form_example.module

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph


Revision 1.1 - (hide annotations) (download) (as text)
Wed Mar 22 19:16:41 2006 UTC (3 years, 8 months ago) by jvandyk
Branch: MAIN
File MIME type: text/x-php
formerly multipart_form_example.module
1 jvandyk 1.1 <?php
2    
3     // $Id$
4    
5     /**
6     * Implementation of hook_help().
7     */
8     function multipage_form_example_help($section) {
9     switch ($section) {
10     case 'admin/modules#description':
11     return t('An example module showing how to handle multipage forms in FAPI.');
12     case 'node/add#multipage_form_example':
13     return t('This will show you an example multipage form submission.');
14     }
15     }
16    
17     /**
18     * Implementation of hook_menu().
19     */
20     function multipage_form_example_menu($may_cache) {
21     $items = array();
22    
23     if (!$may_cache) {
24    
25     $items[] = array('title' => t('multipage form example'),
26     'path' => 'node/add/multipage_form_example',
27     'access' => TRUE,
28     );
29     }
30    
31     return $items;
32     }
33    
34     /**
35     * Implementation of hook_access().
36     */
37     function multipage_form_example_access($op, $node) {
38     return TRUE;
39     }
40    
41     /**
42     * Implementation of hook_node_info().
43     */
44     function multipage_form_example_node_info() {
45     return array('multipage_form_example' => array('name' => t('multipage form example'), 'base' => 'multipage_form_example'));
46     }
47    
48     /**
49     * Implementation of hook_form() for multipage_form_example. We don't set ANY
50     * #required attributes here - we leave that up to multipage_form_example_pre_render().
51     */
52     function multipage_form_example_form(&$node) {
53    
54     $form = array();
55    
56     // 'checkboxes' elements are just ridiculously hard--i recommend just
57     // using a bunch of individual checkbox elements instead.
58     // I suspect that multiselects would also be pretty difficult...
59    
60     // Here's a new form element, which enables you to store hidden values
61     // in an array. Check out the element definition functions at the bottom
62     // if you want to use this in a module. Keys show up in the
63     // $_POST/$form_values like:
64     // $_POST['edit']['test_hidden_array']['n'] = 'north'
65     // $form_values['test_hidden_array']['n'] = 'north'
66    
67     $form['test_hidden_array'] = array(
68     '#type' => 'hidden_array',
69     '#values' => array('n' => 'north', 'e' => 'east', 'w' => 'west', 's' => 'south', ),
70     );
71    
72    
73    
74     // Helper for our multipage - does field switching, sets options
75     // based on validated $form_values instead of $_POST, and so forth.
76     $form['#pre_render'] = array('multipage_form_example_pre_render');
77    
78     // Title and body, page 1
79     $form['title'] = array(
80     '#type' => 'textfield',
81     '#title' => t('Title'),
82     '#default_value' => isset($node->title) ? $node->title : NULL,
83     '#description' => t("Enter a title for your favorites section."),
84     '#size' => 60,
85     '#maxlength' => 128,
86     );
87     $form['body'] = array(
88     '#type' => 'textarea',
89     '#title' => t('Description'),
90     '#default_value' => isset($node->body) ? $node->body : NULL,
91     '#description' => t('Add any additional info about your favorites.'),
92     '#rows' => 20,
93     );
94    
95     // Person, page 2
96     $form['person'] = array(
97     // This is a fieldset, but has to be set as such in #pre_render,
98     // otherwise we either have the choice of displaying the <fieldset>
99     // all the time, or not passing through the values of its children.
100     '#title' => t('Your favorite person'),
101     );
102     $form['person']['fav_person'] = array(
103     '#type' => 'textfield',
104     '#title' => t('Name'),
105     '#default_value' => isset($node->fav_person) ? $node->fav_person : NULL,
106     '#description' => t('Enter their real name, or their code name if they like to fly stealth.'),
107     );
108     $form['person']['fav_person_desc'] = array(
109     '#type' => 'textarea',
110     '#title' => t('Description'),
111     '#default_value' => isset($node->fav_person_desc) ? $node->fav_person_desc : NULL,
112     '#description' => t('Juicy details go here...'),
113     );
114     $form['person']['fav_gummi'] = array(
115     '#type' => 'checkbox',
116     '#default_value' => isset($node->fav_gummi) ? $node->fav_gummi : 0,
117     '#title' => t('Do they like gummi bears?'),
118     );
119    
120     // Color and number, page 3
121     $form['fav_color'] = array(
122     '#type' => 'select',
123     '#title' => t('Favorite color'),
124     '#default_value' => isset($node->fav_color) ? $node->fav_color : 'red',
125     '#options' => array('red' => t('Red'), 'green' => t('Green'), 'blue' => t('Blue'), 'yellow' => t('Yellow')),
126     );
127     $form['fav_number'] = array(
128     '#type' => 'textfield',
129     '#title' => t('Favorite number'),
130     '#default_value' => isset($node->fav_number) ? $node->fav_number : NULL,
131     );
132    
133     // Movie and tv show, page 4
134     $form['fav_movie'] = array(
135     '#type' => 'textfield',
136     '#title' => t('Favorite movie'),
137     '#default_value' => isset($node->fav_movie) ? $node->fav_movie : NULL,
138     );
139     $form['fav_tv'] = array(
140     '#type' => 'radios',
141     '#title' => t('How often do you watch your favorite tv show?'),
142     '#default_value' => isset($node->fav_tv) ? $node->fav_tv : 'daily',
143     '#options' => array('daily' => t('Daily'), 'weekly' => t('Weekly'), 'monthly' => t('Monthly'),),
144     );
145    
146     // Some markup elements to help the user see what they've already
147     // entered. Since the data won't be available until after the form
148     // is submitted, we'll only build the basic element here, and then
149     // we'll populate it in #pre_render
150     $form['person_display'] = array(
151     '#type' => 'markup',
152     );
153     $form['color_number_display'] = array(
154     '#type' => 'markup',
155     );
156    
157     // Add a back button
158     $form['back'] = array(
159     '#type' => 'button',
160     '#value' => t('Back'),
161     '#weight' => 35,
162     );
163    
164    
165     return $form;
166     }
167    
168     /**
169     * Implementation of hook_form_alter(). Here, we set up the 'page' field,
170     * which keeps track of what stage the form is in.
171     */
172     function multipage_form_example_form_alter($form_id, &$form) {
173    
174     // Make sure it's our multipage form.
175     if ($form_id == 'multipage_form_example_node_form') {
176    
177     // Determine which page of the multipage form we're on. We don't do
178     // any incrementing here - that's something that our #pre_render'er
179     // will do when this page of the form has successfully validated.
180     $form['page'] = array('#type' => 'hidden', '#value' =>
181     isset($_POST['edit']['page']) ? $_POST['edit']['page'] : 1);
182    
183     // If back button is pressed, back up the form stage, Also, if preview
184     // is hit we need to decrement the counter here to keep us on the same page.
185     if ($_POST['op'] == t('Back') || $_POST['op'] == t('Preview')) {$form['page']['#value']--;}
186    
187     // This modifies the form for validation purposes. once validation is
188     // completed, it'll be called one more time (through Drupal's Form API)
189     // at which point it'll advance the form to the next page.
190     multipage_form_example_pre_render($form_id, $form, FALSE);
191    
192     // Here we're augmenting the regular node form validation/submission with
193     // some of our own. Note that these are inside the conditional check for
194     // this particular form.
195     $form['#validate'] = array_merge($form['#validate'], array('multipage_form_example_validate' => array()));
196     $form['#submit'] = array_merge($form['#submit'], array('multipage_form_example_submit' => array()));
197     }
198    
199     return $form;
200     }
201    
202     /**
203     * Validate our form.
204     */
205     function multipage_form_example_validate() {
206     global $form_values;
207     // validate our number, but don't bother if the back button was hit
208     if (($form_values['page'] == 3 ) && !is_numeric($form_values['fav_number']) && ($_POST['op'] != t('Back'))) {
209     form_set_error('fav_number', t('Favorite number is a <em>number</em>, dummy!'));
210     }
211     }
212    
213     /**
214     * The #pre_render of a form allows us to make changes AFTER validation (unlike
215     * hook_form_alter()), but BEFORE the form has actually been displayed. We use
216     * it to control which form elements are shown, which are hidden, and which values
217     * to set based on validate elements, not $_POST. This is a necessity for our
218     * complicated multipage example form.
219     */
220     function multipage_form_example_pre_render($form_id, &$form, $next_page = TRUE) {
221    
222     global $form_values;
223    
224     // Make sure it's our multipage form.
225     if ($form_id == 'multipage_form_example_node_form') {
226    
227     // Are we ready for the next page in our form?
228     if ($next_page && isset($_POST['edit']['page']) && ($_POST['op'] != t('Back'))) {
229     $form['page']['#value'] = $form['page']['#value'] + 1;
230     }
231    
232     // Validation errors? Show previous page for correcting.
233     if (form_get_errors()) { $form['page']['#value']--; }
234    
235     // Modify the #required/#type values depending on our current page.
236     // The arrays tell us the pages the changes should take place in.
237    
238     // Title/body, stage 1
239     $form['title']['#type'] = in_array($form['page']['#value'], array(1)) ? 'textfield' : 'hidden';
240     $form['title']['#required'] = in_array($form['page']['#value'], array(1)) ? 1 : 0;
241     $form['body']['#type'] = in_array($form['page']['#value'], array(1)) ? 'textarea' : 'hidden';
242    
243     // Person, stage 2
244     $form['person']['#type'] = in_array($form['page']['#value'], array(2)) ? 'fieldset' : NULL;
245     $form['person']['fav_person']['#type'] = in_array($form['page']['#value'], array(2)) ? 'textfield' : 'hidden';
246     $form['person']['fav_person']['#required'] = in_array($form['page']['#value'], array(2)) ? 1 : 0;
247     $form['person']['fav_person_desc']['#type'] = in_array($form['page']['#value'], array(2)) ? 'textarea' : 'hidden';
248     $form['person']['fav_person_desc']['#required'] = in_array($form['page']['#value'], array(2)) ? 1 : 0;
249     $form['person']['fav_gummi']['#type'] = in_array($form['page']['#value'], array(2)) ? 'checkbox' : 'hidden';
250    
251     // Color and number, page 3
252     $form['fav_color']['#type'] = in_array($form['page']['#value'], array(3)) ? 'select' : 'hidden';
253     $form['fav_color']['#required'] = in_array($form['page']['#value'], array(3)) ? 1 : 0;
254     $form['fav_number']['#type'] = in_array($form['page']['#value'], array(3)) ? 'textfield' : 'hidden';
255     $form['fav_number']['#required'] = in_array($form['page']['#value'], array(3)) ? 1 : 0;
256    
257     // Movie and tv show, page 4
258     $form['fav_movie']['#type'] = in_array($form['page']['#value'], array(4)) ? 'textfield' : 'hidden';
259     $form['fav_movie']['#required'] = in_array($form['page']['#value'], array(4)) ? 1 : 0;
260     // this bit of trickery is because radios is a bit of a special case -- it's an 'expanding' form element,
261     // which means that the multiple buttons get built by form_builder. Because the building for display actually
262     // happens when the form is still set to stage 3, we have to build it as a radios type in stage 3, or nothing will
263     // display on stage 4! form_hide_elements is a little helper function that recurses through and hides
264     // all of the buttons we built if we don't actually happen to be displaying stage 4. whew!
265     $form['fav_tv']['#type'] = in_array($form['page']['#value'], array(4)) ? 'radios' : ($next_page ? hide_form_elements($form['fav_tv']) : 'radios');
266     $form['fav_tv']['#required'] = in_array($form['page']['#value'], array(4)) ? 1 : 0;
267    
268     // The progress display for stuff we've already entered
269     $person_display = t('Your favorite person is %person, and they %like gummi bears.<br \>', array('%person' => check_plain($form_values['fav_person']), '%like' => ($form_values['fav_gummi'] ? t('like') : t('don\'t like'))));
270     $color_number_display = t('Your favorite color is %color, and your favorite number is %number.', array('%color' => check_plain($form_values['fav_color']), '%number' => check_plain($form_values['fav_number'])));
271    
272     $form['person_display']['#value'] = in_array($form['page']['#value'], array(3,4)) ? $person_display : '';
273     $form['color_number_display']['#value'] = in_array($form['page']['#value'], array(4)) ? $color_number_display : '';
274    
275     // Buttons -- like radios, they need to be properly built in the previous stage, so here we also do the switches at
276     // the last chance we have. Notice that the type gets set to 'value' and not 'hidden', b/c hidden will screw w/
277     // $_POST['op']
278     if ($next_page) {
279     $form['back']['#type'] = in_array($form['page']['#value'], array(2,3,4)) ? 'button' : 'value';
280     $form['preview']['#type'] = in_array($form['page']['#value'], array(4)) ? 'button' : 'value';
281     $form['submit']['#type'] = in_array($form['page']['#value'], array(4)) ? 'submit' : 'button';
282     $submit_text = array(NULL, t('Next (person)'), t('Next (color/number)'), t('Next (tv/movie)'), t('Submit'));
283     $form['submit']['#value'] = $submit_text[$form['page']['#value']];
284     }
285     }
286     }
287    
288     // Handles form submission. We're just throwing our data into the variable
289     // table to keep things simple
290     function multipage_form_example_submit() {
291     global $form_values;
292     foreach ($form_values as $key => $value) {
293     if (in_array($key, array('fav_person', 'fav_person_desc', 'fav_gummi', 'fav_color', 'fav_number', 'fav_movie', 'fav_tv',))) {
294     $array[$key] = $value;
295     }
296     }
297     variable_set('multipage_form_example_'. $form_values['nid'], $array);
298     }
299    
300     /**
301     * Implementation of hook_load().
302     *
303     * Now that we've defined how to manage the node data in the database, We
304     * need to tell Drupal how to get the node back out. This hook is called
305     * every time a node is loaded, and allows us to do some loading of our own.
306     */
307     function multipage_form_example_load($node) {
308     $additions = variable_get('multipage_form_example_'. $node->nid, NULL);
309     $additions = (object) $additions;
310     return $additions;
311     }
312    
313     /**
314     * Implementation of hook_delete().
315     *
316     * Clean up our data in variable table.
317     */
318     function multipage_form_example_delete($node) {
319     // Notice that we're matching all revision, by using the node's nid.
320     variable_del('multipage_form_example_'. $node->nid);
321     }
322    
323     /**
324     * Implementation of hook_view().
325     *
326     * This is a typical implementation that simply runs the node text through
327     * the output filters.
328     */
329     function multipage_form_example_view(&$node, $teaser = FALSE, $page = FALSE) {
330     $node = node_prepare($node, $teaser);
331     $favorites = theme('multipage_form_example', $node);
332     $node->body .= $favorites;
333     $node->teaser .= $favorites;
334     }
335    
336     /**
337     * A custom theme function.
338     *
339     * By using this function to format our node-specific information, themes
340     * can override this presentation if they wish. We also wrap the default
341     * presentation in a CSS class that is prefixed by the module name. This
342     * way, style sheets can modify the output without requiring theme code.
343     */
344     function theme_multipage_form_example($node) {
345    
346     $person_display = t('Your favorite person is %person, and they %like gummi bears. <br \>', array('%person' => check_plain($node->fav_person), '%like' => ($node->fav_gummi ? t('like') : t('don\'t like'))));
347     $color_number_display = t('Your favorite color is %color, and your favorite number is %number. <br \>', array('%color' => check_plain($node->fav_color), '%number' => check_plain($node->fav_number)));
348     $tv_movie_display = t('Your favorite movie is %movie, and you watch your favorite tv show %watch.', array('%movie' => check_plain($node->fav_movie), '%watch' => check_plain($node->fav_tv)));
349    
350     $output = '<div class="multipage_form_example">';
351     $output .= $person_display . $color_number_display . $tv_movie_display;
352     $output .= '</div>';
353     return $output;
354     }
355    
356     /**
357     * A little helper function to hide the child elements of 'radios'.
358     */
359     function hide_form_elements(&$element) {
360     foreach (element_children($element) as $key) {
361     $element[$key]['#type'] = 'hidden';
362     }
363     return 'hidden';
364     }
365    
366     /**
367     * Playing around here with a new form element to enable storing hidden values in an array fashion.
368     * Seems to work fine. Check out $form['test_hidden_array'] above for how to structure the form
369     * element
370     */
371     function multipage_form_example_elements() {
372     $type['hidden_array'] = array('#input' => TRUE, '#process' => array('expand_hidden_array' => array()), '#tree' => TRUE);
373     return $type;
374     }
375    
376     function expand_hidden_array($element) {
377     $values = is_array($element['#values']) ? $element['#values'] : array();
378     $element['#tree'] = TRUE;
379     foreach ($values as $key => $value) {
380     $element[$key] = array('#type' => 'hidden', '#processed' => TRUE, '#value' => $value);
381     }
382     return $element;
383     }
384    
385     function theme_hidden_array ($element) {
386     return $element['#children'];
387     }

  ViewVC Help
Powered by ViewVC 1.1.2