form.inc 38.8 KB
Newer Older
1
<?php
2
3
// $Id$

4
5
6
7
8
9
10
/**
 * @defgroup form Form generation
 * @{
 * Functions to enable output of HTML forms and form elements.
 *
 * Drupal uses these functions to achieve consistency in its form presentation,
 * while at the same time simplifying code and reducing the amount of HTML that
11
 * must be explicitly generated by modules. See the reference at
12
 * http://api.drupal.org/api/HEAD/file/developer/topics/forms_api_reference.html
13
 * and the quickstart guide at
14
 * http://api.drupal.org/api/HEAD/file/developer/topics/forms_api.html
15
16
17
 */

/**
18
 * Processes a form array and produces the HTML output of a form.
19
 * If there is input in the $_POST['edit'] variable, this function
20
21
 * will attempt to validate it, using drupal_validate_form(),
 * and then submit the form using drupal_submit_form().
22
23
 *
 * @param $form_id
24
 *   A unique string identifying the form. Allows each form to be
25
 *   themed. Pass NULL to suppress the form_id parameter (produces
26
 *   a shorter URL with method=get)
27
28
29
30
31
32
33
 * @param $form
 *   An associative array containing the structure of the form.
 * @param $callback
 *   An optional callback that will be used in addition to the form_id.
 *
 */
function drupal_get_form($form_id, &$form, $callback = NULL) {
34
  global $form_values, $form_submitted, $user, $form_button_counter;
35
36
37
38
39
  static $saved_globals = array();

  // Save globals in case of indirect recursive call
  array_push($saved_globals, array($form_values, $form_submitted, $form_button_counter));

40
  $form_values = array();
Dries's avatar
Dries committed
41
  $form_submitted = FALSE;
42
  $form_button_counter = array(0, 0);
Steven Wittens's avatar
Steven Wittens committed
43

44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
  $form = drupal_build_form($form_id, $form, $callback);

  if (!empty($_POST['edit']) && (($_POST['edit']['form_id'] == $form_id) || ($_POST['edit']['form_id'] == $callback))) {
    drupal_validate_form($form_id, $form, $callback);
    // IE does not send a button value when there is only one submit button (and no non-submit buttons)
    // and you submit by pressing enter.
    // In that case we accept a submission without button values.
    if (($form_submitted || (!$form_button_counter[0] && $form_button_counter[1])) && !form_get_errors()) {
      $redirect = drupal_submit_form($form_id, $form, $callback);
      drupal_redirect_form($form, $redirect);
    }
  }

  $output = drupal_render_form($form_id, $form, $callback);
  list($form_values, $form_submitted, $form_button_counter) = array_pop($saved_globals);
  return $output;
}

/**
 * Prepares a structured form array by adding required elements,
 * executing any hook_form_alter functions, and optionally inserting
 * a validation token to prevent tampering.
 *
 * @param $form_id
 *   A unique string identifying the form for validation, submission,
 *   theming, and hook_form_alter functions.
 * @param $form
 *   An associative array containing the structure of the form.
 * @param $callback
 *   An optional callback that will be used in addition to the form_id.
 *
 */
function drupal_build_form($form_id, &$form, $callback = NULL) {
77
78
  $form['#type'] = 'form';
  if (isset($form['#token'])) {
79
80
81
    // If the page cache is on and an anonymous user issues a GET request,
    // unset the token because the token in the cached page would not match,
    // because the token is based on the session ID.
82
83
    if (variable_get('cache', 0) && !$user->uid && $_SERVER['REQUEST_METHOD'] == 'GET') {
      unset($form['#token']);
84
    }
85
86
87
88
89
    else {
      // Make sure that a private key is set:
      if (!variable_get('drupal_private_key', '')) {
        variable_set('drupal_private_key', mt_rand());
      }
90

91
92
      $form['form_token'] = array('#type' => 'hidden', '#default_value' => md5(session_id() . $form['#token'] . variable_get('drupal_private_key', '')));
    }
93
  }
94

95
  if (isset($form_id)) {
96
    $form['form_id'] = array('#type' => 'hidden', '#value' => $form_id, '#id' => str_replace('_', '-', "edit-$form_id"));
97
  }
98
99
100
  if (!isset($form['#id'])) {
    $form['#id'] = $form_id;
  }
Steven Wittens's avatar
Steven Wittens committed
101

102
  $form += _element_info('form');
103

Dries's avatar
Dries committed
104
105
  if (!isset($form['#validate'])) {
    if (function_exists($form_id .'_validate')) {
106
      $form['#validate'] = array($form_id .'_validate' => array());
Dries's avatar
Dries committed
107
108
    }
    elseif (function_exists($callback .'_validate')) {
109
      $form['#validate'] = array($callback .'_validate' => array());
Dries's avatar
Dries committed
110
111
112
    }
  }

113
114
  if (!isset($form['#submit'])) {
    if (function_exists($form_id .'_submit')) {
115
116
      // we set submit here so that it can be altered but use reference for
      // $form_values because it will change later
117
      $form['#submit'] = array($form_id .'_submit' => array());
Dries's avatar
Dries committed
118
    }
119
    elseif (function_exists($callback .'_submit')) {
120
      $form['#submit'] = array($callback .'_submit' => array());
Dries's avatar
Dries committed
121
122
123
    }
  }

124
125
  foreach (module_implements('form_alter') as $module) {
    $function = $module .'_form_alter';
126
    $function($form_id, $form);
127
128
  }

129
  $form = form_builder($form_id, $form);
130

131
  return $form;
132
133
}

