Project

General

Profile

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

root / drupal7 / sites / all / modules / webform / webform.api.php @ 8d02775b

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
 * the 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
 *     - private
450
 *
451
 *   Note that most of these features do not indicate the default state, but
452
 *   determine if the component can have this property at all. Setting
453
 *   "required" to TRUE does not mean that a component's fields will always be
454
 *   required, but instead give the option to the administrator to choose the
455
 *   requiredness. See the example implementation for details on how these
456
 *   features may be set.
457
 *
458
 *   An optional "file" may be specified to be loaded when the component is
459
 *   needed. A set of callbacks will be established based on the name of the
460
 *   component. All components follow the pattern:
461
 *
462
 *   _webform_[callback]_[component]
463
 *
464
 *   Where [component] is the name of the key of the component and [callback] is
465
 *   any of the following:
466
 *
467
 *     - defaults
468
 *     - edit
469
 *     - render
470
 *     - display
471
 *     - submit
472
 *     - delete
473
 *     - help
474
 *     - theme
475
 *     - analysis
476
 *     - table
477
 *     - csv_headers
478
 *     - csv_data
479
 *
480
 *   See the sample component implementation for details on each one of these
481
 *   callbacks.
482
 *
483
 * @see webform_components()
484
 */
485
function hook_webform_component_info() {
486
  $components = array();
487

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    
547
      // Set this to FALSE if this component cannot be used as a private
548
      // component. If this is not FALSE, in your implementation of
549
      // _webform_defaults_COMPONENT(), set ['extra']['private'] property to
550
      // TRUE or FALSE.
551
      'private' => FALSE,
552
    ),
553

    
554
    // Specify the conditional behaviour of this component.
555
    // Examples are 'string', 'date', 'time', 'numeric', 'select'.
556
    // Defaults to 'string'.
557
    'conditional_type' => 'string',
558

    
559
    'file' => 'components/textfield.inc',
560
  );
561

    
562
  return $components;
563
}
564

    
565
/**
566
 * Alter the list of available Webform components.
567
 *
568
 * @param $components
569
 *   A list of existing components as defined by hook_webform_component_info().
570
 *
571
 * @see hook_webform_component_info()
572
 */
573
function hook_webform_component_info_alter(&$components) {
574
  // Completely remove a component.
575
  unset($components['grid']);
576

    
577
  // Change the name of a component.
578
  $components['textarea']['label'] = t('Text box');
579
}
580

    
581
/**
582
 * Alter the list of Webform component default values.
583
 *
584
 * @param $defaults
585
 *   A list of component defaults as defined by _webform_defaults_COMPONENT().
586
 * @param $type
587
 *   The component type whose defaults are being provided.
588
 *
589
 * @see _webform_defaults_component()
590
 */
591
function hook_webform_component_defaults_alter(&$defaults, $type) {
592
  // Alter a default for all component types.
593
  $defaults['required'] = 1;
594

    
595
  // Add a default for a new field added via hook_form_alter() or
596
  // hook_form_FORM_ID_alter() for all component types.
597
  $defaults['extra']['added_field'] = t('Added default value');
598

    
599
  // Add or alter defaults for specific component types:
600
  switch ($type) {
601
    case 'select':
602
      $defaults['extra']['optrand'] = 1;
603
      break;
604

    
605
    case 'textfield':
606
    case 'textarea':
607
      $defaults['extra']['another_added_field'] = t('Another added default value');
608
  }
609
}
610

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

    
636
    case 'edit':
637
      return FALSE;
638

    
639
    case 'delete':
640
      return TRUE;
641

    
642
    case 'list':
643
      return TRUE;
644
  }
645
}
646

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

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

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

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

    
765
/**
766
 * Alter default settings for a newly created webform node.
767
 *
768
 * @param array $defaults
769
 *   Default settings for a newly created webform node as defined by
770
 *   webform_node_defaults().
771
 *
772
 * @see webform_node_defaults()
773
 */
774
function hook_webform_node_defaults_alter(array &$defaults) {
775
  $defaults['allow_draft'] = '1';
776
}
777

    
778
/**
779
 * Add additional fields to submission data downloads.
780
 *
781
 * @return array
782
 *   Keys and titles for default submission information.
783
 *
784
 * @see hook_webform_results_download_submission_information_data()
785
 */
786
function hook_webform_results_download_submission_information_info() {
787
  return array(
788
    'field_key_1' => t('Field Title 1'),
789
    'field_key_2' => t('Field Title 2'),
790
  );
791
}
792

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

    
818
    case 'field_key_2':
819
      return 'Field Value 2';
820
  }
821
}
822

    
823
/**
824
 * Alter the query that will produce the list of submission IDs to be
825
 * downloaded.
826
 *
827
 * @param object $query
828
 *   The query object that is being built up to provide the list of submission
829
 *   IDs.
830
 *
831
 * @see webform_download_sids_query()
832
 */
833
function hook_webform_download_sids_query_alter(&$query) {
834
  global $user;
835

    
836
  // check if component value matches a node ID and author of that node.
837
  $query->join('webform_submitted_data', 'wsd', 'ws.sid = wsd.sid');
838
  $query->condition('wsd.cid', 2);
839
  $query->join('node', 'n', 'wsd.data = n.nid');
840
  $query->condition('n.uid', $user->uid);
841
}
842

    
843
/**
844
 * @}
845
 */
846

    
847
/**
848
 * @defgroup webform_component Sample Webform Component
849
 * @{
850
 * In each of these examples, the word "component" should be replaced with the,
851
 * name of the component type (such as textfield or select). These are not
852
 * actual hooks, but instead samples of how Webform integrates with its own
853
 * built-in components.
854
 */
855

    
856
/**
857
 * Specify the default properties of a component.
858
 *
859
 * @return array
860
 *   An array defining the default structure of a component.
861
 */
862
function _webform_defaults_component() {
863
  return array(
864
    'name' => '',
865
    'form_key' => NULL,
866
    'required' => 0,
867
    'pid' => 0,
868
    'weight' => 0,
869
    'extra' => array(
870
      'options' => '',
871
      'questions' => '',
872
      'optrand' => 0,
873
      'qrand' => 0,
874
      'description' => '',
875
      'description_above' => FALSE,
876
      'private' => FALSE,
877
      'analysis' => TRUE,
878
    ),
879
  );
880
}
881

    
882
/**
883
 * Generate the form for editing a component.
884
 *
885
 * Create a set of form elements to be displayed on the form for editing this
886
 * component. Use care naming the form items, as this correlates directly to the
887
 * database schema. The component "Name" and "Description" fields are added to
888
 * every component type and are not necessary to specify here (although they
889
 * may be overridden if desired).
890
 *
891
 * @param array $component
892
 *   A Webform component array.
893
 * @param array $form
894
 *   The form array.
895
 * @param array $form_state
896
 *   The form state array.
897
 *
898
 * @return array
899
 *   Return $form with whatever changes are desired.
900
 */
901
function _webform_edit_component(array $component, array $form, array $form_state) {
902
  // Disabling the description if not wanted.
903
  $form['description']['#access'] = FALSE;
904

    
905
  // Most options are stored in the "extra" array, which stores any settings
906
  // unique to a particular component type.
907
  $form['extra']['options'] = array(
908
    '#type' => 'textarea',
909
    '#title' => t('Options'),
910
    '#default_value' => $component['extra']['options'],
911
    '#description' => t('Key-value pairs may be entered separated by pipes. i.e. safe_key|Some readable option') . ' ' . theme('webform_token_help'),
912
    '#cols' => 60,
913
    '#rows' => 5,
914
    '#weight' => -3,
915
    '#required' => TRUE,
916
  );
917
  return $form;
918
}
919

    
920
/**
921
 * Render a Webform component to be part of a form.
922
 *
923
 * @param $component
924
 *   A Webform component array.
925
 * @param $value
926
 *   If editing an existing submission or resuming a draft, this will contain
927
 *   an array of values to be shown instead of the default in the component
928
 *   configuration. This value will always be an array, keyed numerically for
929
 *   each value saved in this field.
930
 * @param $filter
931
 *   Whether or not to filter the contents of descriptions and values when
932
 *   rendering the component. Values need to be unfiltered to be editable by
933
 *   Form Builder.
934
 * @param $submission
935
 *   The submission from which this component is being rendered. Usually not
936
 *   needed. Used by _webform_render_date() to validate using the submission's
937
 *   completion date.
938
 *
939
 * @return array
940
 *   $form_item
941
 *
942
 * @see _webform_client_form_add_component()
943
 */
