Skip to content

GitLab

Commit a35ca55b authored by Dries's avatar Dries
Browse files

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

parent 6048d282
Hide whitespace changes
Inline Side-by-side
includes/form.inc
View file @ a35ca55b
......@@ -8,11 +8,10 @@
*
* 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. See the
* <a href="http://drupaldocs.org/api/head/file/contributions/docs/developer/topics/forms_api_reference.html">reference</a>
* and the
* <a href="http://drupaldocs.org/api/file/contributions/docs/developer/topics/forms_api.html">quickstart</a>
* guide for more.
* must be explicitly generated by modules. See the reference at
* http://drupaldocs.org/api/head/file/contributions/docs/developer/topics/forms_api_reference.html
* and the quickstart guide at
* http://drupaldocs.org/api/head/file/contributions/docs/developer/topics/forms_api.html
*/
/**
......@@ -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
* will attempt to validate it, using <code>drupal_validate_form</code>,
* and then submit the form using <code>drupal_submit_form</code>.
* will attempt to validate it, using drupal_validate_form(),
* and then submit the form using drupal_submit_form().
*
* @param $form_id
* 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) {
/* Validate the current input */
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.
if ($elements['#required'] && empty($elements['#value']) && $elements['#value'] !== '0') {
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;
/* Use element defaults */
if ((!empty($form['#type'])) && ($info = _element_info($form['#type']))) {
// overlay $info onto $form, retaining preexisting keys in $form
$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']) {
foreach ($form['#process'] as $process => $args) {
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);
}
# 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'])) {
$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
* each of the form elements generating HTML code. This function is usually
* Renders a HTML form given a form tree. Recursively iterates over each of
* the form elements, generating HTML code. This function is usually
* called from within a theme. To render a form from within a module, use
* <code>drupal_get_form()</code>.
* drupal_get_form().
*
* @param $elements
* 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) {
$a_weight = (is_array($a) && isset($a['#weight'])) ? $a['#weight'] : 0;
......@@ -458,7 +458,7 @@ function form_options_flatten($array, $reset = TRUE) {
*
* @param $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
* A themed HTML string representing the form element.
*
......@@ -469,7 +469,7 @@ function form_options_flatten($array, $reset = TRUE) {
function theme_select($element) {
$select = '';
$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.
$value_valid = isset($element['#value']) || array_key_exists('#value', $element);
$value_is_array = is_array($element['#value']);
......@@ -505,7 +505,7 @@ function theme_select($element) {
*
* @param $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
* A themed HTML string representing the form item group.
*/
......@@ -529,7 +529,7 @@ function theme_fieldset($element) {
*
* @param $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
* A themed HTML string representing the form item group.
*/
......@@ -551,7 +551,7 @@ function theme_radio($element) {
*
* @param $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
* A themed HTML string representing the radio button set.
*/
......@@ -601,7 +601,7 @@ function password_confirm_after_build($form, $form_values, &$ref) {
*
* @param $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
* A themed HTML string representing the date selection boxes.
*/
......@@ -677,8 +677,8 @@ function checkboxes_value(&$form) {
}
/**
* Roll out a single radios element
* to a list of radios, using the options array as index.
* Roll out a single radios element to a list of radios,
* using the options array as index.
*/
function expand_radios($element) {
if (count($element['#options']) > 0) {
......@@ -697,7 +697,7 @@ function expand_radios($element) {
*
* @param $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
* A themed HTML string representing the form item.
*/
......@@ -711,7 +711,7 @@ function theme_item($element) {
*
* @param $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
* A themed HTML string representing the checkbox.
*/
......@@ -779,7 +779,7 @@ function theme_button($element) {
*
* @param $element
* An associative array containing the properties of the element.
* Properties used : value, edit
* Properties used: value, edit
* @return
* A themed HTML string representing the hidden form field.
*/
......@@ -792,7 +792,7 @@ function theme_hidden($element) {
*
* @param $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
* A themed HTML string representing the textfield.
*/
......@@ -813,7 +813,7 @@ function theme_textfield($element) {
*
* @param $element
* An associative array containing the properties of the element.
* Properties used : action, method, attributes, children
* Properties used: action, method, attributes, children
* @return
* A themed HTML string representing the form.
*/
......@@ -829,7 +829,7 @@ function theme_form($element) {
*
* @param $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
* A themed HTML string representing the textarea.
*/
......@@ -852,7 +852,7 @@ function theme_textarea($element) {
*
* @param $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
* A themed HTML string representing the HTML markup.
*/
......@@ -868,7 +868,7 @@ function theme_markup($element) {
*
* @param $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
* A themed HTML string representing the form.
*/
......@@ -885,7 +885,7 @@ function theme_password($element) {
*
* @param $element
* An associative array containing the properties of the element.
* Properties used : title, delta, description
* Properties used: title, delta, description
* @return
* 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
* The ID to clean
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment