Drupal
/
drupal
mirror of https://git.drupalcode.org/project/drupal.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

- Patch #45224 by jvandyk: improved PHPdoc comments. Corrected spelling, improved grammar.

4.7.x
Dries Buytaert 2006-01-18 19:04:12 +00:00
parent 6048d282cc
commit a35ca55bbf
1 changed files with 33 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
includes/form.inc
View File

@ -8,11 +8,10 @@
* *
* Drupal uses these functions to achieve consistency in its form presentation, * 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 * while at the same time simplifying code and reducing the amount of HTML that
* must be explicitly generated by modules. See the * must be explicitly generated by modules. See the reference at
* <a href="http://drupaldocs.org/api/head/file/contributions/docs/developer/topics/forms_api_reference.html">reference</a> * http://drupaldocs.org/api/head/file/contributions/docs/developer/topics/forms_api_reference.html
* and the * and the quickstart guide at
* <a href="http://drupaldocs.org/api/file/contributions/docs/developer/topics/forms_api.html">quickstart</a> * http://drupaldocs.org/api/head/file/contributions/docs/developer/topics/forms_api.html
* guide for more.
*/ */
/** /**
@ -38,10 +37,10 @@ function element_children($element) {
} }
/** /**
* Processes a form array, and produces the HTML output of a form. * Processes a form array and produces the HTML output of a form.
* If there is input in the $_POST['edit'] variable, this function * If there is input in the $_POST['edit'] variable, this function
* will attempt to validate it, using <code>drupal_validate_form</code>, * will attempt to validate it, using drupal_validate_form(),
* and then submit the form using <code>drupal_submit_form</code>. * and then submit the form using drupal_submit_form().
* *
* @param $form_id * @param $form_id
* A unique string identifying the form. Allows each form to be themed. * A unique string identifying the form. Allows each form to be themed.
@ -140,7 +139,7 @@ function drupal_submit_form($form_id, $form, $callback = NULL) {
function _form_validate($elements, $form_id = NULL) { function _form_validate($elements, $form_id = NULL) {
/* Validate the current input */ /* Validate the current input */
if (!$elements['#validated'] && ($elements['#input'] || isset($form_id))) { if (!$elements['#validated'] && ($elements['#input'] || isset($form_id))) {
// An empty checkbox returns 0, an empty textfield returns '' so we use empty(). // An empty checkbox returns 0 and an empty textfield returns '' so we use empty().
// Unfortunately, empty('0') returns TRUE so we need a special check for the '0' string. // Unfortunately, empty('0') returns TRUE so we need a special check for the '0' string.
if ($elements['#required'] && empty($elements['#value']) && $elements['#value'] !== '0') { if ($elements['#required'] && empty($elements['#value']) && $elements['#value'] !== '0') {
form_error($elements, t('%name field is required.', array('%name' => $elements['#title']))); form_error($elements, t('%name field is required.', array('%name' => $elements['#title'])));
@ -249,6 +248,7 @@ function _form_builder($form_id, $form) {
global $form_submitted; global $form_submitted;
/* Use element defaults */ /* Use element defaults */
if ((!empty($form['#type'])) && ($info = _element_info($form['#type']))) { if ((!empty($form['#type'])) && ($info = _element_info($form['#type']))) {
// overlay $info onto $form, retaining preexisting keys in $form
$form += $info; $form += $info;
} }
@ -293,7 +293,7 @@ function _form_builder($form_id, $form) {
} }
} }
// Allow for elements to expand to multiple elements. Radios, checkboxes and files for instance. // Allow for elements to expand to multiple elements, e.g. radios, checkboxes and files.
if (isset($form['#process']) && !$form['#processed']) { if (isset($form['#process']) && !$form['#processed']) {
foreach ($form['#process'] as $process => $args) { foreach ($form['#process'] as $process => $args) {
if (function_exists($process)) { if (function_exists($process)) {
@ -325,7 +325,7 @@ function _form_builder($form_id, $form) {
$form[$key]['#parents'] = $form[$key]['#tree'] && $form['#tree'] ? array_merge($form['#parents'], array($key)) : array($key); $form[$key]['#parents'] = $form[$key]['#tree'] && $form['#tree'] ? array_merge($form['#parents'], array($key)) : array($key);
} }
# Assign a decimal placeholder weight, to preserve original array order # Assign a decimal placeholder weight to preserve original array order
if (!isset($form[$key]['#weight'])) { if (!isset($form[$key]['#weight'])) {
$form[$key]['#weight'] = $count/1000; $form[$key]['#weight'] = $count/1000;
} }
@ -343,10 +343,10 @@ function _form_builder($form_id, $form) {
} }
/** /**
* Renders a HTML form given an form tree. Recursively iterates over each of * Renders a HTML form given a form tree. Recursively iterates over each of
* each of the form elements generating HTML code. This function is usually * the form elements, generating HTML code. This function is usually
* called from within a theme. To render a form from within a module, use * called from within a theme. To render a form from within a module, use
* <code>drupal_get_form()</code>. * drupal_get_form().
* *
* @param $elements * @param $elements
* The form tree describing the form. * The form tree describing the form.
@ -392,7 +392,7 @@ function form_render(&$elements) {
} }
/** /**
* Function used by uasort in form render to sort form via weight. * Function used by uasort in form_render() to sort form by weight.
*/ */
function _form_sort($a, $b) { function _form_sort($a, $b) {
$a_weight = (is_array($a) && isset($a['#weight'])) ? $a['#weight'] : 0; $a_weight = (is_array($a) && isset($a['#weight'])) ? $a['#weight'] : 0;
@ -458,7 +458,7 @@ function form_options_flatten($array, $reset = TRUE) {
* *
* @param $element * @param $element
* An associative array containing the properties of the element. * An associative array containing the properties of the element.
* Properties used : title, value, options, description, extra, multiple, required * Properties used: title, value, options, description, extra, multiple, required
* @return * @return
* A themed HTML string representing the form element. * A themed HTML string representing the form element.
* *
@ -469,7 +469,7 @@ function form_options_flatten($array, $reset = TRUE) {
function theme_select($element) { function theme_select($element) {
$select = ''; $select = '';
$size = $element['#size'] ? ' size="' . $element['#size'] . '"' : ''; $size = $element['#size'] ? ' size="' . $element['#size'] . '"' : '';
// array_key_exists accomodates the rare event where $element['#value'] is NULL. // array_key_exists() accomodates the rare event where $element['#value'] is NULL.
// isset() fails in this situation. // isset() fails in this situation.
$value_valid = isset($element['#value']) || array_key_exists('#value', $element); $value_valid = isset($element['#value']) || array_key_exists('#value', $element);
$value_is_array = is_array($element['#value']); $value_is_array = is_array($element['#value']);
@ -505,7 +505,7 @@ function theme_select($element) {
* *
* @param $element * @param $element
* An associative array containing the properties of the element. * An associative array containing the properties of the element.
* Properties used : attributes, title, description, children, collapsible, collapsed * Properties used: attributes, title, description, children, collapsible, collapsed
* @return * @return
* A themed HTML string representing the form item group. * A themed HTML string representing the form item group.
*/ */
@ -529,7 +529,7 @@ function theme_fieldset($element) {
* *
* @param $element * @param $element
* An associative array containing the properties of the element. * An associative array containing the properties of the element.
* Properties used : required, return_value, value, attributes, title, description * Properties used: required, return_value, value, attributes, title, description
* @return * @return
* A themed HTML string representing the form item group. * A themed HTML string representing the form item group.
*/ */
@ -551,7 +551,7 @@ function theme_radio($element) {
* *
* @param $element * @param $element
* An associative array containing the properties of the element. * An associative array containing the properties of the element.
* Properties used : title, value, options, description, required and attributes. * Properties used: title, value, options, description, required and attributes.
* @return * @return
* A themed HTML string representing the radio button set. * A themed HTML string representing the radio button set.
*/ */
@ -601,7 +601,7 @@ function password_confirm_after_build($form, $form_values, &$ref) {
* *
* @param $element * @param $element
* An associative array containing the properties of the element. * An associative array containing the properties of the element.
* Properties used : title, value, options, description, required and attributes. * Properties used: title, value, options, description, required and attributes.
* @return * @return
* A themed HTML string representing the date selection boxes. * A themed HTML string representing the date selection boxes.
*/ */
@ -677,8 +677,8 @@ function checkboxes_value(&$form) {
} }
/** /**
* Roll out a single radios element * Roll out a single radios element to a list of radios,
* to a list of radios, using the options array as index. * using the options array as index.
*/ */
function expand_radios($element) { function expand_radios($element) {
if (count($element['#options']) > 0) { if (count($element['#options']) > 0) {
@ -697,7 +697,7 @@ function expand_radios($element) {
* *
* @param $element * @param $element
* An associative array containing the properties of the element. * An associative array containing the properties of the element.
* Properties used : title, value, description, required, error * Properties used: title, value, description, required, error
* @return * @return
* A themed HTML string representing the form item. * A themed HTML string representing the form item.
*/ */
@ -711,7 +711,7 @@ function theme_item($element) {
* *
* @param $element * @param $element
* An associative array containing the properties of the element. * An associative array containing the properties of the element.
* Properties used : title, value, return_value, description, required * Properties used: title, value, return_value, description, required
* @return * @return
* A themed HTML string representing the checkbox. * A themed HTML string representing the checkbox.
*/ */
@ -779,7 +779,7 @@ function theme_button($element) {
* *
* @param $element * @param $element
* An associative array containing the properties of the element. * An associative array containing the properties of the element.
* Properties used : value, edit * Properties used: value, edit
* @return * @return
* A themed HTML string representing the hidden form field. * A themed HTML string representing the hidden form field.
*/ */
@ -792,7 +792,7 @@ function theme_hidden($element) {
* *
* @param $element * @param $element
* An associative array containing the properties of the element. * An associative array containing the properties of the element.
* Properties used : title, value, description, size, maxlength, required, attributes autocomplete_path * Properties used: title, value, description, size, maxlength, required, attributes autocomplete_path
* @return * @return
* A themed HTML string representing the textfield. * A themed HTML string representing the textfield.
*/ */
@ -813,7 +813,7 @@ function theme_textfield($element) {
* *
* @param $element * @param $element
* An associative array containing the properties of the element. * An associative array containing the properties of the element.
* Properties used : action, method, attributes, children * Properties used: action, method, attributes, children
* @return * @return
* A themed HTML string representing the form. * A themed HTML string representing the form.
*/ */
@ -829,7 +829,7 @@ function theme_form($element) {
* *
* @param $element * @param $element
* An associative array containing the properties of the element. * An associative array containing the properties of the element.
* Properties used : title, value, description, rows, cols, required, attributes * Properties used: title, value, description, rows, cols, required, attributes
* @return * @return
* A themed HTML string representing the textarea. * A themed HTML string representing the textarea.
*/ */
@ -852,7 +852,7 @@ function theme_textarea($element) {
* *
* @param $element * @param $element
* An associative array containing the properties of the element. * An associative array containing the properties of the element.
* Properties used : prefix, value, children and suffix. * Properties used: prefix, value, children and suffix.
* @return * @return
* A themed HTML string representing the HTML markup. * A themed HTML string representing the HTML markup.
*/ */
@ -868,7 +868,7 @@ function theme_markup($element) {
* *
* @param $element * @param $element
* An associative array containing the properties of the element. * An associative array containing the properties of the element.
* Properties used : title, value, description, size, maxlength, required, attributes * Properties used: title, value, description, size, maxlength, required, attributes
* @return * @return
* A themed HTML string representing the form. * A themed HTML string representing the form.
*/ */
@ -885,7 +885,7 @@ function theme_password($element) {
* *
* @param $element * @param $element
* An associative array containing the properties of the element. * An associative array containing the properties of the element.
* Properties used : title, delta, description * Properties used: title, delta, description
* @return * @return
* A themed HTML string representing the form. * A themed HTML string representing the form.
*/ */
@ -926,7 +926,7 @@ function _form_get_class($name, $required, $error) {
} }
/** /**
* Remove invalid characters from an HTML ID attribute string * Remove invalid characters from an HTML ID attribute string.
* *
* @param $id * @param $id
* The ID to clean * The ID to clean