944
function _webform_render_component($component, $value = NULL, $filter = TRUE, $submission = NULL) {
945
  $form_item = array(
946
    '#type' => 'textfield',
947
    '#title' => $filter ? webform_filter_xss($component['name']) : $component['name'],
948
    '#required' => $component['required'],
949
    '#weight' => $component['weight'],
950
    '#description'   => $filter ? webform_filter_descriptions($component['extra']['description']) : $component['extra']['description'],
951
    '#default_value' => $filter ? webform_replace_tokens($component['value']) : $component['value'],
952
    '#theme_wrappers' => array('webform_element'),
953
  );
954

    
955
  if (isset($value)) {
956
    $form_item['#default_value'] = $value[0];
957
  }
958

    
959
  return $form_item;
960
}
961

    
962
/**
963
 * Allow modules to modify a webform component that will be rendered in a form.
964
 *
965
 * @param array $element
966
 *   The display element as returned by _webform_render_component().
967
 * @param array $component
968
 *   A Webform component array.
969
 *
970
 * @see _webform_render_component()
971
 */
972
function hook_webform_component_render_alter(array &$element, array &$component) {
973
  if ($component['cid'] == 10) {
974
    $element['#title'] = 'My custom title';
975
    $element['#default_value'] = 42;
976
  }
977
}
978

    
979
/**
980
 * Display the result of a submission for a component.
981
 *
982
 * The output of this function will be displayed under the "Results" tab then
983
 * "Submissions". This should output the saved data in some reasonable manner.
984
 *
985
 * @param $component
986
 *   A Webform component array.
987
 * @param $value
988
 *   An array of information containing the submission result, directly
989
 *   correlating to the webform_submitted_data database table schema.
990
 * @param $format
991
 *   Either 'html' or 'text'. Defines the format that the content should be
992
 *   returned as. Make sure that returned content is run through check_plain()
993
 *   or other filtering functions when returning HTML.
994
 * @param $submission
995
 *   The submission. Used to generate tokens.
996
 *
997
 * @return array
998
 *   A renderable element containing at the very least these properties:
999
 *    - #title
1000
 *    - #weight
1001
 *    - #component
1002
 *    - #format
1003
 *    - #value
1004
 *   Webform also uses #theme_wrappers to output the end result to the user,
1005
 *   which will properly format the label and content for use within an e-mail
1006
 *   (such as wrapping the text) or as HTML (ensuring consistent output).
1007
 */
1008
function _webform_display_component($component, $value, $format = 'html', $submission = array()) {
1009
  return array(
1010
    '#title' => $component['name'],
1011
    '#weight' => $component['weight'],
1012
    '#theme' => 'webform_display_textfield',
1013
    '#theme_wrappers' => $format == 'html' ? array('webform_element') : array('webform_element_text'),
1014
    '#post_render' => array('webform_element_wrapper'),
1015
    '#field_prefix' => $component['extra']['field_prefix'],
1016
    '#field_suffix' => $component['extra']['field_suffix'],
1017
    '#component' => $component,
1018
    '#format' => $format,
1019
    '#value' => isset($value[0]) ? $value[0] : '',
1020
  );
1021
}
1022

    
1023
/**
1024
 * Allow modules to modify a "display only" webform component.
1025
 *
1026
 * @param array $element
1027
 *   The display element as returned by _webform_display_component().
1028
 * @param array $component
1029
 *   A Webform component array.
1030
 *
1031
 * @see _webform_display_component()
1032
 */
