- Patch #29465: new form API by Adrian et al.

  TODO:
  + The contact.module was broken; a new patch for contact.module is needed.
  + Documentation is needed.
  + The most important modules need to be updated ASAP.

1 files changed, 584 insertions, 0 deletions

diff --git a/includes/legacy.inc b/includes/legacy.inc
new file mode 100644
index 000000000..ad17aeaa5
--- /dev/null
+++ b/includes/legacy.inc
@@ -0,0 +1,584 @@
+<?
+
+/**
+ * An unchecked checkbox is not present in $_POST so we fix it here by
+ * proving a default value of 0.  Also, with form_checkboxes() we expect
+ * an array, but HTML does not send the empty array.  This is also taken
+ * care off.
+ */
+function fix_checkboxes() {
+  if (isset($_POST['form_array'])) {
+    $_POST['edit'] = _fix_checkboxes($_POST['edit'], $_POST['form_array'], array());
+  }
+  if (isset($_POST['form_zero'])) {
+    $_POST['edit'] = _fix_checkboxes($_POST['edit'], $_POST['form_zero'], 0);
+  }
+}
+
+function _fix_checkboxes($array1, $array2, $value) {
+  if (is_array($array2) && count($array2)) {
+    foreach ($array2 as $k => $v) {
+      if (is_array($v) && count($v)) {
+        $array1[$k] = _fix_checkboxes($array1[$k], $v, $value);
+      }
+      else if (!isset($array1[$k])) {
+        $array1[$k] = $value;
+      }
+    }
+  }
+  else {
+    $array1 = $value;
+  }
+  return $array1;
+}
+/**
+ * @defgroup form Form generation (deprecated)
+ * @{
+ * 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
+ * must be explicitly generated by modules.
+ */
+
+/**
+ * Generate a form from a set of form elements.
+ *
+ * @param $form
+ *   An HTML string containing one or more form elements.
+ * @param $method
+ *   The query method to use ("post" or "get").
+ * @param $action
+ *   The URL to send the form contents to, if not the current page.
+ * @param $attributes
+ *   An associative array of attributes to add to the form tag.
+ * @result
+ *   An HTML string with the contents of $form wrapped in a form tag.
+ */
+function form($form, $method = 'post', $action = NULL, $attributes = NULL) {
+  if (!$action) {
+    $action = request_uri();
+  }
+  // Anonymous div to satisfy XHTML compliancy.
+  return '<form action="'. check_url($action) .'" method="'. $method .'"'. drupal_attributes($attributes) .">\n<div>". $form ."\n</div></form>\n";
+}
+/**
+ * Format a general form item.
+ *
+ * @param $title
+ *   The label for the form item.
+ * @param $value
+ *   The contents of the form item.
+ * @param $description
+ *   Explanatory text to display after the form item.
+ * @param $id
+ *   A unique identifier for the form item.
+ * @param $required
+ *   Whether the user must fill in this form element before submitting the form.
+ * @param $error
+ *   An error message to display alongside the form element.
+ * @return
+ *   A themed HTML string representing the form item.
+ */
+function form_item($title, $value, $description = NULL, $id = NULL, $required = FALSE, $error = FALSE) {
+  return theme('form_element', $title, $value, $description, $id, $required, $error);
+}
+
+/**
+ * Format a group of form items.
+ *
+ * @param $legend
+ *   The label for the form item group.
+ * @param $group
+ *   The form items within the group, as an HTML string.
+ * @param $description
+ *   Explanatory text to display after the form item group.
+ * @param $attributes
+ *   An associative array of HTML attributes to add to the fieldset tag.
+ * @return
+ *   A themed HTML string representing the form item group.
+ */
+function form_group($legend, $group, $description = NULL, $attributes = NULL) {
+  return '<fieldset' . drupal_attributes($attributes) .'>' . ($legend ? '<legend>'. $legend .'</legend>' : '') . $group . ($description ? '<div class="description">'. $description .'</div>' : '') . "</fieldset>\n";
+}
+
+/**
+ * Format a group of form items.
+ *
+ * @param $legend
+ *   The label for the form item group.
+ * @param $group
+ *   The form items within the group, as an HTML string.
+ * @param $collapsed
+ *   A boolean value decided whether the group starts collapsed.
+ * @param $description
+ *   Explanatory text to display after the form item group.
+ * @param $attributes
+ *   An associative array of HTML attributes to add to the fieldset tag.
+ * @return
+ *   A themed HTML string representing the form item group.
+ */
+function form_group_collapsible($legend, $group, $collapsed = FALSE, $description = NULL, $attributes = NULL) {
+  drupal_add_js('misc/collapse.js');
+
+  $attributes['class'] .= ' collapsible';
+  if ($collapsed) {
+    $attributes['class'] .= ' collapsed';
+  }
+
+  return '<fieldset' . drupal_attributes($attributes) .'>' . ($legend ? '<legend>'. $legend .'</legend>' : '') . $group . ($description ? '<div class="description">'. $description .'</div>' : '') . "</fieldset>\n";
+}
+
+/**
+ * Format a radio button.
+ *
+ * @param $title
+ *   The label for the radio button.
+ * @param $name
+ *   The internal name used to refer to the button.
+ * @param $value
+ *   The value that the form element takes on when selected.
+ * @param $checked
+ *   Whether the button will be initially selected when the page is rendered.
+ * @param $description
+ *   Explanatory text to display after the form item.
+ * @param $attributes
+ *   An associative array of HTML attributes to add to the button.
+ * @param $required
+ *   Whether the user must select this radio button before submitting the form.
+ * @return
+ *   A themed HTML string representing the radio button.
+ */
+function form_radio($title, $name, $value = 1, $checked = FALSE, $description = NULL, $attributes = NULL, $required = FALSE) {
+  $element = '<input type="radio" class="'. _form_get_class('form-radio', $required, _form_get_error($name)) .'" name="edit['. $name .']" value="'. $value .'"'. ($checked ? ' checked="checked"' : '') . drupal_attributes($attributes) .' />';
+  if (!is_null($title)) {
+    $element = '<label class="option">'. $element .' '. $title .'</label>';
+  }
+  return theme('form_element', NULL, $element, $description, $name, $required, _form_get_error($name));
+}
+
+/**
+ * Format a set of radio buttons.
+ *
+ * @param $title
+ *   The label for the radio buttons as a group.
+ * @param $name
+ *   The internal name used to refer to the buttons.
+ * @param $value
+ *   The currently selected radio button's key.
+ * @param $options
+ *   An associative array of buttons to display. The keys in this array are
+ *   button values, while the values are the labels to display for each button.
+ * @param $description
+ *   Explanatory text to display after the form item.
+ * @param $required
+ *   Whether the user must select a radio button before submitting the form.
+ * @param $attributes
+ *   An associative array of HTML attributes to add to each button.
+ * @return
+ *   A themed HTML string representing the radio button set.
+ */
+function form_radios($title, $name, $value, $options, $description = NULL, $required = FALSE, $attributes = NULL) {
+  if (count($options) > 0) {
+    $choices = '';
+    foreach ($options as $key => $choice) {
+      $choices .= '<label class="option"><input type="radio" class="form-radio" name="edit['. $name .']" value="'. $key .'"'. ($key == $value ? ' checked="checked"' : ''). drupal_attributes($attributes) .' /> '. $choice .'</label><br />';
+    }
+    return theme('form_element', $title, $choices, $description, NULL, $required, _form_get_error($name));
+  }
+}
+
+/**
+ * Format a checkbox.
+ *
+ * @param $title
+ *   The label for the checkbox.
+ * @param $name
+ *   The internal name used to refer to the button.
+ * @param $value
+ *   The value that the form element takes on when selected.
+ * @param $checked
+ *   Whether the button will be initially selected when the page is rendered.
+ * @param $description
+ *   Explanatory text to display after the form item.
+ * @param $attributes
+ *   An associative array of HTML attributes to add to the button.
+ * @param $required
+ *   Whether the user must check this box before submitting the form.
+ * @return
+ *   A themed HTML string representing the checkbox.
+ */
+function form_checkbox($title, $name, $value = 1, $checked = FALSE, $description = NULL, $attributes = NULL, $required = FALSE) {
+  $element = '<input type="checkbox" class="'. _form_get_class('form-checkbox', $required, _form_get_error($name)) .'" name="edit['. $name .']" id="edit-'. form_clean_id($name).'" value="'. $value .'"'. ($checked ? ' checked="checked"' : '') . drupal_attributes($attributes) .' />';
+  if (!is_null($title)) {
+    $element = '<label class="option">'. $element .' '. $title .'</label>';
+  }
+  return form_hidden($name, 1, 'form_zero') . theme('form_element', NULL, $element, $description, $name, $required, _form_get_error($name));
+}
+
+/**
+ * Format a set of checkboxes.
+ *
+ * @param $title
+ *   The label for the checkboxes as a group.
+ * @param $name
+ *   The internal name used to refer to the buttons.
+ * @param $values
+ *   A linear array of keys of the initially checked boxes.
+ * @param $options
+ *   An associative array of buttons to display. The keys in this array are
+ *   button values, while the values are the labels to display for each button.
+ * @param $description
+ *   Explanatory text to display after the form item.
+ * @param $attributes
+ *   An associative array of HTML attributes to add to each button.
+ * @param $required
+ *   Whether the user must check a box before submitting the form.
+ * @return
+ *   A themed HTML string representing the checkbox set.
+ */
+function form_checkboxes($title, $name, $values, $options, $description = NULL, $attributes = NULL, $required = FALSE) {
+  if (count($options) > 0) {
+    if (!isset($values) || $values == 0) {
+      $values = array();
+    }
+    $choices = '';
+    foreach ($options as $key => $choice) {
+      $choices .= '<label class="option"><input type="checkbox" class="form-checkbox" name="edit['. $name .'][]" value="'. $key .'"'. (in_array($key, $values) ? ' checked="checked"' : ''). drupal_attributes($attributes) .' /> '. $choice .'</label><br />';
+    }
+    return form_hidden($name, 1, 'form_array') . theme('form_element', $title, $choices, $description, NULL, $required, _form_get_error($name));
+  }
+}
+
+/**
+ * Format a single-line text field.
+ *
+ * @param $title
+ *   The label for the text field.
+ * @param $name
+ *   The internal name used to refer to the field.
+ * @param $value
+ *   The initial value for the field at page load time.
+ * @param $size
+ *   A measure of the visible size of the field (passed directly to HTML).
+ * @param $maxlength
+ *   The maximum number of characters that may be entered in the field.
+ * @param $description
+ *   Explanatory text to display after the form item.
+ * @param $attributes
+ *   An associative array of HTML attributes to add to the form item.
+ * @param $required
+ *   Whether the user must enter some text in the field.
+ * @return
+ *   A themed HTML string representing the field.
+ */
+function form_textfield($title, $name, $value, $size, $maxlength, $description = NULL, $attributes = NULL, $required = FALSE) {
+  $size = $size ? ' size="'. $size .'"' : '';
+  return theme('form_element', $title, '<input type="text" maxlength="'. $maxlength .'" class="'. _form_get_class('form-text', $required, _form_get_error($name)) .'" name="edit['. $name .']" id="edit-'. form_clean_id($name) .'"'. $size .' value="'. check_plain($value) .'"'. drupal_attributes($attributes) .' />', $description, 'edit-'. $name, $required, _form_get_error($name));
+}
+
+/**
+ * Format a single-line text field that uses Ajax for autocomplete.
+ *
+ * @param $title
+ *   The label for the text field.
+ * @param $name
+ *   The internal name used to refer to the field.
+ * @param $value
+ *   The initial value for the field at page load time.
+ * @param $size
+ *   A measure of the visible size of the field (passed directly to HTML).
+ * @param $maxlength
+ *   The maximum number of characters that may be entered in the field.
+ * @param $callback_path
+ *   A drupal path for the Ajax autocomplete callback.
+ * @param $description
+ *   Explanatory text to display after the form item.
+ * @param $attributes
+ *   An associative array of HTML attributes to add to the form item.
+ * @param $required
+ *   Whether the user must enter some text in the field.
+ * @return
+ *   A themed HTML string representing the field.
+ */
+function form_autocomplete($title, $name, $value, $size, $maxlength, $callback_path, $description = NULL, $attributes = NULL, $required = FALSE) {
+  drupal_add_js('misc/autocomplete.js');
+
+  $size = $size ? ' size="'. $size .'"' : '';
+
+  $output = theme('form_element', $title, '<input type="text" maxlength="'. $maxlength .'" class="'. _form_get_class('form-text form-autocomplete', $required, _form_get_error($name)) .'" name="edit['. $name .']" id="edit-'. form_clean_id($name) .'"'. $size .' value="'. check_plain($value) .'"'. drupal_attributes($attributes) .' />', $description, 'edit-'. $name, $required, _form_get_error($name));
+  $output .= '<input class="autocomplete" type="hidden" id="edit-'. form_clean_id($name) .'-autocomplete" value="'. check_url(url($callback_path, NULL, NULL, TRUE)) .'" disabled="disabled" />';
+
+  return $output;
+}
+
+/**
+ * Format a single-line text field that does not display its contents visibly.
+ *
+ * @param $title
+ *   The label for the text field.
+ * @param $name
+ *   The internal name used to refer to the field.
+ * @param $value
+ *   The initial value for the field at page load time.
+ * @param $size
+ *   A measure of the visible size of the field (passed directly to HTML).
+ * @param $maxlength
+ *   The maximum number of characters that may be entered in the field.
+ * @param $description
+ *   Explanatory text to display after the form item.
+ * @param $attributes
+ *   An associative array of HTML attributes to add to the form item.
+ * @param $required
+ *   Whether the user must enter some text in the field.
+ * @return
+ *   A themed HTML string representing the field.
+ */
+function form_password($title, $name, $value, $size, $maxlength, $description = NULL, $attributes = NULL, $required = FALSE) {
+  $size = $size ? ' size="'. $size .'"' : '';
+  return theme('form_element', $title, '<input type="password" class="'. _form_get_class('form-password', $required, _form_get_error($name)) .'" maxlength="'. $maxlength .'" name="edit['. $name .']" id="edit-'. form_clean_id($name) .'"'. $size .' value="'. check_plain($value) .'"'. drupal_attributes($attributes) .' />', $description, 'edit-'. $name, $required, _form_get_error($name));
+}
+
+/**
+ * Format a multiple-line text field.
+ *
+ * @param $title
+ *   The label for the text field.
+ * @param $name
+ *   The internal name used to refer to the field.
+ * @param $value
+ *   The initial value for the field at page load time.
+ * @param $cols
+ *   The width of the field, in columns of text.
+ * @param $rows
+ *   The height of the field, in rows of text.
+ * @param $description
+ *   Explanatory text to display after the form item.
+ * @param $attributes
+ *   An associative array of HTML attributes to add to the form item.
+ * @param $required
+ *   Whether the user must enter some text in the field.
+ * @return
+ *   A themed HTML string representing the field.
+ */
+function form_textarea($title, $name, $value, $cols, $rows, $description = NULL, $attributes = NULL, $required = FALSE) {
+  $cols = $cols ? ' cols="'. $cols .'"' : '';
+  $pre = '';
+  $post = '';
+
+  // optionally plug in a WYSIWYG editor
+  foreach (module_list() as $module_name) {
+    if (module_hook($module_name, 'textarea')) {
+      $pre  .= module_invoke($module_name, 'textarea', 'pre', $name);
+      $post .= module_invoke($module_name, 'textarea', 'post', $name);
+    }
+  }
+
+  return theme('form_element', $title, $pre .'<textarea'. $cols .' rows="'. $rows .'" name="edit['. $name .']" id="edit-'. form_clean_id($name) .'" class="'. _form_get_class('textarea', $required, _form_get_error($name)) .'"'. drupal_attributes($attributes) .'>'. check_plain($value) .'</textarea>'. $post, $description, 'edit-'. $name, $required, _form_get_error($name));
+}
+
+/**
+ * Format a dropdown menu or scrolling selection box.
+ *
+ * @param $title
+ *   The label for the form element.
+ * @param $name
+ *   The internal name used to refer to the form element.
+ * @param $value
+ *   The key of the currently selected item, or a linear array of keys of all the
+ *   currently selected items if multiple selections are allowed.
+ * @param $options
+ *   An associative array of buttons to display. The keys in this array are
+ *   button values, while the values are the labels to display for each button.
+ * @param $description
+ *   Explanatory text to display after the form item.
+ * @param $extra
+ *   Additional HTML to inject into the select element tag.
+ * @param $multiple
+ *   Whether the user may select more than one item.
+ * @param $required
+ *   Whether the user must select a value before submitting the form.
+ * @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 form_select($title, $name, $value, $options, $description = NULL, $extra = 0, $multiple = FALSE, $required = FALSE) {
+  $select = '';
+  foreach ($options as $key => $choice) {
+    if (is_array($choice)) {
+      $select .= '<optgroup label="'. $key .'">';
+      foreach ($choice as $key => $choice) {
+        $select .= '<option value="'. $key .'"'. (is_array($value) ? (in_array($key, $value) ? ' selected="selected"' : '') : ($value == $key ? ' selected="selected"' : '')) .'>'. check_plain($choice) .'</option>';
+      }
+      $select .= '</optgroup>';
+    }
+    else {
+      $select .= '<option value="'. $key .'"'. (is_array($value) ? (in_array($key, $value) ? ' selected="selected"' : '') : ($value == $key ? ' selected="selected"' : '')) .'>'. check_plain($choice) .'</option>';
+    }
+  }
+  return theme('form_element', $title, '<select name="edit['. $name .']'. ($multiple ? '[]' : '') .'"'. ($multiple ? ' multiple="multiple" ' : '') . ($extra ? ' '. $extra : '') .' id="edit-'. form_clean_id($name) .'">'. $select .'</select>', $description, 'edit-'. $name, $required, _form_get_error($name));
+}
+
+/**
+ * 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 form_file($title, $name, $size, $description = NULL, $required = FALSE) {
+  return theme('form_element', $title, '<input type="file" class="'. _form_get_class('form-file', $required, _form_get_error($name)) .'" name="edit['. $name .']" id="edit-'. form_clean_id($name) .'" size="'. $size ."\" />\n", $description, 'edit-'. $name, $required, _form_get_error($name));
+}
+
+/**
+ * Store data in a hidden form field.
+ *
+ * @param $name
+ *   The internal name used to refer to the field.
+ * @param $value
+ *   The stored data.
+ * @param $edit
+ *   The array name to prefix to the $name.
+ * @param $attributes
+ *   An array of HTML attributes for the input tag.
+ * @return
+ *   A themed HTML string representing the hidden field.
+ *
+ * This function can be useful in retaining information between page requests,
+ * but be sure to validate the data on the receiving page as it is possible for
+ * an attacker to change the value before it is submitted.
+ */
+function form_hidden($name, $value, $edit = 'edit', $attributes = NULL) {
+  return '<input type="hidden" name="'. $edit .'['. $name .']" id="'. form_clean_id($edit .'-'. $name) .'" value="'. check_plain($value) .'"'. drupal_attributes($attributes) ." />\n";
+}
+
+/**
+ * Format an action button.
+ *
+ * @param $value
+ *   Both the label for the button, and the value passed to the target page
+ *   when this button is clicked.
+ * @param $name
+ *   The internal name used to refer to the button.
+ * @param $type
+ *   What type to pass to the HTML input tag.
+ * @param $attributes
+ *   An associative array of HTML attributes to add to the form item.
+ * @return
+ *   A themed HTML string representing the button.
+ */
+function form_button($value, $name = 'op', $type = 'submit', $attributes = NULL) {
+  return '<input type="'. $type .'" class="form-'. $type .'" name="'. $name .'" id="'. form_clean_id($name) .'" value="'. check_plain($value) .'" '. drupal_attributes($attributes) ." />\n";
+}
+
+/**
+ * Format a form submit button.
+ *
+ * @param $value
+ *   Both the label for the button, and the value passed to the target page
+ *   when this button is clicked.
+ * @param $name
+ *   The internal name used to refer to the button.
+ * @param $attributes
+ *   An associative array of HTML attributes to add to the form item.
+ * @return
+ *   A themed HTML string representing the button.
+ */
+function form_submit($value, $name = 'op', $attributes = NULL) {
+  return form_button($value, $name, 'submit', $attributes);
+}
+
+/**
+ * Format a weight selection menu.
+ *
+ * @param $title
+ *   The label for the form element.
+ * @param $name
+ *   The internal name used to refer to the form element.
+ * @param $value
+ *   The selected weight value at page load time.
+ * @param $delta
+ *   The largest in absolute value the weight can be. For example, if set to 10,
+ *   weights could range from -10 to 10 inclusive.
+ * @param $description
+ *   Explanatory text to display after the form item.
+ * @param $extra
+ *   Additional HTML to inject into the select element tag.
+ * @return
+ *   A themed HTML string representing the form element.
+ */
+function form_weight($title = NULL, $name = 'weight', $value = 0, $delta = 10, $description = NULL, $extra = 0) {
+  for ($n = (-1 * $delta); $n <= $delta; $n++) {
+    $weights[$n] = $n;
+  }
+
+  return form_select($title, $name, $value, $weights, $description, $extra);
+}
+
+/**
+ * Set a hidden 'form_token' field to be included in a form, used to validate
+ * that the resulting submission was actually generated by a local form.
+ *
+ * @param $key
+ *   A unique key to identify the form that is currently being displayed.
+ *   This identical key is later used to validate that the resulting submission
+ *   actually originated with this form.
+ * @result
+ *   A themed HTML string representing the hidden token field.
+ */
+function form_token($key) {
+  // this private key should always be kept secret
+  if (!variable_get('drupal_private_key', '')) {
+    variable_set('drupal_private_key', mt_rand());
+  }
+
+  // the verification token is an md5 hash of the form key and our private key
+  return form_hidden('form_token', md5($_SERVER['REMOTE_ADDR'] . $key . variable_get('drupal_private_key', '')));
+}
+
+/**
+ * Verify that the hidden 'form_token' field was actually generated with our
+ * private key.
+ *
+ * @param $edit
+ *  An array containing the form that needs to be validated.
+ * @param $key
+ *  The same key that was used to generate the 'form_token'.
+ * @param $error_message
+ *  An optional error message to display if the form does not validate.
+ * @result
+ *  There is nothing returned from this function, but if the 'form_token' does
+ *  not validate an error is generated, preventing the submission.
+ */
+function form_validate($edit, $key, $error_message = NULL) {
+  if ($error_message == NULL) {
+    // set a generic default error message
+    $error = t('Validation error, please try again.  If this error persists, please contact the site administrator.');
+  }
+
+  if ($edit['form_token'] != md5($_SERVER['REMOTE_ADDR'] . $key . variable_get('drupal_private_key', ''))) {
+    // setting this error will cause the form to fail validation
+    form_set_error('form_token', $error);
+  }
+}
+
+/**
+ * @} End of "defgroup form".
+ */
+
+