134
135
136
137
138
139
140
141
142
143
144
145
146
147

/**
 * Validates user-submitted form data from a global variable using
 * the validate functions defined in a structured form array.
 *
 * @param $form_id
 *   A unique string identifying the form for validation, submission,
 *   theming, and hook_form_alter functions.
 * @param $form
 *   An associative array containing the structure of the form.
 * @param $callback
 *   An optional callback that will be used in addition to the form_id.
 *
 */
148
function drupal_validate_form($form_id, $form, $callback = NULL) {
149
  global $form_values;
150
151
152
153
154
  static $validated_forms = array();

  if (isset($validated_forms[$form_id])) {
    return;
  }
155

156
157
  // If the session token was set by drupal_build_form(), ensure that it
  // matches the current user's session
158
  if (isset($form['#token'])) {
159
    if ($form_values['form_token'] != md5(session_id() . $form['#token'] . variable_get('drupal_private_key', ''))) {
160
      // setting this error will cause the form to fail validation
161
      form_set_error('form_token', t('Validation error, please try again. If this error persists, please contact the site administrator.'));
162
163
164
    }
  }

165
  _form_validate($form, $form_id);
166
  $validated_forms[$form_id] = TRUE;
167
168
}

169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
/**
 * Processes user-submitted form data from a global variable using
 * the submit functions defined in a structured form array.
 *
 * @param $form_id
 *   A unique string identifying the form for validation, submission,
 *   theming, and hook_form_alter functions.
 * @param $form
 *   An associative array containing the structure of the form.
 * @param $callback
 *   An optional callback that will be used in addition to the form_id.
 * @return
 *   A string containing the path of the page to display when processing
 *   is complete.
 *
 */
185
function drupal_submit_form($form_id, $form, $callback = NULL) {
186
187
  global $form_values;
  $default_args = array($form_id, &$form_values);
188

189
  if (isset($form['#submit'])) {
190
191
    foreach ($form['#submit'] as $function => $args) {
      if (function_exists($function)) {
192
        $args = array_merge($default_args, (array) $args);
193
194
        // Since we can only redirect to one page, only the last redirect will work
        $redirect = call_user_func_array($function, $args);
195
196
197
        if (isset($redirect)) {
          $goto = $redirect;
        }
Dries's avatar
Dries committed
198
199
      }
    }
200
  }
201
  return $goto;
202
203
}

204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
/**
 * Renders a structured form array into themed HTML.
 *
 * @param $form_id
 *   A unique string identifying the form for validation, submission,
 *   theming, and hook_form_alter functions.
 * @param $form
 *   An associative array containing the structure of the form.
 * @param $callback
 *   An optional callback that will be used in addition to the form_id.
 * @return
 *   A string containing the path of the page to display when processing
 *   is complete.
 *
 */
function drupal_render_form($form_id, &$form, $callback = NULL) {
  // Don't override #theme if someone already set it.
  if (!isset($form['#theme'])) {
    if (theme_get_function($form_id)) {
      $form['#theme'] = $form_id;
    }
    elseif (theme_get_function($callback)) {
      $form['#theme'] = $callback;
    }
  }

  if (isset($form['#pre_render'])) {
    foreach ($form['#pre_render'] as $function) {
      if (function_exists($function)) {
        $function($form_id, $form);
      }
    }
  }

238
  $output = drupal_render($form);
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
  return $output;
}

/**
 * Redirect the user to a URL after a form has been processed.
 *
 * @param $form
 *   An associative array containing the structure of the form.
 * @param $redirect
 *   An optional string containing the destination path to redirect
 *   to if none is specified by the form.
 *
 */
function drupal_redirect_form($form, $redirect = NULL) {
  if (isset($redirect)) {
    $goto = $redirect;
  }
  if (isset($form['#redirect'])) {
    $goto = $form['#redirect'];
  }
  if ($goto !== FALSE) {
    if (is_array($goto)) {
      call_user_func_array('drupal_goto', $goto);
    }
    elseif (!isset($goto)) {
      drupal_goto($_GET['q']);
    }
    else {
      drupal_goto($goto);
    }
  }
}