1033
function hook_webform_component_display_alter(array &$element, array &$component) {
1034
  if ($component['cid'] == 10) {
1035
    $element['#title'] = 'My custom title';
1036
    $element['#default_value'] = 42;
1037
  }
1038
}
1039

    
1040
/**
1041
 * Performs the conditional action set on an implemented component.
1042
 *
1043
 * Setting the form element allows form validation functions to see the value
1044
 * that webform has set for the given component.
1045
 *
1046
 * @param array $component
1047
 *   The webform component array whose value is being set for the currently-
1048
 *   edited submission.
1049
 * @param array $element
1050
 *   The form element currently being set.
1051
 * @param array $form_state
1052
 *   The form's state.
1053
 * @param string $value
1054
 *   The value to be set, as defined in the conditional action.
1055
 */
1056
function _webform_action_set_component(array $component, array &$element, array &$form_state, $value) {
1057
  $element['#value'] = $value;
1058
  form_set_value($element, $value, $form_state);
1059
}
1060

    
1061
/**
1062
 * A hook for changing the input values before saving to the database.
1063
 *
1064
 * Webform expects a component to consist of a single field, or a single array
1065
 * of fields. If you have a component that requires a deeper form tree
1066
 * you must flatten the data into a single array using this callback
1067
 * or by setting #parents on each field to avoid data loss and/or unexpected
1068
 * behavior.
1069
 *
1070
 * Note that Webform will save the result of this function directly into the
1071
 * database.
1072
 *
1073
 * @param $component
1074
 *   A Webform component array.
1075
 * @param $value
1076
 *   The POST data associated with the user input.
1077
 *
1078
 * @return array
1079
 *   An array of values to be saved into the database. Note that this should be
1080
 *   a numerically keyed array.
1081
 */
1082
function _webform_submit_component($component, $value) {
1083
  // Clean up a phone number into 123-456-7890 format.
1084
  if ($component['extra']['phone_number']) {
1085
    $number = preg_replace('/[^0-9]/', '', $value[0]);
1086
    if (strlen($number) == 7) {
1087
      $number = substr($number, 0, 3) . '-' . substr($number, 3, 4);
1088
    }
1089
    else {
1090
      $number = substr($number, 0, 3) . '-' . substr($number, 3, 3) . '-' . substr($number, 6, 4);
1091
    }
1092
  }
1093

    
1094
  $value[0] = $number;
1095
  return $value;
1096
}
1097

    
1098
/**
1099
 * Delete operation for a component or submission.
1100
 *
1101
 * @param $component
1102
 *   A Webform component array.
1103
 * @param $value
1104
 *   An array of information containing the submission result, directly
1105
 *   correlating to the webform_submitted_data database schema.
1106
 */
1107
function _webform_delete_component($component, $value) {
1108
  // Delete corresponding files when a submission is deleted.
1109
  if (!empty($value[0]) && ($file = webform_get_file($value[0]))) {
1110
    file_usage_delete($file, 'webform');
1111
    file_delete($file);
1112
  }
1113
}
1114

    
1115
/**
1116
 * Module specific instance of hook_help().
1117
 *
1118
 * This allows each Webform component to add information into hook_help().
1119
 */
1120
function _webform_help_component($section) {
1121
  switch ($section) {
1122
    case 'admin/config/content/webform#grid_description':
1123
      return t('Allows creation of grid questions, denoted by radio buttons.');
1124
  }
1125
}
1126

    
1127
/**
1128
 * Module specific instance of hook_theme().
1129
 *
1130
 * This allows each Webform component to add information into hook_theme(). If
1131
 * you specify a file to include, you must define the path to the module that
1132
 * this file belongs to.
1133
 */
1134
function _webform_theme_component() {
1135
  return array(
1136
    'webform_grid' => array(
1137
      'render element' => 'element',
1138
      'file' => 'components/grid.inc',
1139
      'path' => drupal_get_path('module', 'webform'),
1140
    ),
1141
    'webform_display_grid' => array(
1142
      'render element' => 'element',
1143
      'file' => 'components/grid.inc',
1144
      'path' => drupal_get_path('module', 'webform'),
1145
    ),
1146
  );
1147
}
1148

    
1149
/**
1150
 * Calculate and returns statistics about results for this component.
1151
 *
1152
 * This takes into account all submissions to this webform. The output of this
1153
 * function will be displayed under the "Results" tab then "Analysis".
1154
 *
1155
 * @param $component
1156
 *   An array of information describing the component, directly correlating to
1157
 *   the webform_component database schema.
1158
 * @param $sids
1159
 *   An optional array of submission IDs (sid). If supplied, the analysis will
1160
 *   be limited to these sids.
1161
 * @param $single
1162
 *   Boolean flag determining if the details about a single component are being
1163
 *   shown. May be used to provided detailed information about a single
1164
 *   component's analysis, such as showing "Other" options within a select list.
1165
 * @param $join
1166
 *   An optional SelectQuery object to be used to join with the submissions
1167
 *   table to restrict the submissions being analyzed.
1168
 *
1169
 * @return array
1170
 *   An array containing one or more of the following keys:
1171
 *   - table_rows: If this component has numeric data that can be represented in
1172
 *     a grid, return the values here. This array assumes a 2-dimensional
1173
 *     structure, with the first value being a label and subsequent values
1174
 *     containing a decimal or integer.
1175
 *   - table_header: If this component has more than a single set of values,
1176
 *     include a table header so each column can be labeled.
1177
 *   - other_data: If your component has non-numeric data to include, such as
1178
 *     a description or link, include that in the other_data array. Each item
1179
 *     may be a string or an array of values that matches the number of columns
1180
 *     in the table_header property.
1181
 *   At the very least, either table_rows or other_data should be provided.
1182
 *   Note that if you want your component's analysis to be available by default
1183
 *   without the user specifically enabling it, you must set
1184
 *   $component['extra']['analysis'] = TRUE in your
1185
 *   _webform_defaults_component() callback.
1186
 *
1187
 * @see _webform_defaults_component()
1188
 */
1189
function _webform_analysis_component($component, $sids = array(), $single = FALSE, $join = NULL) {
1190
  // Generate the list of options and questions.
1191
  $options = _webform_select_options_from_text($component['extra']['options'], TRUE);
1192
  $questions = _webform_select_options_from_text($component['extra']['questions'], TRUE);
1193

    
1194
  // Generate a lookup table of results.
1195
  $query = db_select('webform_submitted_data', 'wsd')
1196
    ->fields('wsd', array('no', 'data'))
1197
    ->condition('nid', $component['nid'])
1198
    ->condition('cid', $component['cid'])
1199
    ->condition('data', '', '<>')
1200
    ->groupBy('no')
1201
    ->groupBy('data');
1202
  $query->addExpression('COUNT(sid)', 'datacount');
1203

    
1204
  if (count($sids)) {
1205
    $query->condition('sid', $sids, 'IN');
1206
  }
1207

    
1208
  if ($join) {
1209
    $query->innerJoin($join, 'ws2_', 'wsd.sid = ws2_.sid');
1210
  }
1211

    
1212
  $result = $query->execute();
1213
  $counts = array();
1214
  foreach ($result as $data) {
1215
    $counts[$data->no][$data->data] = $data->datacount;
1216
  }
1217

    
1218
  // Create an entire table to be put into the returned row.
1219
  $rows = array();
1220
  $header = array('');
1221

    
1222
  // Add options as a header row.
1223
  foreach ($options as $option) {
1224
    $header[] = $option;
1225
  }
1226

    
1227
  // Add questions as each row.
1228
  foreach ($questions as $qkey => $question) {
1229
    $row = array($question);
1230
    foreach ($options as $okey => $option) {
1231
      $row[] = !empty($counts[$qkey][$okey]) ? $counts[$qkey][$okey] : 0;
1232
    }
1233
    $rows[] = $row;
1234
  }
1235

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

    
1239
  return array(
1240
    'table_header' => $header,
1241
    'table_rows' => $rows,
1242
    'other_data' => $other,
1243
  );
1244
}
1245

    
1246
/**
1247
 * Return the result of a component value for display in a table.
1248
 *
1249
 * The output of this function will be displayed under the "Results" tab then
1250
 * "Table".
1251
 *
1252
 * @param $component
1253
 *   A Webform component array.
1254
 * @param $value
1255
 *   An array of information containing the submission result, directly
1256
 *   correlating to the webform_submitted_data database schema.
1257
 *
1258
 * @return string
1259
 *   Textual output formatted for human reading.
1260
 */
1261
function _webform_table_component($component, $value) {
1262
  $questions = array_values(_webform_component_options($component['extra']['questions']));
1263
  $output = '';
1264
  // Set the value as a single string.
1265
  if (is_array($value)) {
1266
    foreach ($value as $item => $value) {
1267
      if ($value !== '') {
1268
        $output .= $questions[$item] . ': ' . check_plain($value) . '<br />';
1269
      }
1270
    }
1271
  }
1272
  else {
1273
    $output = check_plain(!isset($value['0']) ? '' : $value['0']);
1274
  }
1275
  return $output;
1276
}
1277

    
1278
/**
1279
 * Return the header for this component to be displayed in a CSV file.
1280
 *
1281
 * The output of this function will be displayed under the "Results" tab then
1282
 * "Download".
1283
 *
1284
 * @param $component
1285
 *   A Webform component array.
1286
 * @param $export_options
1287
 *   An array of options that may configure export of this field.
1288
 *
1289
 * @return array
1290
 *   An array of data to be displayed in the first three rows of a CSV file, not
1291
 *   including either prefixed or trailing commas.
1292
 */
1293
function _webform_csv_headers_component($component, $export_options) {
1294
  $header = array();
1295
  $header[0] = array('');
1296
  $header[1] = array($export_options['header_keys'] ? $component['form_key'] : $component['name']);
1297
  $items = _webform_component_options($component['extra']['questions']);
1298
  $count = 0;
1299
  foreach ($items as $key => $item) {
1300
    // Empty column per sub-field in main header.
1301
    if ($count != 0) {
1302
      $header[0][] = '';
1303
      $header[1][] = '';
1304
    }
1305
    // The value for this option.
1306
    $header[2][] = $item;
1307
    $count++;
1308
  }
1309

    
1310
  return $header;
1311
}
1312

    
1313
/**
1314
 * Format the submitted data of a component for CSV downloading.
1315
 *
1316
 * The output of this function will be displayed under the "Results" tab then
1317
 * "Download".
1318
 *
1319
 * @param $component
1320
 *   A Webform component array.
1321
 * @param $export_options
1322
 *   An array of options that may configure export of this field.
1323
 * @param $value
1324
 *   An array of information containing the submission result, directly
1325
 *   correlating to the webform_submitted_data database schema.
1326
 *
1327
 * @return array
1328
 *   An array of items to be added to the CSV file. Each value within the array
1329
 *   will be another column within the file. This function is called once for
1330
 *   every row of data.
1331
 */
