Project

General

Profile

Paste
Download (45.2 KB) Statistics
| Branch: | Revision:

root / drupal7 / sites / all / modules / webform / webform.api.php @ 01f36513

1
<?php
2

    
3
/**
4
 * @file
5
 * Sample hooks demonstrating usage in Webform.
6
 */
7

    
8
/**
9
 * @defgroup webform_hooks Webform Module Hooks
10
 * @{
11
 * Webform's hooks enable other modules to intercept events within Webform, such
12
 * as the completion of a submission or adding validation. Webform's hooks also
13
 * allow other modules to provide additional components for use within forms.
14
 */
15

    
16
/**
17
 * Define callbacks that can be used as select list options.
18
 *
19
 * When users create a select component, they may select a pre-built list of
20
 * certain options. Webform core provides a few of these lists such as the
21
 * United States, countries of the world, and days of the week. This hook
22
 * provides additional lists that may be utilized.
23
 *
24
 * @see webform_options_example()
25
 * @see hook_webform_select_options_info_alter()
26
 *
27
 * @return array
28
 *   An array of callbacks that can be used for select list options. This array
29
 *   should be keyed by the "name" of the pre-defined list. The values should
30
 *   be an array with the following additional keys:
31
 *     - title: The translated title for this list.
32
 *     - options callback: The name of a function implementing
33
 *       callback_webform_options() that will return the list.
34
 *     - options arguments: Any additional arguments to send to the callback.
35
 *     - file: Optional. The file containing the options callback, relative to
36
 *       the module root.
37
 */
38
function hook_webform_select_options_info() {
39
  $items = array();
40

    
41
  $items['days'] = array(
42
    'title' => t('Days of the week'),
43
    'options callback' => 'webform_options_days',
44
    'file' => 'includes/webform.options.inc',
45
  );
46

    
47
  return $items;
48
}
49

    
50
/**
51
 * Alter the list of select list options provided by Webform and other modules.
52
 *
53
 * @see hook_webform_select_options_info()
54
 */
55
function hook_webform_select_options_info_alter(&$items) {
56
  // Remove the days of the week options.
57
  unset($items['days']);
58
}
59

    
60
/**
61
 * Define a list of options that Webform may use in a select component.
62
 *
63
 * Callback for hook_webform_select_options_info().
64
 *
65
 * @param $component
66
 *   The Webform component array for the select component being displayed.
67
 * @param $flat
68
 *   Boolean value indicating whether the returned list needs to be a flat array
69
 *   of key => value pairs. Select components support up to one level of
70
 *   nesting, but when results are displayed, the list needs to be returned
71
 *   without the nesting.
72
 * @param $arguments
73
 *   The "options arguments" specified in hook_webform_select_options_info().
74
 *
75
 * @return array
76
 *   An array of key => value pairs suitable for a select list's #options
77
 *   FormAPI property.
78
 */
79
function callback_webform_options($component, $flat, $arguments) {
80
  $options = array(
81
    'one' => t('Pre-built option one'),
82
    'two' => t('Pre-built option two'),
83
    'three' => t('Pre-built option three'),
84
  );
85

    
86
  return $options;
87
}
88

    
89
/**
90
 * Respond to the loading of Webform submissions.
91
 *
92
 * @param $submissions
93
 *   An array of Webform submissions that are being loaded, keyed by the
94
 *   submission ID. Modifications to the submissions are done by reference.
95
 */
96
function hook_webform_submission_load(&$submissions) {
97
  foreach ($submissions as $sid => $submission) {
98
    $submissions[$sid]->new_property = 'foo';
99
  }
100
}
101

    
102
/**
103
 * Respond to the creation of a new submission from form values.
104
 *
105
 * This hook is called when a user has completed a submission to initialize the
106
 * submission object. After this object has its values populated, it will be
107
 * saved by webform_submission_insert(). Note that this hook is only called for
108
 * new submissions, not for submissions being edited. If responding to the
109
 * saving of all submissions, it's recommended to use
110
 * hook_webform_submission_presave().
111
 *
112
 * @param $submission
113
 *   The submission object that has been created.
114
 * @param $node
115
 *   The Webform node for which this submission is being saved.
116
 * @param $account
117
 *   The user account that is creating the submission.
118
 * @param $form_state
119
 *   The contents of form state that is the basis for this submission.
120
 *
121
 * @see webform_submission_create()
122
 */
123
function hook_webform_submission_create_alter(&$submission, &$node, &$account, &$form_state) {
124
  $submission->new_property = TRUE;
125
}
126

    
127
/**
128
 * Modify a Webform submission, prior to saving it in the database.
129
 *
130
 * @param $node
131
 *   The Webform node on which this submission was made.
132
 * @param $submission
133
 *   The Webform submission that is about to be saved to the database.
134
 */
135
function hook_webform_submission_presave($node, &$submission) {
136
  // Update some component's value before it is saved.
137
  $component_id = 4;
138
  $submission->data[$component_id][0] = 'foo';
139
}
140

    
141
/**
142
 * Respond to a Webform submission being inserted.
143
 *
144
 * Note that this hook is called after a submission has already been saved to
145
 * the database. If needing to modify the submission prior to insertion, use
146
 * hook_webform_submission_presave().
147
 *
148
 * @param $node
149
 *   The Webform node on which this submission was made.
150
 * @param $submission
151
 *   The Webform submission that was just inserted into the database.
152
 */
153
function hook_webform_submission_insert($node, $submission) {
154
  // Insert a record into a 3rd-party module table when a submission is added.
155
  db_insert('mymodule_table')
156
    ->fields(array(
157
      'nid' => $node->nid,
158
      'sid' => $submission->sid,
159
      'foo' => 'foo_data',
160
    ))
161
    ->execute();
162
}
163

    
164
/**
165
 * Respond to a Webform submission being updated.
166
 *
167
 * Note that this hook is called after a submission has already been saved to
168
 * the database. If needing to modify the submission prior to updating, use
169
 * hook_webform_submission_presave().
170
 *
171
 * @param $node
172
 *   The Webform node on which this submission was made.
173
 * @param $submission
174
 *   The Webform submission that was just updated in the database.
175
 */
176
function hook_webform_submission_update($node, $submission) {
177
  // Update a record in a 3rd-party module table when a submission is updated.
178
  db_update('mymodule_table')
179
    ->fields(array(
180
      'foo' => 'foo_data',
181
    ))
182
    ->condition('nid', $node->nid)
183
    ->condition('sid', $submission->sid)
184
    ->execute();
185
}
186

    
187
/**
188
 * Respond to a Webform submission being deleted.
189
 *
190
 * @param $node
191
 *   The Webform node on which this submission was made.
192
 * @param $submission
193
 *   The Webform submission that was just deleted from the database.
194
 */
195
function hook_webform_submission_delete($node, $submission) {
196
  // Delete a record from a 3rd-party module table when a submission is deleted.
197
  db_delete('mymodule_table')
198
    ->condition('nid', $node->nid)
199
    ->condition('sid', $submission->sid)
200
    ->execute();
201
}
202

    
203
/**
204
 * Provide a list of actions that can be executed on a submission.
205
 *
206
 * Some actions are displayed in the list of submissions such as edit, view, and
207
 * delete. All other actions are displayed only when viewing the submission.
208
 * These additional actions may be specified in this hook. Examples included
209
 * directly in the Webform module include PDF, print, and resend e-mails. Other
210
 * modules may extend this list by using this hook.
211
 *
212
 * @param $node
213
 *   The Webform node on which this submission was made.
214
 * @param $submission
215
 *   The Webform submission on which the actions may be performed.
216
 *
217
 * @return array
218
 *   List of action.
219
 */
220
function hook_webform_submission_actions($node, $submission) {
221
  $actions = array();
222

    
223
  if (webform_results_access($node)) {
224
    $actions['myaction'] = array(
225
      'title' => t('Do my action'),
226
      'href' => 'node/' . $node->nid . '/submission/' . $submission->sid . '/myaction',
227
      'query' => drupal_get_destination(),
228
    );
229
  }
230

    
231
  return $actions;
232
}
233

    
234
/**
235
 * Modify the draft to be presented for editing.
236
 *
237
 * When drafts are enabled for the webform, by default, a pre-existing draft is
238
 * presented when the webform is displayed to that user. To allow multiple
239
 * drafts, implement this alter function to set the $sid to NULL, or use your
240
 * application's business logic to determine whether a new draft or which of
241
 * he pre-existing drafts should be presented.
242
 *
243
 * @param int $sid
244
 *   The id of the most recent submission to be presented for editing. Change
245
 *    to a different draft's sid or set to NULL for a new draft.
246
 * @param array $context
247
 *   Array of context with indices 'nid' and 'uid'.
248
 */
249
function hook_webform_draft_alter(&$sid, array $context) {
250
  if ($_GET['newdraft']) {
251
    $sid = NULL;
252
  }
253
}
254

    
255
/**
256
 * Alter the display of a Webform submission.
257
 *
258
 * This function applies to both e-mails sent by Webform and normal display of
259
 * submissions when viewing through the administrative interface.
260
 *
261
 * @param $renderable
262
 *   The Webform submission in a renderable array, similar to FormAPI's
263
 *   structure. This variable must be passed in by-reference. Important
264
 *   properties of this array include #node, #submission, #email, and #format,
265
 *   which can be used to find the context of the submission that is being
266
 *   rendered.
267
 */
268
function hook_webform_submission_render_alter(&$renderable) {
269
  // Remove page breaks from sent e-mails.
270
  if (isset($renderable['#email'])) {
271
    foreach (element_children($renderable) as $key) {
272
      if ($renderable[$key]['#component']['type'] == 'pagebreak') {
273
        unset($renderable[$key]);
274
      }
275
    }
276
  }
277
}
278

    
279
/**
280
 * Modify a loaded Webform component.
281
 *
282
 * IMPORTANT: This hook does not actually exist because components are loaded
283
 * in bulk as part of webform_node_load(). Use hook_node_load() to modify loaded
284
 * components when the node is loaded. This example is provided merely to point
285
 * to hook_node_load().
286
 *
287
 * @see hook_nodeapi()
288
 * @see webform_node_load()
289
 */
290
function hook_webform_component_load() {
291
  // This hook does not exist. Instead use hook_node_load().
292
}
293

    
294
/**
295
 * Modify a Webform component before it is saved to the database.
296
 *
297
 * Note that most of the time this hook is not necessary, because Webform will
298
 * automatically add data to the component based on the component form. Using
299
 * hook_form_alter() will be sufficient in most cases.
300
 *
301
 * @param $component
302
 *   The Webform component being saved.
303
 *
304
 * @see hook_form_alter()
305
 * @see webform_component_edit_form()
306
 */
307
function hook_webform_component_presave(&$component) {
308
  $component['extra']['new_option'] = 'foo';
309
}
310

    
311
/**
312
 * Respond to a Webform component being inserted into the database.
313
 */
314
function hook_webform_component_insert($component) {
315
  // Insert a record into a 3rd-party module table when a component is inserted.
316
  db_insert('mymodule_table')
317
    ->fields(array(
318
      'nid' => $component['nid'],
319
      'cid' => $component['cid'],
320
      'foo' => 'foo_data',
321
    ))
322
    ->execute();
323
}
324

    
325
/**
326
 * Respond to a Webform component being updated in the database.
327
 */
328
function hook_webform_component_update($component) {
329
  // Update a record in a 3rd-party module table when a component is updated.
330
  db_update('mymodule_table')
331
    ->fields(array(
332
      'foo' => 'foo_data',
333
    ))
334
    ->condition('nid', $component['nid'])
335
    ->condition('cid', $component['cid'])
336
    ->execute();
337
}
338

    
339
/**
340
 * Respond to a Webform component being deleted.
341
 */
342
function hook_webform_component_delete($component) {
343
  // Delete a record in a 3rd-party module table when a component is deleted.
344
  db_delete('mymodule_table')
345
    ->condition('nid', $component['nid'])
346
    ->condition('cid', $component['cid'])
347
    ->execute();
348
}
349

    
350
/**
351
 * Alter the entire analysis before rendering to the page on the Analysis tab.
352
 *
353
 * This alter hook allows modification of the entire analysis of a node's
354
 * Webform results. The resulting analysis is displayed on the Results ->
355
 * Analysis tab on the Webform.
356
 *
357
 * @param array $analysis
358
 *   A Drupal renderable array, passed by reference, containing the entire
359
 *   contents of the analysis page. This typically will contain the following
360
 *   two major keys:
361
 *   - form: The form for configuring the shown analysis.
362
 *   - components: The list of analyses for each analysis-enabled component
363
 *     for the node. Each keyed by its component ID.
364
 */
365
function hook_webform_analysis_alter(array &$analysis) {
366
  $node = $analysis['#node'];
367

    
368
  // Add an additional piece of information to every component's analysis:
369
  foreach (element_children($analysis['components']) as $cid) {
370
    $component = $node->components[$cid];
371
    $analysis['components'][$cid]['chart'] = array(
372
      '#markup' => t('Chart for the @name component', array('@name' => $component['name'])),
373
    );
374
  }
375
}
376

    
377
/**
378
 * Alter data when displaying an analysis on that component.
379
 *
380
 * This hook modifies the data from an individual component's analysis results.
381
 * It can be used to add additional analysis, or to modify the existing results.
382
 * If needing to alter the entire set of analyses rather than an individual
383
 * component, hook_webform_analysis_alter() may be used instead.
384
 *
385
 * @param array $data
386
 *   An array containing the result of a components analysis hook, passed by
387
 *   reference. This is passed directly from a component's
388
 *   _webform_analysis_component() function. See that hook for more information
389
 *   on this value.
390
 * @param object $node
391
 *   The node object that contains the component being analyzed.
392
 * @param array $component
393
 *   The Webform component array whose analysis results are being displayed.
394
 *
395
 * @see _webform_analysis_component()
396
 * @see hook_webform_analysis_alter()
397
 */
398
function hook_webform_analysis_component_data_alter(array &$data, $node, array $component) {
399
  if ($component['type'] === 'textfield') {
400
    // Do not display rows that contain a zero value.
401
    foreach ($data as $row_number => $row_data) {
402
      if ($row_data[1] === 0) {
403
        unset($data[$row_number]);
404
      }
405
    }
406
  }
407
}
408

    
409
/**
410
 * Alter a Webform submission's header when exported.
411
 */
412
function hook_webform_csv_header_alter(&$header, $component) {
413
  // Use the machine name for component headers, but only for the webform
414
  // with node 5 and components that are text fields.
415
  if ($component['nid'] == 5 && $component['type'] == 'textfield') {
416
    $header[2] = $component['form_key'];
417
  }
418
}
419

    
420
/**
421
 * Alter a Webform submission's data when exported.
422
 */
423
function hook_webform_csv_data_alter(&$data, $component, $submission) {
424
  // If a value of a field was left blank, use the value from another
425
  // field.
426
  if ($component['cid'] == 1 && empty($data)) {
427
    $data = $submission->data[2]['value'][0];
428
  }
429
}
430

    
431
/**
432
 * Define components to Webform.
433
 *
434
 * @return array
435
 *   An array of components, keyed by machine name. Required properties are
436
 *   "label" and "description". The "features" array defines which capabilities
437
 *   the component has, such as being displayed in e-mails or csv downloads.
438
 *   A component like "markup" for example would not show in these locations.
439
 *   The possible features of a component include:
440
 *
441
 *     - csv
442
 *     - email
443
 *     - email_address
444
 *     - email_name
445
 *     - required
446
 *     - conditional
447
 *     - spam_analysis
448
 *     - group
449
 *
450
 *   Note that most of these features do not indicate the default state, but
451
 *   determine if the component can have this property at all. Setting
452
 *   "required" to TRUE does not mean that a component's fields will always be
453
 *   required, but instead give the option to the administrator to choose the
454
 *   requiredness. See the example implementation for details on how these
455
 *   features may be set.
456
 *
457
 *   An optional "file" may be specified to be loaded when the component is
458
 *   needed. A set of callbacks will be established based on the name of the
459
 *   component. All components follow the pattern:
460
 *
461
 *   _webform_[callback]_[component]
462
 *
463
 *   Where [component] is the name of the key of the component and [callback] is
464
 *   any of the following:
465
 *
466
 *     - defaults
467
 *     - edit
468
 *     - render
469
 *     - display
470
 *     - submit
471
 *     - delete
472
 *     - help
473
 *     - theme
474
 *     - analysis
475
 *     - table
476
 *     - csv_headers
477
 *     - csv_data
478
 *
479
 *   See the sample component implementation for details on each one of these
480
 *   callbacks.
481
 *
482
 * @see webform_components()
483
 */
484
function hook_webform_component_info() {
485
  $components = array();
486

    
487
  $components['textfield'] = array(
488
    'label' => t('Textfield'),
489
    'description' => t('Basic textfield type.'),
490
    'features' => array(
491
      // This component includes an analysis callback. Defaults to TRUE.
492
      'analysis' => TRUE,
493

    
494
      // Add content to CSV downloads. Defaults to TRUE.
495
      'csv' => TRUE,
496

    
497
      // This component supports default values. Defaults to TRUE.
498
      'default_value' => FALSE,
499

    
500
      // This component supports a description field. Defaults to TRUE.
501
      'description' => FALSE,
502

    
503
      // Show this component in e-mailed submissions. Defaults to TRUE.
504
      'email' => TRUE,
505

    
506
      // Allow this component to be used as an e-mail FROM or TO address.
507
      // Defaults to FALSE.
508
      'email_address' => FALSE,
509

    
510
      // Allow this component to be used as an e-mail SUBJECT or FROM name.
511
      // Defaults to FALSE.
512
      'email_name' => TRUE,
513

    
514
      // This component may be toggled as required or not. Defaults to TRUE.
515
      'required' => TRUE,
516

    
517
      // This component supports a title attribute. Defaults to TRUE.
518
      'title' => FALSE,
519

    
520
      // This component has a title that can be toggled as displayed or not.
521
      'title_display' => TRUE,
522

    
523
      // This component has a title that can be displayed inline.
524
      'title_inline' => TRUE,
525

    
526
      // If this component can be used as a conditional SOURCE. All components
527
      // may always be displayed conditionally, regardless of this setting.
528
      // Defaults to TRUE.
529
      'conditional' => TRUE,
530

    
531
      // If this component allows other components to be grouped within it
532
      // (like a fieldset or tabs). Defaults to FALSE.
533
      'group' => FALSE,
534

    
535
      // If this component can be used for SPAM analysis.
536
      'spam_analysis' => FALSE,
537

    
538
      // If this component saves a file that can be used as an e-mail
539
      // attachment. Defaults to FALSE.
540
      'attachment' => FALSE,
541

    
542
      // If this component reflects a time range and should use labels such as
543
      // "Before" and "After" when exposed as filters in Views module.
544
      'views_range' => FALSE,
545
    ),
546

    
547
    // Specify the conditional behaviour of this component.
548
    // Examples are 'string', 'date', 'time', 'numeric', 'select'.
549
    // Defaults to 'string'.
550
    'conditional_type' => 'string',
551

    
552
    'file' => 'components/textfield.inc',
553
  );
554

    
555
  return $components;
556
}
557

    
558
/**
559
 * Alter the list of available Webform components.
560
 *
561
 * @param $components
562
 *   A list of existing components as defined by hook_webform_component_info().
563
 *
564
 * @see hook_webform_component_info()
565
 */