272
function _form_validate($elements, $form_id = NULL) {
273
274
275
276
277
278
  // Recurse through all children.
  foreach (element_children($elements) as $key) {
    if (isset($elements[$key]) && $elements[$key]) {
      _form_validate($elements[$key]);
    }
  }
279
  /* Validate the current input */
280
  if (!$elements['#validated']) {
281
    if (isset($elements['#needs_validation'])) {
282
283
284
285
286
      // An empty textfield returns '' so we use empty(). An empty checkbox
      // and a textfield could return '0' and empty('0') returns TRUE so we
      // need a special check for the '0' string.
      if ($elements['#required'] && empty($elements['#value']) && $elements['#value'] !== '0') {
        form_error($elements, t('%name field is required.', array('%name' => $elements['#title'])));
287
      }
288
289
290
291
292
293
294
295
296
297
298
299
300
301

      // Add legal choice check if element has #options. Can be skipped, but then you must validate your own element.
      if (isset($elements['#options']) && isset($elements['#value']) && !isset($elements['#DANGEROUS_SKIP_CHECK'])) {
        if ($elements['#type'] == 'select') {
          $options = form_options_flatten($elements['#options']);
        }
        else {
          $options = $elements['#options'];
        }
        if (is_array($elements['#value'])) {
          $value = $elements['#type'] == 'checkboxes' ? array_keys(array_filter($elements['#value'])) : $elements['#value'];
          foreach ($value as $v) {
            if (!isset($options[$v])) {
              form_error($elements, t('An illegal choice has been detected. Please contact the site administrator.'));
302
              watchdog('form', t('Illegal choice %choice in %name element.', array('%choice' => theme('placeholder', check_plain($v)), '%name' => theme_placeholder(empty($elements['#title']) ? $elements['#parents'][0] : $elements['#title']))), WATCHDOG_ERROR);
303
            }
304
305
          }
        }
306
307
        elseif (!isset($options[$elements['#value']])) {
          form_error($elements, t('An illegal choice has been detected. Please contact the site administrator.'));
308
          watchdog('form', t('Illegal choice %choice in %name element.', array('%choice' => theme_placeholder(check_plain($elements['#value'])), '%name' => theme('placeholder', empty($elements['#title']) ? $elements['#parents'][0] : $elements['#title']))), WATCHDOG_ERROR);
309
        }
310
311
312
313
      }
    }

    // User-applied checks.
Dries's avatar
Dries committed
314
    if (isset($elements['#validate'])) {
315
316
317
318
319
      foreach ($elements['#validate'] as $function => $args) {
        $args = array_merge(array($elements), $args);
        // for the full form we hand over a copy of $form_values
        if (isset($form_id)) {
          $args = array_merge(array($form_id, $GLOBALS['form_values']), $args);
320
        }
321
322
        if (function_exists($function))  {
          call_user_func_array($function, $args);
323
324
325
        }
      }
    }
326
    $elements['#validated'] = TRUE;
327
328
329
  }
}

330
331
332
333
334
/**
 * File an error against a form element. If the name of the element is
 * edit[foo][bar] then you may pass either foo or foo][bar as $name
 * foo will set an error for all its children.
 */
335
function form_set_error($name = NULL, $message = '') {
336
337
338
  static $form = array();
  if (isset($name) && !isset($form[$name])) {
    $form[$name] = $message;
339
340
341
    if ($message) {
      drupal_set_message($message, 'error');
    }
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
  }
  return $form;
}

/**
 * Return an associative array of all errors.
 */
function form_get_errors() {
  $form = form_set_error();
  if (!empty($form)) {
    return $form;
  }
}

/**
 * Return the error message filed against the form with the specified name.
 */
function form_get_error($element) {
  $form = form_set_error();
  $key = $element['#parents'][0];
  if (isset($form[$key])) {
    return $form[$key];
  }
  $key = implode('][', $element['#parents']);
  if (isset($form[$key])) {
    return $form[$key];
  }
}

371
372
373
/**
 * Flag an element as having an error.
 */
374
function form_error(&$element, $message = '') {
375
  $element['#error'] = TRUE;
376
  form_set_error(implode('][', $element['#parents']), $message);
377
378
379
}

/**
380
381
382
383
384
385
 * Adds some required properties to each form element, which are used
 * internally in the form api. This function also automatically assigns
 * the value property from the $edit array, provided the element doesn't
 * already have an assigned value.
 *
 * @param $form_id
386
387
 *   A unique string identifying the form for validation, submission,
 *   theming, and hook_form_alter functions.
388
389
 * @param $form
 *   An associative array containing the structure of the form.
390
 */
391
function form_builder($form_id, $form) {
392
  global $form_values, $form_submitted, $form_button_counter;
393

394
395
396
  // Initialize as unprocessed.
  $form['#processed'] = FALSE;

397
  /* Use element defaults */
398
  if ((!empty($form['#type'])) && ($info = _element_info($form['#type']))) {
399
    // overlay $info onto $form, retaining preexisting keys in $form
400
401
402
    $form += $info;
  }

403
  if (isset($form['#input']) && $form['#input']) {
404
405
406
407
408
409
    if (!isset($form['#name'])) {
      $form['#name'] = 'edit[' . implode('][', $form['#parents']) . ']';
    }
    if (!isset($form['#id'])) {
      $form['#id'] =  'edit-' . implode('-', $form['#parents']);
    }
410

411
    $posted = (isset($_POST['edit']) && ($_POST['edit']['form_id'] == $form_id));
412
    $edit = $posted ? $_POST['edit'] : array();
413
    foreach ($form['#parents'] as $parent) {
414
415
      $edit = isset($edit[$parent]) ? $edit[$parent] : NULL;
    }
416
    if (!isset($form['#value']) && !array_key_exists('#value', $form)) {
417
      if ($posted) {
418
419
        switch ($form['#type']) {
          case 'checkbox':
420
            $form['#value'] = !empty($edit) ? $form['#return_value'] : 0;
421
422
            break;
          case 'select':
423
424
425
426
427
428
429
            if (isset($form['#multiple']) && $form['#multiple']) {
              if (isset($edit) && is_array($edit)) {
                $form['#value'] = drupal_map_assoc($edit);
              }
              else {
                $form['#value'] = array();
              }
430
            }
431
432
            elseif (isset($edit)) {
              $form['#value'] = $edit;
433
            }
434
435
436
            break;
          case 'textfield':
            if (isset($edit)) {
437
438
439
              // Equate $edit to the form value to ensure it's marked for validation
              $edit = str_replace(array("\r", "\n"), '', $edit);
              $form['#value'] = $edit;
440
441
442
443
444
445
            }
            break;
          default:
            if (isset($edit)) {
              $form['#value'] = $edit;
            }
446
        }
447
        // Mark all posted values for validation
448
        if ((isset($form['#value']) && $form['#value'] === $edit) || (isset($form['#required']) && $form['#required'])) {
449
          $form['#needs_validation'] = TRUE;
450
451
452
        }
      }
      if (!isset($form['#value'])) {
453
454
455
456
457
458
459
        $function = $form['#type'] . '_value';
        if (function_exists($function)) {
          $function($form);
        }
        else {
          $form['#value'] = $form['#default_value'];
        }
460
      }
461
    }
462
463
464
465
466
    if (isset($form['#executes_submit_callback'])) {
      // Count submit and non-submit buttons
      $form_button_counter[$form['#executes_submit_callback']]++;
      // See if a submit button was pressed
      if (isset($_POST[$form['#name']]) && $_POST[$form['#name']] == $form['#value']) {
467
        $form_submitted = $form_submitted || $form['#executes_submit_callback'];
468
469
470
471
      }
    }
  }

472
  // Allow for elements to expand to multiple elements, e.g. radios, checkboxes and files.
473
  if (isset($form['#process']) && !$form['#processed']) {
474
475
    foreach ($form['#process'] as $process => $args) {
      if (function_exists($process)) {
476
477
        $args = array_merge(array($form), $args);
        $form = call_user_func_array($process, $args);
478
479
      }
    }
480
    $form['#processed'] = TRUE;
481
482
  }

483
484
485
  // Set the $form_values key that gets passed to validate and submit.
  // We call this after #process gets called so that #process has a
  // chance to update #value if desired.
486
  if (isset($form['#input']) && $form['#input']) {
487
    form_set_value($form, $form['#value']);
488
489
  }

490
491
492
  // Recurse through all child elements.
  $count  = 0;
  foreach (element_children($form) as $key) {
Steven Wittens's avatar
Steven Wittens committed
493
    // don't squash an existing tree value
494
495
496
    if (!isset($form[$key]['#tree'])) {
      $form[$key]['#tree'] = $form['#tree'];
    }
Steven Wittens's avatar
Steven Wittens committed
497

498
499
    // don't squash existing parents value
    if (!isset($form[$key]['#parents'])) {
500
501
      // Check to see if a tree of child elements is present. If so, continue down the tree if required.
      $form[$key]['#parents'] = $form[$key]['#tree'] && $form['#tree'] ? array_merge($form['#parents'], array($key)) : array($key);
Steven Wittens's avatar
Steven Wittens committed
502
503
    }

504
    # Assign a decimal placeholder weight to preserve original array order
505
506
507
    if (!isset($form[$key]['#weight'])) {
      $form[$key]['#weight'] = $count/1000;
    }
508
    $form[$key] = form_builder($form_id, $form[$key]);
509
510
511
    $count++;
  }

512
513
514
515
516
517
  if (isset($form['#after_build']) && !isset($form['#after_build_done'])) {
    foreach ($form['#after_build'] as $function) {
      if (function_exists($function)) {
        $form = $function($form, $form_values);
      }
    }
518
    $form['#after_build_done'] = TRUE;
Steven Wittens's avatar
Steven Wittens committed
519
  }
520
521

  return $form;
522
523
}

524
/**
Dries's avatar
Dries committed
525
 * Use this function to make changes to form values in the form validate
526
527
528
529
 * phase, so they will be available in the submit phase in $form_values.
 *
 * Specifically, if $form['#parents'] is array('foo', 'bar')
 * and $value is 'baz' then this function will make
Dries's avatar
Dries committed
530
 * $form_values['foo']['bar'] to be 'baz'.
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
 *
 * @param $form
 *   The form item. Keys used: #parents, #value
 * @param $value
 *   The value for the form item.
 */
function form_set_value($form, $value) {
  global $form_values;
  _form_set_value($form_values, $form, $form['#parents'], $value);
}

/**
 * Helper function for form_set_value().
 *
 * We iterate of $parents and create nested arrays for them
 * in $form_values if needed. Then we insert the value in
 * the right array.
 */
function _form_set_value(&$form_values, $form, $parents, $value) {
  $parent = array_shift($parents);
  if (empty($parents)) {
    $form_values[$parent] = $value;
  }
  else {
    if (!isset($form_values[$parent])) {
      $form_values[$parent] = array();
    }
    _form_set_value($form_values[$parent], $form, $parents, $value);
  }
  return $form;
}

563
564
565
/**
 * Retrieve the default properties for the defined element type.
 */
566
function _element_info($type, $refresh = NULL) {
567
  static $cache;
Steven Wittens's avatar
Steven Wittens committed
568

569
  $basic_defaults = array(
570
571
572
    '#description' => NULL,
    '#attributes' => array(),
    '#required' => FALSE,
Steven Wittens's avatar
Steven Wittens committed
573
    '#tree' => FALSE,
574
    '#parents' => array()
575
  );
576
  if (!isset($cache) || $refresh) {
577
578
579
    $cache = array();
    foreach (module_implements('elements') as $module) {
      $elements = module_invoke($module, 'elements');
580
      if (isset($elements) && is_array($elements)) {
581
        $cache = array_merge_recursive($cache, $elements);
582
583
584
585
      }
    }
    if (sizeof($cache)) {
      foreach ($cache as $element_type => $info) {
586
        $cache[$element_type] = array_merge_recursive($basic_defaults, $info);
587
588
589
590
591
592
593
      }
    }
  }

  return $cache[$type];
}

594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
function form_options_flatten($array, $reset = TRUE) {
  static $return;

  if ($reset) {
    $return = array();
  }

  foreach ($array as $key => $value) {
    if (is_array($value)) {
      form_options_flatten($value, FALSE);
    }
    else {
      $return[$key] = 1;
    }
  }

  return $return;
}