1332
function _webform_csv_data_component($component, $export_options, $value) {
1333
  $questions = array_keys(_webform_select_options($component['extra']['questions']));
1334
  $return = array();
1335
  foreach ($questions as $key => $question) {
1336
    $return[] = isset($value[$key]) ? $value[$key] : '';
1337
  }
1338
  return $return;
1339
}
1340

    
1341
/**
1342
 * Fix the view field(s) that are automatically generated for number components.
1343
 *
1344
 * Provides each component the opportunity to adjust how this component is
1345
 * displayed in a view as a field in a view table. For example, a component may
1346
 * modify how it responds to click-sorting. Or it may add additional fields,
1347
 * such as a grid component having a column for each question.
1348
 *
1349
 * @param array $component
1350
 *   A Webform component array.
1351
 * @param array $fields
1352
 *   An array of field-definition arrays. Will be passed one field definition,
1353
 *   which may be modified. Additional fields may be added to the array.
1354
 *
1355
 * @return array
1356
 *   The modified $fields array.
1357
 */
1358
function _webform_view_field_component(array $component, array $fields) {
1359
  foreach ($fields as &$field) {
1360
    $field['webform_datatype'] = 'number';
1361
  }
1362
  return $fields;
1363
}
1364

    
1365
/**
1366
 * Modify the how a view was expanded to show all the components.
1367
 *
1368
 * This alter function is only called when the view is actually modified. It
1369
 * provides modules an opportunity to alter the changes that webform made to
1370
 * the view.
1371
 *
1372
 * This hook is called from webform_views_pre_view. If another module also
1373
 * changes views by implementing this same views hook, the relative order of
1374
 * execution of the two implementations will depend upon the module weights of
1375
 * the two modules. Using hook_webform_view_alter instead guarantees an
1376
 * opportunity to modify the view AFTER webform.
1377
 *
1378
 * @param object $view
1379
 *   The view object.
1380
 * @param string $display_id
1381
 *   The display_id that was expanded by webform.
1382
 * @param array $args
1383
 *   The arguments that were passed to the view.
1384
 */
1385
function hook_webform_view_alter($view, $display_id, array $args) {
1386
  // Don't show component with cid == 4.
1387
  $fields = $view->get_items('field', $display_id);
1388
  foreach ($fields as $id => $field) {
1389
    if (isset($field['webform_cid']) && $field['webform_cid'] == 4) {
1390
      unset($fields[$id]);
1391
    }
1392
  }
1393
  $view->display[$display_id]->handler->set_option('fields', $fields);
1394
}
1395

    
1396
/**
1397
 * Modify the list of mail systems that are capable of sending HTML email.
1398
 *
1399
 * @param array &$systems
1400
 *   An array of mail system class names.
1401
 */
1402
function hook_webform_html_capable_mail_systems_alter(array &$systems) {
1403
  if (module_exists('my_module')) {
1404
    $systems[] = 'MyModuleMailSystem';
1405
  }
1406
}
1407

    
1408
/**
1409
 * Define a list of webform exporters.
1410
 *
1411
 * @return array
1412
 *   A list of the available exporters provided by the module.
1413
 *
1414
 * @see webform_webform_exporters()
1415
 */
1416
function hook_webform_exporters() {
1417
  $exporters = array(
1418
    'webform_exporter_custom' => array(
1419
      'title' => t('Webform exporter name'),
1420
      'description' => t('The description for this exporter.'),
1421
      'handler' => 'webform_exporter_custom',
1422
      'file' => drupal_get_path('module', 'yourmodule') . '/includes/webform_exporter_custom.inc',
1423
      'weight' => 10,
1424
    ),
1425
  );
1426

    
1427
  return $exporters;
1428
}
1429

    
1430
/**
1431
 * Modify the list of webform exporters definitions.
1432
 *
1433
 * @param array &$exporters
1434
 *   A list of all available webform exporters.
1435
 */