566
function hook_webform_component_info_alter(&$components) {
567
  // Completely remove a component.
568
  unset($components['grid']);
569

    
570
  // Change the name of a component.
571
  $components['textarea']['label'] = t('Text box');
572
}
573

    
574
/**
575
 * Alter the list of Webform component default values.
576
 *
577
 * @param $defaults
578
 *   A list of component defaults as defined by _webform_defaults_COMPONENT().
579
 * @param $type
580
 *   The component type whose defaults are being provided.
581
 *
582
 * @see _webform_defaults_component()
583
 */
584
function hook_webform_component_defaults_alter(&$defaults, $type) {
585
  // Alter a default for all component types.
586
  $defaults['required'] = 1;
587

    
588
  // Add a default for a new field added via hook_form_alter() or
589
  // hook_form_FORM_ID_alter() for all component types.
590
  $defaults['extra']['added_field'] = t('Added default value');
591

    
592
  // Add or alter defaults for specific component types:
593
  switch ($type) {
594
    case 'select':
595
      $defaults['extra']['optrand'] = 1;
596
      break;
597

    
598
    case 'textfield':
599
    case 'textarea':
600
      $defaults['extra']['another_added_field'] = t('Another added default value');
601
  }
602
}
603

    
604
/**
605
 * Alter access to a Webform submission.
606
 *
607
 * @param $node
608
 *   The Webform node on which this submission was made.
609
 * @param $submission
610
 *   The Webform submission.
611
 * @param $op
612
 *   The operation to be performed on the submission. Possible values are:
613
 *   - "view"
614
 *   - "edit"
615
 *   - "delete"
616
 *   - "list"
617
 * @param $account
618
 *   A user account object.
619
 *
620
 * @return bool
621
 *   TRUE if the current user has access to submission,
622
 *   or FALSE otherwise.
623
 */
624
function hook_webform_submission_access($node, $submission, $op = 'view', $account = NULL) {
625
  switch ($op) {
626
    case 'view':
627
      return TRUE;
628

    
629
    case 'edit':
630
      return FALSE;
631

    
632
    case 'delete':
633
      return TRUE;
634

    
635
    case 'list':
636
      return TRUE;
637
  }
638
}
639

    
640
/**
641
 * Determine if a user has access to see the results of a webform.
642
 *
643
 * Note in addition to the view access to the results granted here, the $account
644
 * must also have view access to the Webform node in order to see results.
645
 * Access via this hook is in addition (adds permission) to the standard
646
 * webform access.
647
 *
648
 * @param $node
649
 *   The Webform node to check access on.
650
 * @param $account
651
 *   The user account to check access on.
652
 *
653
 * @return bool
654
 *   TRUE or FALSE if the user can access the webform results.
655
 *
656
 * @see webform_results_access()
657
 */
658
function hook_webform_results_access($node, $account) {
659
  // Let editors view results of unpublished webforms.
660
  if ($node->status == 0 && in_array('editor', $account->roles)) {
661
    return TRUE;
662
  }
663
  else {
664
    return FALSE;
665
  }
666
}
667

    
668
/**
669
 * Determine if a user has access to clear the results of a webform.
670
 *
671
 * Access via this hook is in addition (adds permission) to the standard
672
 * webform access (delete all webform submissions).
673
 *
674
 * @param object $node
675
 *   The Webform node to check access on.
676
 * @param object $account
677
 *   The user account to check access on.
678
 *
679
 * @return bool
680
 *   TRUE or FALSE if the user can access the webform results.
681
 *
682
 * @see webform_results_clear_access()
683
 */
684
function hook_webform_results_clear_access($node, $account) {
685
  return user_access('my additional access', $account);
686
}
687

    
688
/**
689
 * Overrides the node_access and user_access permissions.
690
 *
691
 * Overrides the node_access and user_access permission to access and edit
692
 * webform components, e-mails, conditions, and form settings.
693
 *
694
 * Return NULL to defer to other modules. If all implementations defer, then
695
 * access to the node's EDIT tab plus 'edit webform components' permission
696
 * determines access. To grant access, return TRUE; to deny access, return
697
 * FALSE. If more than one implementation return TRUE/FALSE, all must be TRUE
698
 * to grant access.
699
 *
700
 * In this way, access to the EDIT tab of the node may be decoupled from
701
 * access to the WEBFORM tab. When returning TRUE, consider all aspects of
702
 * access as this will be the only test. For example, 'return TRUE;' would grant
703
 * annonymous access to creating webform components, which seldom be desired.
704
 *
705
 * @param object $node
706
 *   The Webform node to check access on.
707
 * @param object $account
708
 *   The user account to check access on.
709
 *
710
 * @return bool|null
711
 *   TRUE or FALSE if the user can access the webform results, or NULL if
712
 *   access should be deferred to other implementations of this hook or
713
 *   node_access('update') plus user_access('edit webform components').
714
 *
715
 * @see webform_node_update_access()
716
 */
717
function hook_webform_update_access($node, $account) {
718
  // Allow anyone who can see webform_editable_by_user nodes and who has
719
  // 'my webform component edit access' permission to see, edit, and delete the
720
  // webform components, e-mails, conditionals, and form settings.
721
  if ($node->type == 'webform_editable_by_user') {
722
    return node_access('view', $node, $account) && user_access('my webform component edit access', $account);
723
  }
724
}
725

    
726
/**
727
 * Return an array of files associated with the component.
728
 *
729
 * The output of this function will be used to attach files to e-mail messages.
730
 *
731
 * @param $component
732
 *   A Webform component array.
733
 * @param $value
734
 *   An array of information containing the submission result, directly
735
 *   correlating to the webform_submitted_data database schema.
736
 *
737
 * @return array
738
 *   An array of files, each file is an array with following keys:
739
 *     - filepath: The relative path to the file.
740
 *     - filename: The name of the file including the extension.
741
 *     - filemime: The mimetype of the file.
742
 *   This will result in an array looking something like this:
743
 *
744
 * @code
745
 *   array[0] => array(
746
 *     'filepath' => '/sites/default/files/attachment.txt',
747
 *     'filename' => 'attachment.txt',
748
 *     'filemime' => 'text/plain',
749
 *   );
750
 * @endcode
751
 */
752
function _webform_attachments_component($component, $value) {
753
  $files = array();
754
  $files[] = (array) file_load($value[0]);
755
  return $files;
756
}
757

    
758
/**
759
 * Alter default settings for a newly created webform node.
760
 *
761
 * @param array $defaults
762
 *   Default settings for a newly created webform node as defined by webform_node_defaults().
763
 *
764
 * @see webform_node_defaults()
765
 */
766
function hook_webform_node_defaults_alter(array &$defaults) {
767
  $defaults['allow_draft'] = '1';
768
}
769

    
770
/**
771
 * Add additional fields to submission data downloads.
772
 *
773
 * @return array
774
 *   Keys and titles for default submission information.
775
 *
776
 * @see hook_webform_results_download_submission_information_data()
777
 */
778
function hook_webform_results_download_submission_information_info() {
779
  return array(
780
    'field_key_1' => t('Field Title 1'),
781
    'field_key_2' => t('Field Title 2'),
782
  );
783
}
784

    
785
/**
786
 * Return values for submission data download fields.
787
 *
788
 * @param $token
789
 *   The name of the token being replaced.
790
 * @param $submission
791
 *   The data for an individual submission from webform_get_submissions().
792
 * @param array $options
793
 *   A list of options that define the output format. These are generally passed
794
 *   through from the GUI interface.
795
 * @param $serial_start
796
 *   The starting position for the Serial column in the output.
797
 * @param $row_count
798
 *   The number of the row being generated.
799
 *
800
 * @return string
801
 *   Value for requested submission information field.
802
 *
803
 * @see hook_webform_results_download_submission_information_info()
804
 */
805
function hook_webform_results_download_submission_information_data($token, $submission, array $options, $serial_start, $row_count) {
806
  switch ($token) {
807
    case 'field_key_1':
808
      return 'Field Value 1';
809

    
810
    case 'field_key_2':
811
      return 'Field Value 2';
812
  }
813
}
814

    
815
/**
816
 * @}
817
 */
818

    
819
/**
820
 * @defgroup webform_component Sample Webform Component
821
 * @{
822
 * In each of these examples, the word "component" should be replaced with the,
823
 * name of the component type (such as textfield or select). These are not
824
 * actual hooks, but instead samples of how Webform integrates with its own
825
 * built-in components.
826
 */
827

    
828
/**
829
 * Specify the default properties of a component.
830
 *
831
 * @return array
832
 *   An array defining the default structure of a component.
833
 */
834
function _webform_defaults_component() {
835
  return array(
836
    'name' => '',
837
    'form_key' => NULL,
838
    'required' => 0,
839
    'pid' => 0,
840
    'weight' => 0,
841
    'extra' => array(
842
      'options' => '',
843
      'questions' => '',
844
      'optrand' => 0,
845
      'qrand' => 0,
846
      'description' => '',
847
      'description_above' => FALSE,
848
      'private' => FALSE,
849
      'analysis' => TRUE,
850
    ),
851
  );
852
}
853

    
854
/**
855
 * Generate the form for editing a component.
856
 *
857
 * Create a set of form elements to be displayed on the form for editing this
858
 * component. Use care naming the form items, as this correlates directly to the
859
 * database schema. The component "Name" and "Description" fields are added to
860
 * every component type and are not necessary to specify here (although they
861
 * may be overridden if desired).
862
 *
863
 * @param array $component
864
 *   A Webform component array.
865
 * @param array $form
866
 *   The form array.
867
 * @param array $form_state
868
 *   The form state array.
869
 *
870
 * @return array
871
 *   An array of form items to be displayed on the edit component page
872
 */
873
function _webform_edit_component(array $component, array &$form, array &$form_state) {
874
  // Disabling the description if not wanted.
875
  $form['description']['#access'] = FALSE;
876

    
877
  // Most options are stored in the "extra" array, which stores any settings
878
  // unique to a particular component type.
879
  $form['extra']['options'] = array(
880
    '#type' => 'textarea',
881
    '#title' => t('Options'),
882
    '#default_value' => $component['extra']['options'],
883
    '#description' => t('Key-value pairs may be entered separated by pipes. i.e. safe_key|Some readable option') . ' ' . theme('webform_token_help'),
884
    '#cols' => 60,
885
    '#rows' => 5,
886
    '#weight' => -3,
887
    '#required' => TRUE,
888
  );
889
  return $form;
890
}
891

    
892
/**
893
 * Render a Webform component to be part of a form.
894
 *
895
 * @param $component
896
 *   A Webform component array.
897
 * @param $value
898
 *   If editing an existing submission or resuming a draft, this will contain
899
 *   an array of values to be shown instead of the default in the component
900
 *   configuration. This value will always be an array, keyed numerically for
901
 *   each value saved in this field.
902
 * @param $filter
903
 *   Whether or not to filter the contents of descriptions and values when
904
 *   rendering the component. Values need to be unfiltered to be editable by
905
 *   Form Builder.
906
 * @param $submission
907
 *   The submission from which this component is being rendered. Usually not
908
 *   needed. Used by _webform_render_date() to validate using the submission's
909
 *   completion date.
910
 *
911
 * @return array
912
 *   $form_item
913
 *
914
 * @see _webform_client_form_add_component()
915
 */