613
614
615
616
617
/**
 * Format a dropdown menu or scrolling selection box.
 *
 * @param $element
 *   An associative array containing the properties of the element.
618
 *   Properties used: title, value, options, description, extra, multiple, required
619
620
621
622
623
624
625
626
627
 * @return
 *   A themed HTML string representing the form element.
 *
 * It is possible to group options together; to do this, change the format of
 * $options to an associative array in which the keys are group labels, and the
 * values are associative arrays in the normal $options format.
 */
function theme_select($element) {
  $select = '';
628
  $size = $element['#size'] ? ' size="' . $element['#size'] . '"' : '';
629
  _form_set_class($element, array('form-select'));
630
631
  $multiple = isset($element['#multiple']) && $element['#multiple'];
  return theme('form_element', $element, '<select name="'. $element['#name'] .''. ($multiple ? '[]' : '') .'"'. ($multiple ? ' multiple="multiple" ' : '') . drupal_attributes($element['#attributes']) .' id="'. $element['#id'] .'" '. $size .'>'. form_select_options($element) .'</select>');
632
633
634
635
636
637
}

function form_select_options($element, $choices = NULL) {
  if (!isset($choices)) {
    $choices = $element['#options'];
  }
638
  // array_key_exists() accommodates the rare event where $element['#value'] is NULL.
639
640
641
  // isset() fails in this situation.
  $value_valid = isset($element['#value']) || array_key_exists('#value', $element);
  $value_is_array = is_array($element['#value']);
642
643
  $options = '';
  foreach ($choices as $key => $choice) {
644
    if (is_array($choice)) {
645
646
647
      $options .= '<optgroup label="'. $key .'">';
      $options .= form_select_options($element, $choice);
      $options .= '</optgroup>';
648
649
    }
    else {
650
651
      $key = (string)$key;
      if ($value_valid && ($element['#value'] == $key || ($value_is_array && in_array($key, $element['#value'])))) {
652
653
654
655
656
        $selected = ' selected="selected"';
      }
      else {
        $selected = '';
      }
657
      $options .= '<option value="'. $key .'"'. $selected .'>'. check_plain($choice) .'</option>';
658
659
    }
  }
660
  return $options;
661
662
663
664
665
666
667
}

/**
 * Format a group of form items.
 *
 * @param $element
 *   An associative array containing the properties of the element.
668
 *   Properties used: attributes, title, value, description, children, collapsible, collapsed
669
670
671
672
 * @return
 *   A themed HTML string representing the form item group.
 */
function theme_fieldset($element) {
673
  if ($element['#collapsible']) {
674
675
    drupal_add_js('misc/collapse.js');

676
677
678
    $element['#attributes']['class'] .= ' collapsible';
    if ($element['#collapsed']) {
     $element['#attributes']['class'] .= ' collapsed';
679
680
681
    }
  }

682
  return '<fieldset' . drupal_attributes($element['#attributes']) .'>' . ($element['#title'] ? '<legend>'. $element['#title'] .'</legend>' : '') . ($element['#description'] ? '<div class="description">'. $element['#description'] .'</div>' : '') . $element['#children'] . $element['#value'] . "</fieldset>\n";
683
684
685
686
687
688
689
}

/**
 * Format a radio button.
 *
 * @param $element
 *   An associative array containing the properties of the element.
690
 *   Properties used: required, return_value, value, attributes, title, description
691
692
693
694
 * @return
 *   A themed HTML string representing the form item group.
 */
function theme_radio($element) {
695
  _form_set_class($element, array('form-radio'));
696
  $output = '<input type="radio" ';
697
698
699
700
701
702
  $output .= 'name="' . $element['#name'] .'" ';
  $output .= 'value="'. $element['#return_value'] .'" ';
  $output .= ($element['#value'] == $element['#return_value']) ? ' checked="checked" ' : ' ';
  $output .= drupal_attributes($element['#attributes']) .' />';
  if (!is_null($element['#title'])) {
    $output = '<label class="option">'. $output .' '. $element['#title'] .'</label>';
703
  }
704
705
706

  unset($element['#title']);
  return theme('form_element', $element, $output);
707
708
709
710
711
712
713
}

/**
 * Format a set of radio buttons.
 *
 * @param $element
 *   An associative array containing the properties of the element.
714
 *   Properties used: title, value, options, description, required and attributes.
715
716
717
718
 * @return
 *   A themed HTML string representing the radio button set.
 */
function theme_radios($element) {
719
  if ($element['#title'] || $element['#description']) {
720
721
    unset($element['#id']);
    return theme('form_element', $element, $element['#children']);
722
723
  }
  else {
724
    return $element['#children'];
725
726
727
  }
}

728
729
730
731
732
733
734
735
736
737
/**
 * Format a password_confirm item.
 *
 * @param $element
 *   An associative array containing the properties of the element.
 *   Properties used: title, value, id, required, error.
 * @return
 *   A themed HTML string representing the form item.
 */
function theme_password_confirm($element) {
Dries's avatar
Dries committed
738
  return theme('form_element', $element, $element['#children']);
739
740
}

741
742
743
744
/*
 * Expand a password_confirm field into two text boxes.
 */
function expand_password_confirm($element) {
Dries's avatar
Dries committed
745
746
747
748
749
750
751
752
753
754
  $element['pass1'] =  array(
    '#type' => 'password',
    '#title' => t('Password'),
    '#value' => $element['#value']['pass1'],
  );
  $element['pass2'] =  array(
    '#type' => 'password',
    '#title' => t('Confirm password'),
    '#value' => $element['#value']['pass2'],
  );
755
756
757
758
759
760
  $element['#validate'] = array('password_confirm_validate' => array());
  $element['#tree'] = TRUE;

  return $element;
}

761
/**
762
 * Validate password_confirm element.
763
 */
764
function password_confirm_validate($form) {
765
766
  $pass1 = trim($form['pass1']['#value']);
  if (!empty($pass1)) {
767
    $pass2 = trim($form['pass2']['#value']);
768
    if ($pass1 != $pass2) {
769
      form_error($form, t('The specified passwords do not match.'));
770
    }
771
772
  }
  elseif ($form['#required'] && !empty($_POST['edit'])) {
773
    form_error($form, t('Password field is required.'));
774
  }
775

776
777
778
779
780
781
  // Password field must be converted from a two-element array into a single
  // string regardless of validation results.
  form_set_value($form['pass1'], NULL);
  form_set_value($form['pass2'], NULL);
  form_set_value($form, $pass1);

782
783
784
  return $form;
}

785
/**
786
 * Format a date selection element.
787
788
789
 *
 * @param $element
 *   An associative array containing the properties of the element.
790
 *   Properties used: title, value, options, description, required and attributes.
791
 * @return
792
 *   A themed HTML string representing the date selection boxes.
793
794
 */
function theme_date($element) {
795
  return theme('form_element', $element, '<div class="container-inline">'. $element['#children'] .'</div>');
796
797
798
}

/**
799
 * Roll out a single date element.
800
801
802
 */
function expand_date($element) {
  // Default to current date
803
804
  if (!isset($element['#value'])) {
    $element['#value'] = array('day' => format_date(time(), 'custom', 'j'),
805
806
807
808
                            'month' => format_date(time(), 'custom', 'n'),
                            'year' => format_date(time(), 'custom', 'Y'));
  }

809
810
  $element['#tree'] = TRUE;

811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
  // Determine the order of day, month, year in the site's chosen date format.
  $format = variable_get('date_format_short', 'm/d/Y');
  $sort = array();
  $sort['day'] = max(strpos($format, 'd'), strpos($format, 'j'));
  $sort['month'] = max(strpos($format, 'm'), strpos($format, 'M'));
  $sort['year'] = strpos($format, 'Y');
  asort($sort);
  $order = array_keys($sort);

  // Output multi-selector for date
  foreach ($order as $type) {
    switch ($type) {
      case 'day':
        $options = drupal_map_assoc(range(1, 31));
        break;
      case 'month':
827
        $options = drupal_map_assoc(range(1, 12), 'map_month');
828
829
830
831
832
        break;
      case 'year':
        $options = drupal_map_assoc(range(1900, 2050));
        break;
    }
833
834
835
836
837
838
839
840
    $parents = $element['#parents'];
    $parents[] = $type;
    $element[$type] = array(
      '#type' => 'select',
      '#value' => $element['#value'][$type],
      '#attributes' => $element['#attributes'],
      '#options' => $options,
    );
841
842
843
844
845
  }

  return $element;
}

846
847
848
849
850
851
852
853
854
/**
 * Validates the date type to stop dates like February 30, 2006.
 */
function date_validate($form) {
  if (!checkdate($form['#value']['month'], $form['#value']['day'], $form['#value']['year'])) {
    form_error($form, t('The specified date is invalid.'));
  }
}

855
856
857
858
859
860
/**
 * Helper function for usage with drupal_map_assoc to display month names.
 */
function map_month($month) {
  return format_date(gmmktime(0, 0, 0, $month, 2, 1970), 'custom', 'M', 0);
}
861

862
863
864
865
866
867
868
869
870
871
872
/**
 * Helper function to load value from default value for checkboxes
 */
function checkboxes_value(&$form) {
  $value = array();
  foreach ((array)$form['#default_value'] as $key) {
    $value[$key] = 1;
  }
  $form['#value'] = $value;
}

873
874
875
876
877
878
879
880
881
882
883
884
/**
 * If no default value is set for weight select boxes, use 0.
 */
function weight_value(&$form) {
  if (isset($form['#default_value'])) {
    $form['#value'] = $form['#default_value'];
  }
  else {
    $form['#value'] = 0;
  }
}

885
/**
886
887
 * Roll out a single radios element to a list of radios,
 * using the options array as index.
888
889
 */
function expand_radios($element) {
890
891
  if (count($element['#options']) > 0) {
    foreach ($element['#options'] as $key => $choice) {
892
      if (!isset($element[$key])) {
893
        $element[$key] = array('#type' => 'radio', '#title' => $choice, '#return_value' => $key, '#default_value' => $element['#default_value'], '#attributes' => $element['#attributes'], '#parents' => $element['#parents'], '#spawned' => TRUE);
894
895
896
897
898
899
900
901
902
903
904
      }
    }
  }
  return $element;
}

/**
 * Format a form item.
 *
 * @param $element
 *   An associative array containing the properties of the element.
905
 *   Properties used:  title, value, description, required, error
906
907
908
909
 * @return
 *   A themed HTML string representing the form item.
 */
function theme_item($element) {
910
  return theme('form_element', $element, $element['#value'] . $element['#children']);
911
912
913
914
915
916
917
}

/**
 * Format a checkbox.
 *
 * @param $element
 *   An associative array containing the properties of the element.
918
 *   Properties used:  title, value, return_value, description, required
919
920
921
922
 * @return
 *   A themed HTML string representing the checkbox.
 */
function theme_checkbox($element) {
923
  _form_set_class($element, array('form-checkbox'));
924
925
  $checkbox = '<input ';
  $checkbox .= 'type="checkbox" ';
926
927
928
  $checkbox .= 'name="'. $element['#name'] .'" ';
  $checkbox .= 'id="'. $element['#id'].'" ' ;
  $checkbox .= 'value="'. $element['#return_value'] .'" ';
929
  $checkbox .= $element['#value'] ? ' checked="checked" ' : ' ';
930
931
932
933
  $checkbox .= drupal_attributes($element['#attributes']) . ' />';

  if (!is_null($element['#title'])) {
    $checkbox = '<label class="option">'. $checkbox .' '. $element['#title'] .'</label>';
934
935
  }

936
937
  unset($element['#title']);
  return theme('form_element', $element, $checkbox);
938
939
940
941
942
943
944
945
946
947
948
}

/**
 * Format a set of checkboxes.
 *
 * @param $element
 *   An associative array containing the properties of the element.
 * @return
 *   A themed HTML string representing the checkbox set.
 */
function theme_checkboxes($element) {
949
  if ($element['#title'] || $element['#description']) {
950
951
    unset($element['#id']);
    return theme('form_element', $element, $element['#children']);
952
953
  }
  else {
954
    return $element['#children'];
955
956
957
958
  }
}

function expand_checkboxes($element) {
959
  $value = is_array($element['#value']) ? $element['#value'] : array();
Steven Wittens's avatar
Steven Wittens committed
960
  $element['#tree'] = TRUE;
961
962
963
  if (count($element['#options']) > 0) {
    if (!isset($element['#default_value']) || $element['#default_value'] == 0) {
      $element['#default_value'] = array();
964
    }
965
    foreach ($element['#options'] as $key => $choice) {
966
      if (!isset($element[$key])) {
967
        $element[$key] = array('#type' => 'checkbox', '#processed' => TRUE, '#title' => $choice, '#return_value' => $key, '#default_value' => isset($value[$key]), '#attributes' => $element['#attributes']);
968
969
970
971
972
973
974
975
976
977
978
      }
    }
  }
  return $element;
}

function theme_submit($element) {
  return theme('button', $element);
}

function theme_button($element) {
979
980
981
982
983
984
985
  //Make sure not to overwrite classes
  if (isset($element['#attributes']['class'])) {
    $element['#attributes']['class'] = 'form-'. $element['#button_type'] .' '. $element['#attributes']['class'];
  }
  else {
    $element['#attributes']['class'] = 'form-'. $element['#button_type'];
  }
986

987
  return '<input type="submit" '. (empty($element['#name']) ? '' : 'name="'. $element['#name'] .'" ') .'value="'. check_plain($element['#value']) .'" '. drupal_attributes($element['#attributes']) ." />\n";
988
989
990
991
992
993
994
}

/**
 * Format a hidden form field.
 *
 * @param $element
 *   An associative array containing the properties of the element.
995
 *   Properties used:  value, edit
996
997
998
999
 * @return
 *   A themed HTML string representing the hidden form field.
 */
function theme_hidden($element) {
1000
  return '<input type="hidden" name="'. $element['#name'] . '" id="'. $element['#id'] . '" value="'. check_plain($element['#value']) ."\" " . drupal_attributes($element['#attributes']) ." />\n";
1001
1002
1003
1004
1005
1006
1007
}

/**
 * Format a textfield.
 *
 * @param $element
 *   An associative array containing the properties of the element.
1008
 *   Properties used:  title, value, description, size, maxlength, required, attributes autocomplete_path
1009
1010
1011
1012
 * @return
 *   A themed HTML string representing the textfield.
 */
function theme_textfield($element) {
1013
  $size = $element['#size'] ? ' size="' . $element['#size'] . '"' : '';
1014
  $class = array('form-text');
1015
  $extra = '';
1016
  if ($element['#autocomplete_path']) {
1017
    drupal_add_js('misc/autocomplete.js');
1018
    $class[] = 'form-autocomplete';
1019
    $extra =  '<input class="autocomplete" type="hidden" id="'. $element['#id'] .'-autocomplete" value="'. check_url(url($element['#autocomplete_path'], NULL, NULL, TRUE)) .'" disabled="disabled" />';
1020
  }
1021
1022
  _form_set_class($element, $class);
  $output = '<input type="text" maxlength="'. $element['#maxlength'] .'" name="'. $element['#name'] .'" id="'. $element['#id'] .'" '. $size .' value="'. check_plain($element['#value']) .'"'. drupal_attributes($element['#attributes']) .' />';
1023
  return theme('form_element', $element, $output). $extra;
1024
1025
1026
1027
1028
1029
1030
}

/**
 * Format a form.
 *
 * @param $element
 *   An associative array containing the properties of the element.
1031
 *   Properties used: action, method, attributes, children
1032
1033
1034
1035
 * @return
 *   A themed HTML string representing the form.
 */
function theme_form($element) {
1036
  // Anonymous div to satisfy XHTML compliance.
1037
  $action = $element['#action'] ? 'action="' . check_url($element['#action']) . '" ' : '';
1038
  return '<form '. $action . ' method="'. $element['#method'] .'" '. 'id="'. $element['#id'] .'"'. drupal_attributes($element['#attributes']) .">\n<div>". $element['#children'] ."\n</div></form>\n";
1039
1040
1041
1042
1043
1044
1045
}

