1 | Views allows handlers to output form elements, wrapping them automatically in a form, and handling validation / submission. |
---|
2 | The form is multistep by default, allowing other modules to add additional steps, such as confirmation screens. |
---|
3 | |
---|
4 | <h2>Implementation</h2> |
---|
5 | A views handler outputs a special placeholder in render(), while the real form with matching structure gets added in views_form(). |
---|
6 | When the View is being preprocessed for the theme file, all placeholders get replaced with the rendered form elements. |
---|
7 | |
---|
8 | The views handler can also implement views_form_validate() and views_form_submit(). |
---|
9 | <pre> |
---|
10 | function render($values) { |
---|
11 | return '<!--form-item-' . $this->options['id'] . '--' . $this->view->row_index . '-->'; |
---|
12 | } |
---|
13 | |
---|
14 | function views_form(&$form, &$form_state) { |
---|
15 | // The view is empty, abort. |
---|
16 | if (empty($this->view->result)) { |
---|
17 | return; |
---|
18 | } |
---|
19 | |
---|
20 | $field_name = $this->options['id']; |
---|
21 | $form[$field_name] = array( |
---|
22 | '#tree' => TRUE, |
---|
23 | ); |
---|
24 | // At this point, the query has already been run, so we can access the results |
---|
25 | foreach ($this->view->result as $row_id => $row) { |
---|
26 | $form[$field_name][$row_id] = array( |
---|
27 | '#type' => 'textfield', |
---|
28 | '#title' => t('Your name'), |
---|
29 | '#default_value' => '', |
---|
30 | ); |
---|
31 | } |
---|
32 | } |
---|
33 | |
---|
34 | // Optional validate function. |
---|
35 | function views_form_validate($form, &$form_state) { |
---|
36 | $field_name = $this->options['id']; |
---|
37 | foreach ($form_state['values'][$field_name] as $row_id => $value) { |
---|
38 | if ($value == 'Drupal') { |
---|
39 | form_set_error($field_name . '][' . $row_id, "You can't be named Drupal. That's my name."); |
---|
40 | } |
---|
41 | } |
---|
42 | } |
---|
43 | |
---|
44 | // Optional submit function. |
---|
45 | function views_form_submit($form, &$form_state) { |
---|
46 | // Do something here |
---|
47 | } |
---|
48 | </pre> |
---|
49 | |
---|
50 | Modules can implement hook_views_form_validate($form, &$form_state) and hook_views_form_submit($form, &$form_state). |
---|
51 | |
---|
52 | The form is multistep by default, with one step: 'views_form_views_form'. |
---|
53 | A "form_example" module could add a confirmation step by setting: |
---|
54 | <pre> |
---|
55 | $form_state['storage']['step'] = 'form_example_confirmation'; |
---|
56 | </pre> |
---|
57 | in form_example_views_form_submit(). |
---|
58 | Then, views_form would call form_example_confirmation($form, $form_state, $view, $output) to get that step. |
---|
59 | |
---|
60 | <b>Important:</b> You can fetch the Views object in form_alter and validate / submit hooks from $form['#parameters']: |
---|
61 | <pre> |
---|
62 | $view = $form['#parameters'][2]; |
---|
63 | </pre> |
---|
64 | |
---|
65 | <h2>Relevant Views functions</h2> |
---|
66 | <ul> |
---|
67 | <li>template_preprocess_views_view()</li> |
---|
68 | <li>views_form()</li> |
---|
69 | <li>views_form_validate()</li> |
---|
70 | <li>views_form_submit()</li> |
---|
71 | <li>views_form_views_form()</li> |
---|
72 | <li>views_form_views_form_validate()</li> |
---|
73 | <li>views_form_views_form_submit()</li> |
---|
74 | <li>theme_views_form_views_form()</li> |
---|
75 | </ul> |
---|
76 | |
---|
77 | <h2>Hooks</h2> |
---|
78 | <ul> |
---|
79 | <li>hook_views_form_substitutions()</li> |
---|
80 | <li>hook_views_form_validate($form, &$form_state)</li> |
---|
81 | <li>hook_views_form_submit($form, &$form_state)</li> |
---|
82 | </ul> |
---|