916
function _webform_render_component($component, $value = NULL, $filter = TRUE, $submission = NULL) {
917
  $form_item = array(
918
    '#type' => 'textfield',
919
    '#title' => $filter ? webform_filter_xss($component['name']) : $component['name'],
920
    '#required' => $component['required'],
921
    '#weight' => $component['weight'],
922
    '#description'   => $filter ? webform_filter_descriptions($component['extra']['description']) : $component['extra']['description'],
923
    '#default_value' => $filter ? webform_replace_tokens($component['value']) : $component['value'],
924
    '#theme_wrappers' => array('webform_element'),
925
  );
926

    
927
  if (isset($value)) {
928
    $form_item['#default_value'] = $value[0];
929
  }
930

    
931
  return $form_item;
932
}
933

    
934
/**
935
 * Allow modules to modify a webform component that is going to be rendered in a form.
936
 *
937
 * @param array $element
938
 *   The display element as returned by _webform_render_component().
939
 * @param array $component
940
 *   A Webform component array.
941
 *
942
 * @see _webform_render_component()
943
 */
944
function hook_webform_component_render_alter(array &$element, array &$component) {
945
  if ($component['cid'] == 10) {
946
    $element['#title'] = 'My custom title';
947
    $element['#default_value'] = 42;
948
  }
949
}
950

    
951
/**
952
 * Display the result of a submission for a component.
953
 *
954
 * The output of this function will be displayed under the "Results" tab then
955
 * "Submissions". This should output the saved data in some reasonable manner.
956
 *
957
 * @param $component
958
 *   A Webform component array.
959
 * @param $value
960
 *   An array of information containing the submission result, directly
961
 *   correlating to the webform_submitted_data database table schema.
962
 * @param $format
963
 *   Either 'html' or 'text'. Defines the format that the content should be
964
 *   returned as. Make sure that returned content is run through check_plain()
965
 *   or other filtering functions when returning HTML.
966
 * @param $submission
967
 *   The submission. Used to generate tokens.
968
 *
969
 * @return array
970
 *   A renderable element containing at the very least these properties:
971
 *    - #title
972
 *    - #weight
973
 *    - #component
974
 *    - #format
975
 *    - #value
976
 *   Webform also uses #theme_wrappers to output the end result to the user,
977
 *   which will properly format the label and content for use within an e-mail
978
 *   (such as wrapping the text) or as HTML (ensuring consistent output).
979
 */
980
function _webform_display_component($component, $value, $format = 'html', $submission = array()) {
981
  return array(
982
    '#title' => $component['name'],
983
    '#weight' => $component['weight'],
984
    '#theme' => 'webform_display_textfield',
985
    '#theme_wrappers' => $format == 'html' ? array('webform_element') : array('webform_element_text'),
986
    '#post_render' => array('webform_element_wrapper'),
987
    '#field_prefix' => $component['extra']['field_prefix'],
988
    '#field_suffix' => $component['extra']['field_suffix'],
989
    '#component' => $component,
990
    '#format' => $format,
991
    '#value' => isset($value[0]) ? $value[0] : '',
992
  );
993
}
994

    
995
/**
996
 * Allow modules to modify a "display only" webform component.
997
 *
998
 * @param array $element
999
 *   The display element as returned by _webform_display_component().
1000
 * @param array $component
1001
 *   A Webform component array.
1002
 *
1003
 * @see _webform_display_component()
1004
 */
1005
function hook_webform_component_display_alter(array &$element, array &$component) {
1006
  if ($component['cid'] == 10) {
1007
    $element['#title'] = 'My custom title';
1008
    $element['#default_value'] = 42;
1009
  }
1010
}
1011

    
1012
/**
1013
 * Performs the conditional action set on an implemented component.
1014
 *
1015
 * Setting the form element allows form validation functions to see the value
1016
 * that webform has set for the given component.
1017
 *
1018
 * @param array $component
1019
 *   The webform component array whose value is being set for the currently-
1020
 *   edited submission.
1021
 * @param array $element
1022
 *   The form element currently being set.
1023
 * @param array $form_state
1024
 *   The form's state.
1025
 * @param string $value
1026
 *   The value to be set, as defined in the conditional action.
1027
 */
1028
function _webform_action_set_component(array $component, array &$element, array &$form_state, $value) {
1029
  $element['#value'] = $value;
1030
  form_set_value($element, $value, $form_state);
1031
}
1032

    
1033
/**
1034
 * A hook for changing the input values before saving to the database.
1035
 *
1036
 * Webform expects a component to consist of a single field, or a single array
1037
 * of fields. If you have a component that requires a deeper form tree
1038
 * you must flatten the data into a single array using this callback
1039
 * or by setting #parents on each field to avoid data loss and/or unexpected
1040
 * behavior.
1041
 *
1042
 * Note that Webform will save the result of this function directly into the
1043
 * database.
1044
 *
1045
 * @param $component
1046
 *   A Webform component array.
1047
 * @param $value
1048
 *   The POST data associated with the user input.
1049
 *
1050
 * @return array
1051
 *   An array of values to be saved into the database. Note that this should be
1052
 *   a numerically keyed array.
1053
 */
1054
function _webform_submit_component($component, $value) {
1055
  // Clean up a phone number into 123-456-7890 format.
1056
  if ($component['extra']['phone_number']) {
1057
    $number = preg_replace('/[^0-9]/', '', $value[0]);
1058
    if (strlen($number) == 7) {
1059
      $number = substr($number, 0, 3) . '-' . substr($number, 3, 4);
1060
    }
1061
    else {
1062
      $number = substr($number, 0, 3) . '-' . substr($number, 3, 3) . '-' . substr($number, 6, 4);
1063
    }
1064
  }
1065

    
1066
  $value[0] = $number;
1067
  return $value;
1068
}
1069

    
1070
/**
1071
 * Delete operation for a component or submission.
1072
 *
1073
 * @param $component
1074
 *   A Webform component array.
1075
 * @param $value
1076
 *   An array of information containing the submission result, directly
1077
 *   correlating to the webform_submitted_data database schema.
1078
 */