1436
function hook_webform_exporters_alter(array &$exporters) {
1437
  $exporters['excel']['handler'] = 'customized_excel_exporter';
1438
  $exporters['excel']['file'] = drupal_get_path('module', 'yourmodule') . '/includes/customized_excel_exporter.inc';
1439
}
1440

    
1441
/**
1442
 * Declare conditional types and their operators.
1443
 *
1444
 * Each conditional type defined here may then be referenced in
1445
 * hook_webform_component_info(). For each type this hook also declares a set of
1446
 * operators that may be applied to a component of this conditional type in
1447
 * conditionals.
1448
 *
1449
 * @return array
1450
 *   A 2-dimensional array of operator configurations. The configurations are
1451
 *   keyed first by their conditional type then by operator key. Each operator
1452
 *   declaration is an array with the following keys:
1453
 *   - label: Translated label for this operator that is shown in the UI.
1454
 *   - comparison callback: A callback for server-side evaluation.
1455
 *   - js comparison callback: A JavaScript callback for client-side evaluation.
1456
 *     The callback will be looked for in the Drupal.webform object.
1457
 *   - form callback (optional): A form callback that allows configuring
1458
 *     additional parameters for this operator. Default:
1459
 *     'webform_conditional_operator_text'.
1460
 *
1461
 * @see hook_webform_component_info()
1462
 * @see callback_webform_conditional_comparision_operator()
1463
 * @see callback_webform_conditional_rule_value_form()
1464
 */
1465
function hook_webform_conditional_operator_info() {
1466
  $operators = array();
1467
  $operators['string']['not_equal'] = array(
1468
    'label' => t('is not'),
1469
    'comparison callback' => 'webform_conditional_operator_string_not_equal',
1470
    'js comparison callback' => 'conditionalOperatorStringNotEqual',
1471
  );
1472
  return $operators;
1473
}
1474

    
1475
/**
1476
 * Alter the list of operators and conditional types.
1477
 *
1478
 * @param array $operators
1479
 *   A data structure as described in hook_webform_conditional_operator_info().
1480
 *
1481
 * @see hook_webform_conditional_operator_info()
1482
 */
1483
function hook_webform_conditional_operators_alter(array &$operators) {
1484
  $operators['string']['not_equal']['label'] = t('not equal');
1485
}
1486

    
1487
/**
1488
 * Evaluate the operator for a given set of values.
1489
 *
1490
 * This function will be called two times with potentially different kinds of
1491
 * values: Once in _webform_client_form_validate() before any of the validate
1492
 * handlers or the _webform_submit_COMPONENT() callback is called, and once in
1493
 * webform_client_form_pages() after those handlers have been called.
1494
 *
1495
 * @param array $input_values
1496
 *   The values received from the browser.
1497
 * @param mixed $rule_value
1498
 *   The value as configured in the form callback.
1499
 * @param array $component
1500
 *   The component for which we are evaluating the operator.
1501
 *
1502
 * @return bool
1503
 *   The operation result.
1504
 */
1505
function callback_webfom_conditional_comparison_operator(array $input_values, $rule_value, array $component) {
1506
  foreach ($input_values as $value) {
1507
    if (strcasecmp($value, $rule_value)) {
1508
      return TRUE;
1509
    }
1510
  }
1511
  return FALSE;
1512
}
1513

    
1514
/**
1515
 * Define a form element that configures your operator.
1516
 *
1517
 * @param object $node
1518
 *   The node for which the conditionals are being configured.
1519
 *
1520
 * @return string|string[]
1521
 *   Either a single rendered form element or a rendered form element per
1522
 *   component (keyed by cid). Make sure that none of the rendered strings
1523
 *   contains any HTML IDs as the form element will be rendered multiple times.
1524
 *   The JavaScript will take care of adding the appropriate name attributes.
1525
 *
1526
 * @see _webform_conditional_expand_value_forms()
1527
 */
1528
function callback_webform_conditional_rule_value_form($node) {
1529
  $forms = [];
1530
  foreach ($node->webform['components'] as $cid => $component) {
1531
    if (webform_component_property($component['type'], 'conditional_type') == 'newsletter') {
1532
      $element = [
1533
        '#type' => 'select',
1534
        '#options' => [
1535
          'yes' => t('Opt-in'),
1536
          'no' => t('No opt-in'),
1537
        ],
1538
      ];
1539
      $forms[$cid] = drupal_render($element);
1540
    }
1541
  }
1542
  return $forms;
1543
}
1544

    
1545
/**
1546
 * @}
1547
 */