/**
 * Format a textarea.
 *
 * @param $element
 *   An associative array containing the properties of the element.
1046
 *   Properties used: title, value, description, rows, cols, required, attributes
1047
1048
1049
1050
 * @return
 *   A themed HTML string representing the textarea.
 */
function theme_textarea($element) {
1051
  $class = array('form-textarea');
1052
  if ($element['#resizable'] !== FALSE) {
1053
    drupal_add_js('misc/textarea.js');
1054
    $class[] = 'resizable';
1055
1056
  }

1057
  $cols = $element['#cols'] ? ' cols="'. $element['#cols'] .'"' : '';
1058
  _form_set_class($element, $class);
1059
  return theme('form_element', $element, '<textarea'. $cols .' rows="'. $element['#rows'] .'" name="'. $element['#name'] .'" id="'. $element['#id'] .'" '. drupal_attributes($element['#attributes']) .'>'. check_plain($element['#value']) .'</textarea>');
1060
1061
1062
1063
1064
1065
1066
1067
1068
}

/**
 * Format HTML markup for use in forms.
 *
 * This is used in more advanced forms, such as theme selection and filter format.
 *
 * @param $element
 *   An associative array containing the properties of the element.
1069
 *   Properties used: value, children.
1070
1071
1072
1073
1074
 * @return
 *   A themed HTML string representing the HTML markup.
 */

function theme_markup($element) {
1075
  return $element['#value'] . $element['#children'];
1076
1077
1078
1079
1080
1081
1082
}

/**
* Format a password field.
*
* @param $element
*   An associative array containing the properties of the element.
1083
*   Properties used:  title, value, description, size, maxlength, required, attributes
1084
1085
1086
1087
* @return
*   A themed HTML string representing the form.
*/
function theme_password($element) {
1088
  $size = $element['#size'] ? ' size="'. $element['#size'] .'" ' : '';
1089

1090
1091
  _form_set_class($element, array('form-text'));
  $output = '<input type="password" maxlength="'. $element['#maxlength'] .'" name="'. $element['#name'] .'" id="'. $element['#id'] .'" '. $size . drupal_attributes($element['#attributes']) .' />';
1092
  return theme('form_element', $element, $output);
1093
1094
1095
}

/**
1096
 * Expand weight elements into selects.
1097
 */
1098
function process_weight($element) {
1099
  for ($n = (-1 * $element['#delta']); $n <= $element['#delta']; $n++) {
1100
1101
    $weights[$n] = $n;
  }
1102
1103
  $element['#options'] = $weights;
  $element['#type'] = 'select';
1104
1105
  $element['#is_weight'] = TRUE;
  return $element;
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
}

/**
 * Format a file upload field.
 *
 * @param $title
 *   The label for the file upload field.
 * @param $name
 *   The internal name used to refer to the field.
 * @param $size
 *   A measure of the visible size of the field (passed directly to HTML).
 * @param $description
 *   Explanatory text to display after the form item.
 * @param $required
 *   Whether the user must upload a file to the field.
 * @return
 *   A themed HTML string representing the field.
 *
 * For assistance with handling the uploaded file correctly, see the API
 * provided by file.inc.
 */
function theme_file($element) {
1128
  _form_set_class($element, array('form-file'));
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
  return theme('form_element', $element, '<input type="file" name="'. $element['#name'] .'"'. ($element['#attributes'] ? ' '. drupal_attributes($element['#attributes']) : '') .' id="'. form_clean_id($element['#id']) .'" size="'. $element['#size'] ."\" />\n");
}

/**
 * Return a themed form element.
 *
 * @param element
 *   An associative array containing the properties of the element.
 *   Properties used: title, description, id, required
 * @param $value
 *   the form element's data
 * @return
 *   a string representing the form element
 */
function theme_form_element($element, $value) {
  $output  = '<div class="form-item">'."\n";
  $required = !empty($element['#required']) ? '<span class="form-required" title="'. t('This field is required.') .'">*</span>' : '';

  if (!empty($element['#title'])) {
    $title = $element['#title'];
    if (!empty($element['#id'])) {
      $output .= ' <label for="'. form_clean_id($element['#id']) .'">'. t('%title: %required', array('%title' => $title, '%required' => $required)) ."</label>\n";
    }
    else {
      $output .= ' <label>'. t('%title: %required', array('%title' => $title, '%required' => $required)) ."</label>\n";
    }
  }

  $output .= " $value\n";

  if (!empty($element['#description'])) {
    $output .= ' <div class="description">'. $element['#description'] ."</div>\n";
  }

  $output .= "</div>\n";

  return $output;
1166
}
1167

1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
/**
 * Sets a form element's class attribute.
 *
 * Adds 'required' and 'error' classes as needed.
 *
 * @param &$element
 *   The form element
 * @param $name
 *   Array of new class names to be added
 */
function _form_set_class(&$element, $class = array()) {
  if ($element['#required']) {
    $class[] = 'required';
  }
  if (form_get_error($element)){
    $class[] = 'error';
  }
  if (isset($element['#attributes']['class'])) {
    $class[] = $element['#attributes']['class'];
  }
  $element['#attributes']['class'] = implode(' ', $class);
1189
1190
1191
}

/**
1192
 * Remove invalid characters from an HTML ID attribute string.
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
 *
 * @param $id
 *   The ID to clean
 * @return
 *   The cleaned ID
 */
function form_clean_id($id = NULL) {
  $id = str_replace('][', '-', $id);
  return $id;
}

/**
 * @} End of "defgroup form".
 */