1079
function _webform_delete_component($component, $value) {
1080
  // Delete corresponding files when a submission is deleted.
1081
  if (!empty($value[0]) && ($file = webform_get_file($value[0]))) {
1082
    file_usage_delete($file, 'webform');
1083
    file_delete($file);
1084
  }
1085
}
1086

    
1087
/**
1088
 * Module specific instance of hook_help().
1089
 *
1090
 * This allows each Webform component to add information into hook_help().
1091
 */
1092
function _webform_help_component($section) {
1093
  switch ($section) {
1094
    case 'admin/config/content/webform#grid_description':
1095
      return t('Allows creation of grid questions, denoted by radio buttons.');
1096
  }
1097
}
1098

    
1099
/**
1100
 * Module specific instance of hook_theme().
1101
 *
1102
 * This allows each Webform component to add information into hook_theme(). If
1103
 * you specify a file to include, you must define the path to the module that
1104
 * this file belongs to.
1105
 */
1106
function _webform_theme_component() {
1107
  return array(
1108
    'webform_grid' => array(
1109
      'render element' => 'element',
1110
      'file' => 'components/grid.inc',
1111
      'path' => drupal_get_path('module', 'webform'),
1112
    ),
1113
    'webform_display_grid' => array(
1114
      'render element' => 'element',
1115
      'file' => 'components/grid.inc',
1116
      'path' => drupal_get_path('module', 'webform'),
1117
    ),
1118
  );
1119
}
1120

    
1121
/**
1122
 * Calculate and returns statistics about results for this component.
1123
 *
1124
 * This takes into account all submissions to this webform. The output of this
1125
 * function will be displayed under the "Results" tab then "Analysis".
1126
 *
1127
 * @param $component
1128
 *   An array of information describing the component, directly correlating to
1129
 *   the webform_component database schema.
1130
 * @param $sids
1131
 *   An optional array of submission IDs (sid). If supplied, the analysis will
1132
 *   be limited to these sids.
1133
 * @param $single
1134
 *   Boolean flag determining if the details about a single component are being
1135
 *   shown. May be used to provided detailed information about a single
1136
 *   component's analysis, such as showing "Other" options within a select list.
1137
 * @param $join
1138
 *   An optional SelectQuery object to be used to join with the submissions
1139
 *   table to restrict the submissions being analyzed.
1140
 *
1141
 * @return array
1142
 *   An array containing one or more of the following keys:
1143
 *   - table_rows: If this component has numeric data that can be represented in
1144
 *     a grid, return the values here. This array assumes a 2-dimensional
1145
 *     structure, with the first value being a label and subsequent values
1146
 *     containing a decimal or integer.
1147
 *   - table_header: If this component has more than a single set of values,
1148
 *     include a table header so each column can be labeled.
1149
 *   - other_data: If your component has non-numeric data to include, such as
1150
 *     a description or link, include that in the other_data array. Each item
1151
 *     may be a string or an array of values that matches the number of columns
1152
 *     in the table_header property.
1153
 *   At the very least, either table_rows or other_data should be provided.
1154
 *   Note that if you want your component's analysis to be available by default
1155
 *   without the user specifically enabling it, you must set
1156
 *   $component['extra']['analysis'] = TRUE in your
1157
 *   _webform_defaults_component() callback.
1158
 *
1159
 * @see _webform_defaults_component()
1160
 */
1161
function _webform_analysis_component($component, $sids = array(), $single = FALSE, $join = NULL) {
1162
  // Generate the list of options and questions.
1163
  $options = _webform_select_options_from_text($component['extra']['options'], TRUE);
1164
  $questions = _webform_select_options_from_text($component['extra']['questions'], TRUE);
1165

    
1166
  // Generate a lookup table of results.
1167
  $query = db_select('webform_submitted_data', 'wsd')
1168
    ->fields('wsd', array('no', 'data'))
1169
    ->condition('nid', $component['nid'])
1170
    ->condition('cid', $component['cid'])
1171
    ->condition('data', '', '<>')
1172
    ->groupBy('no')
1173
    ->groupBy('data');
1174
  $query->addExpression('COUNT(sid)', 'datacount');
1175

    
1176
  if (count($sids)) {
1177
    $query->condition('sid', $sids, 'IN');
1178
  }
1179

    
1180
  if ($join) {
1181
    $query->innerJoin($join, 'ws2_', 'wsd.sid = ws2_.sid');
1182
  }
1183

    
1184
  $result = $query->execute();
1185
  $counts = array();
1186
  foreach ($result as $data) {
1187
    $counts[$data->no][$data->data] = $data->datacount;
1188
  }
1189

    
1190
  // Create an entire table to be put into the returned row.
1191
  $rows = array();
1192
  $header = array('');
1193

    
1194
  // Add options as a header row.
1195
  foreach ($options as $option) {
1196
    $header[] = $option;
1197
  }
1198

    
1199
  // Add questions as each row.
1200
  foreach ($questions as $qkey => $question) {
1201
    $row = array($question);
1202
    foreach ($options as $okey => $option) {
1203
      $row[] = !empty($counts[$qkey][$okey]) ? $counts[$qkey][$okey] : 0;
1204
    }
1205
    $rows[] = $row;
1206
  }
1207

    
1208
  $other = array();
1209
  $other[] = l(t('More information'), 'node/' . $component['nid'] . '/webform-results/analysis/' . $component['cid']);
1210

    
1211
  return array(
1212
    'table_header' => $header,
1213
    'table_rows' => $rows,
1214
    'other_data' => $other,
1215
  );
1216
}
1217

    
1218
/**
1219
 * Return the result of a component value for display in a table.
1220
 *
1221
 * The output of this function will be displayed under the "Results" tab then
1222
 * "Table".
1223
 *
1224
 * @param $component
1225
 *   A Webform component array.
1226
 * @param $value
1227
 *   An array of information containing the submission result, directly
1228
 *   correlating to the webform_submitted_data database schema.
1229
 *
1230
 * @return string
1231
 *   Textual output formatted for human reading.
1232
 */
1233
function _webform_table_component($component, $value) {
1234
  $questions = array_values(_webform_component_options($component['extra']['questions']));
1235
  $output = '';
1236
  // Set the value as a single string.
1237
  if (is_array($value)) {
1238
    foreach ($value as $item => $value) {
1239
      if ($value !== '') {
1240
        $output .= $questions[$item] . ': ' . check_plain($value) . '<br />';
1241
      }
1242
    }
1243
  }
1244
  else {
1245
    $output = check_plain(!isset($value['0']) ? '' : $value['0']);
1246
  }
1247
  return $output;
1248
}
1249

    
1250
/**
1251
 * Return the header for this component to be displayed in a CSV file.
1252
 *
1253
 * The output of this function will be displayed under the "Results" tab then
1254
 * "Download".
1255
 *
1256
 * @param $component
1257
 *   A Webform component array.
1258
 * @param $export_options
1259
 *   An array of options that may configure export of this field.
1260
 *
1261
 * @return array
1262
 *   An array of data to be displayed in the first three rows of a CSV file, not
1263
 *   including either prefixed or trailing commas.
1264
 */
1265
function _webform_csv_headers_component($component, $export_options) {
1266
  $header = array();
1267
  $header[0] = array('');
1268
  $header[1] = array($export_options['header_keys'] ? $component['form_key'] : $component['name']);
1269
  $items = _webform_component_options($component['extra']['questions']);
1270
  $count = 0;
1271
  foreach ($items as $key => $item) {
1272
    // Empty column per sub-field in main header.
1273
    if ($count != 0) {
1274
      $header[0][] = '';
1275
      $header[1][] = '';
1276
    }
1277
    // The value for this option.
1278
    $header[2][] = $item;
1279
    $count++;
1280
  }
1281

    
1282
  return $header;
1283
}
1284

    
1285
/**
1286
 * Format the submitted data of a component for CSV downloading.
1287
 *
1288
 * The output of this function will be displayed under the "Results" tab then
1289
 * "Download".
1290
 *
1291
 * @param $component
1292
 *   A Webform component array.
1293
 * @param $export_options
1294
 *   An array of options that may configure export of this field.
1295
 * @param $value
1296
 *   An array of information containing the submission result, directly
1297
 *   correlating to the webform_submitted_data database schema.
1298
 *
1299
 * @return array
1300
 *   An array of items to be added to the CSV file. Each value within the array
1301
 *   will be another column within the file. This function is called once for
1302
 *   every row of data.
1303
 */
1304
function _webform_csv_data_component($component, $export_options, $value) {
1305
  $questions = array_keys(_webform_select_options($component['extra']['questions']));
1306
  $return = array();
1307
  foreach ($questions as $key => $question) {
1308
    $return[] = isset($value[$key]) ? $value[$key] : '';
1309
  }
1310
  return $return;
1311
}
1312

    
1313
/**
1314
 * Fix the view field(s) that are automatically generated for number components.
1315
 *
1316
 * Provides each component the opportunity to adjust how this component is
1317
 * displayed in a view as a field in a view table. For example, a component may
1318
 * modify how it responds to click-sorting. Or it may add additional fields,
1319
 * such as a grid component having a column for each question.
1320
 *
1321
 * @param array $component
1322
 *   A Webform component array.
1323
 * @param array $fields
1324
 *   An array of field-definition arrays. Will be passed one field definition,
1325
 *   which may be modified. Additional fields may be added to the array.
1326
 *
1327
 * @return array
1328
 *   The modified $fields array.
1329
 */
1330
function _webform_view_field_component(array $component, array $fields) {
1331
  foreach ($fields as &$field) {
1332
    $field['webform_datatype'] = 'number';
1333
  }
1334
  return $fields;
1335
}
1336

    
1337
/**
1338
 * Modify the how a view was expanded to show all the components.
1339
 *
1340
 * This alter function is only called when the view is actually modified. It
1341
 * provides modules an opportunity to alter the changes that webform made to
1342
 * the view.
1343
 *
1344
 * This hook is called from webform_views_pre_view. If another module also
1345
 * changes views by implementing this same views hook, the relative order of
1346
 * execution of the two implementations will depend upon the module weights of
1347
 * the two modules. Using hook_webform_view_alter instead guarantees an
1348
 * opportunity to modify the view AFTER webform.
1349
 *
1350
 * @param object $view
1351
 *   The view object.
1352
 * @param string $display_id
1353
 *   The display_id that was expanded by webform.
1354
 * @param array $args
1355
 *   The arguments that were passed to the view.
1356
 */
1357
function hook_webform_view_alter($view, $display_id, array $args) {
1358
  // Don't show component with cid == 4.
1359
  $fields = $view->get_items('field', $display_id);
1360
  foreach ($fields as $id => $field) {
1361
    if (isset($field['webform_cid']) && $field['webform_cid'] == 4) {
1362
      unset($fields[$id]);
1363
    }
1364
  }
1365
  $view->display[$display_id]->handler->set_option('fields', $fields);
1366
}
1367

    
1368
/**
1369
 * Modify the list of mail systems that are capable of sending HTML email.
1370
 *
1371
 * @param array &$systems
1372
 *   An array of mail system class names.
1373
 */
1374
function hook_webform_html_capable_mail_systems_alter(array &$systems) {
1375
  if (module_exists('my_module')) {
1376
    $systems[] = 'MyModuleMailSystem';
1377
  }
1378
}
1379

    
1380
/**
1381
 * Define a list of webform exporters.
1382
 *
1383
 * @return array
1384
 *   A list of the available exporters provided by the module.
1385
 *
1386
 * @see webform_webform_exporters()
1387
 */
1388
function hook_webform_exporters() {
1389
  $exporters = array(
1390
    'webform_exporter_custom' => array(
1391
      'title' => t('Webform exporter name'),
1392
      'description' => t('The description for this exporter.'),
1393
      'handler' => 'webform_exporter_custom',
1394
      'file' => drupal_get_path('module', 'yourmodule') . '/includes/webform_exporter_custom.inc',
1395
      'weight' => 10,
1396
    ),
1397
  );
1398

    
1399
  return $exporters;
1400
}
1401

    
1402
/**
1403
 * Modify the list of webform exporters definitions.
1404
 *
1405
 * @param array &$exporters
1406
 *   A list of all available webform exporters.
1407
 */
1408
function hook_webform_exporters_alter(array &$exporters) {
1409
  $exporters['excel']['handler'] = 'customized_excel_exporter';
1410
  $exporters['excel']['file'] = drupal_get_path('module', 'yourmodule') . '/includes/customized_excel_exporter.inc';
1411
}
1412

    
1413
/**
1414
 * @}
1415
 */