Commit 92e36b3c authored by xjm's avatar xjm

Issue #2486983 by metzlerd, jhodgdon, tim.plunkett: Document Text Input Form Elements

parent eafa3a2a
......@@ -14,6 +14,18 @@
/**
* Provides a form element for choosing a color.
*
* Properties:
* - #default_value: Default value, in a format like #ffffff.
*
* Example usage:
* @code
* $form['color'] = array(
* '#type' => 'color',
* '#title' => 'Color',
* '#default_value' => '#ffffff',
* );
* @endcode
*
* @FormElement("color")
*/
class Color extends FormElement {
......
......@@ -13,10 +13,17 @@
/**
* Provides a form element for date selection.
*
* The #default_value will be today's date if no value is supplied. The format
* for the #default_value and the #return_value is an array with three elements
* with the keys: 'year', month', and 'day'. For example,
* array('year' => 2007, 'month' => 2, 'day' => 15)
* Properties:
* - #default_value: An array with the keys: 'year', 'month', and 'day'.
* Defaults to the current date if no value is supplied.
*
* @code
* $form['expiration'] = array(
* '#type' => 'date',
* '#title' => t('Content expiration'),
* '#default_value' => array('year' => 2020, 'month' => 2, 'day' => 15,)
* );
* @endcode
*
* @FormElement("date")
*/
......
......@@ -13,6 +13,19 @@
/**
* Provides a form input element for entering an email address.
*
* Properties:
* - #default_value: An RFC-compliant email address.
*
* Example usage:
* @code
* $form['email'] = array(
* '#type' => 'email',
* '#title' => t('Email'),
* );
* @end
*
* @see \Drupal\Core\Render\Element\Render\Textfield
*
* @FormElement("email")
*/
class Email extends FormElement {
......
......@@ -13,6 +13,13 @@
/**
* Provides a form element for uploading a file.
*
* If you add this element to a form the enctype="multipart/form-data" attribute
* will automatically be added to the form element.
*
* Properties:
* - #multiple: A Boolean indicating whether multiple files may be uploaded.
* - #size: The size of the file input element in characters.
*
* @FormElement("file")
*/
class File extends FormElement {
......
......@@ -15,9 +15,58 @@
* Provides a machine name render element.
*
* Provides a form element to enter a machine name, which is validated to ensure
* that the name is unique and does not contain disallowed characters. All
* disallowed characters are replaced with a replacement character via
* JavaScript.
* that the name is unique and does not contain disallowed characters.
*
* The element may be automatically populated via JavaScript when used in
* conjunction with a separate "source" form element (typically specifying the
* human-readable name). As the user types text into the source element, the
* JavaScript converts all values to lower case, replaces any remaining
* disallowed characters with a replacement, and populates the associated
* machine name form element.
*
* Properties:
* - #machine_name: An associative array containing:
* - exists: A callable to invoke for checking whether a submitted machine
* name value already exists. The submitted value is passed as an argument.
* In most cases, an existing API or menu argument loader function can be
* re-used. The callback is only invoked if the submitted value differs from
* the element's #default_value.
* - source: (optional) The #array_parents of the form element containing the
* human-readable name (i.e., as contained in the $form structure) to use as
* source for the machine name. Defaults to array('label').
* - label: (optional) Text to display as label for the machine name value
* after the human-readable name form element. Defaults to t('Machine name').
* - replace_pattern: (optional) A regular expression (without delimiters)
* matching disallowed characters in the machine name. Defaults to
* '[^a-z0-9_]+'.
* - replace: (optional) A character to replace disallowed characters in the
* machine name via JavaScript. Defaults to '_' (underscore). When using a
* different character, 'replace_pattern' needs to be set accordingly.
* - error: (optional) A custom form error message string to show, if the
* machine name contains disallowed characters.
* - standalone: (optional) Whether the live preview should stay in its own
* form element rather than in the suffix of the source element. Defaults
* to FALSE.
* - #maxlength: (optional) Maximum allowed length of the machine name. Defaults
* to 64.
* - #disabled: (optional) Should be set to TRUE if an existing machine name
* must not be changed after initial creation.
*
* Usage example:
* @code
* $form['id'] = array(
* '#type' => 'machine_name',
* '#default_value' => $this->entity->id(),
* '#disabled' => !$this->entity->isNew(),
* '#maxlength' => 64,
* '#description' => $this->t('A unique name for this item. It must only contain lowercase letters, numbers, and underscores.'),
* '#machine_name' => array(
* 'exists' => array($this, 'exists'),
* ),
* );
* @endcode
*
* @see \Drupal\Core\Render\Element\Textfield
*
* @FormElement("machine_name")
*/
......@@ -62,35 +111,7 @@ public static function valueCallback(&$element, $input, FormStateInterface $form
* Processes a machine-readable name form element.
*
* @param array $element
* The form element to process. Properties used:
* - #machine_name: An associative array containing:
* - exists: A callable to invoke for checking whether a submitted machine
* name value already exists. The submitted value is passed as an
* argument. In most cases, an existing API or menu argument loader
* function can be re-used. The callback is only invoked if the
* submitted value differs from the element's #default_value.
* - source: (optional) The #array_parents of the form element containing
* the human-readable name (i.e., as contained in the $form structure)
* to use as source for the machine name. Defaults to array('label').
* - label: (optional) Text to display as label for the machine name value
* after the human-readable name form element. Defaults to "Machine
* name".
* - replace_pattern: (optional) A regular expression (without delimiters)
* matching disallowed characters in the machine name. Defaults to
* '[^a-z0-9_]+'.
* - replace: (optional) A character to replace disallowed characters in
* the machine name via JavaScript. Defaults to '_' (underscore). When
* using a different character, 'replace_pattern' needs to be set
* accordingly.
* - error: (optional) A custom form error message string to show, if the
* machine name contains disallowed characters.
* - standalone: (optional) Whether the live preview should stay in its
* own form element rather than in the suffix of the source
* element. Defaults to FALSE.
* - #maxlength: (optional) Maximum allowed length of the machine name.
* Defaults to 64.
* - #disabled: (optional) Should be set to TRUE if an existing machine
* name must not be changed after initial creation.
* The form element to process. See main class documentation for properties.
* @param \Drupal\Core\Form\FormStateInterface $form_state
* The current state of the form.
* @param array $complete_form
......
......@@ -14,6 +14,25 @@
/**
* Provides a form element for numeric input, with special numeric validation.
*
* Properties:
* - #default_value: A valid floating point number.
* - #min: Minimum value.
* - #max: Maximum value.
* - #step: Ensures that the number is an even multiple of step, offset by #min
* if specified. A #min of 1 and a #step of 2 would allow values of 1, 3, 5,
* etc.
*
* Usage example:
* @code
* $form['quantity'] = array(
* '#type' => 'number',
* '#title' => t('Quantity'),
* );
* @endcode
*
* @see \Drupal\Core\Render\Element\Range
* @see \Drupal\Core\Render\Element\Textfield
*
* @FormElement("number")
*/
class Number extends FormElement {
......
......@@ -12,6 +12,18 @@
/**
* Provides a form element for entering a password, with hidden text.
*
* Usage example:
* @code
* $form['pass'] = array(
* '#type' => 'password',
* '#title => t('Password'),
* '#size' => 25,
* );
* @endcode
*
* @see \Drupal\Core\Render\Element\PasswordConfirm
* @see \Drupal\Core\Render\Element\Textfield
*
* @FormElement("password")
*/
class Password extends FormElement {
......
......@@ -15,6 +15,17 @@
* Formats as a pair of password fields, which do not validate unless the two
* entered passwords match.
*
* Usage example:
* @code
* $form['pass'] = array(
* '#type' => 'password_confirm',
* '#title' => t('Password'),
* '#size' => 25,
* );
* @endcode
*
* @see \Drupal\Core\Render\Element\Password
*
* @FormElement("password_confirm")
*/
class PasswordConfirm extends FormElement {
......
......@@ -11,7 +11,24 @@
use Drupal\Core\Render\Element;
/**
* Provides a form element for input of a number within a specific range.
* Provides a slider for input of a number within a specific range.
*
* Provides an HTML5 input element with type of "range".
*
* Properties:
* - #min: Minimum value (defaults to 0).
* - #max: Maximum value (defaults to 100).
* Refer to \Drupal\Core\Render\Element\Number for additional properties.
*
* Usage example:
* @code
* $form['quantity'] = array(
* '#type' => 'number',
* '#title' => t('Quantity'),
* );
* @endcode
*
* @see \Drupal\Core\Render\Element\Number
*
* @FormElement("range")
*/
......
......@@ -10,11 +10,17 @@
use Drupal\Core\Render\Element;
/**
* Provides a form input element for searching.
* Provides an HTML5 input element with type of "search".
*
* This is commonly used to provide a filter or search box at the top of a
* long listing page, to allow users to find specific items in the list for
* faster input.
* Usage example:
* @code
* $form['search'] = array(
* '#type' => 'search',
* '#title' => t('Search'),
* );
* @endcode
*
* @see \Drupal\Core\Render\Element\Textfield
*
* @FormElement("search")
*/
......
......@@ -12,6 +12,19 @@
/**
* Provides a form element for entering a telephone number.
*
* Provides an HTML5 input element with type of "tel". It provides no special
* validation.
*
* Usage example:
* @code
* $form['phone'] = array(
* '#type' => 'tel',
* '#title' => t('Phone'),
* );
* @endcode
*
* @see \Drupal\Core\Render\Element
*
* @FormElement("tel")
*/
class Tel extends FormElement {
......
......@@ -12,6 +12,23 @@
/**
* Provides a form element for input of multiple-line text.
*
* Properties:
* - #rows: Number of rows in the text box.
* - #cols: Number of columns in the text box.
* - #resizable: Controls whether the text area is resizable. Allowed values
* are "none", "vertical", "horizontal", or "both" (defaults to "vertical").
*
* Usage example:
* @code
* $form['text'] = array(
* '#type' => 'textarea',
* '#title' => t('Text'),
* );
* @endcode
*
* @see \Drupal\Core\Render\Element\Textfield
* @see \Drupal\filter\Element\TextFormat
*
* @FormElement("textarea")
*/
class Textarea extends FormElement {
......
......@@ -13,6 +13,36 @@
/**
* Provides a one-line text field form element.
*
* Properties:
* - #maxlength: Maximum number of characters of input allowed.
* - #size: The size of the input element in characters.
* - #autocomplete_route_name: A route to be used as callback URL by the
* autocomplete JavaScript library.
* - #autocomplete_route_parameters: An array of parameters to be used in
* conjunction with the route name.
*
* Usage example:
* @code
* $form['title'] = array(
* '#type' => 'textfield',
* '#title' => t('Subject'),
* '#default_value' => $node->title,
* '#size' => 60,
* '#maxlength' => 128,
* '#required' => TRUE,
* );
* @endcode
*
* @see \Drupal\Core\Render\Element\Color
* @see \Drupal\Core\Render\Element\Email
* @see \Drupal\Core\Render\Element\MachineName
* @see \Drupal\Core\Render\Element\Number
* @see \Drupal\Core\Render\Element\Password
* @see \Drupal\Core\Render\Element\PasswordConfirm
* @see \Drupal\Core\Render\Element\Range
* @see \Drupal\Core\Render\Element\Tel
* @see \Drupal\Core\Render\Element\Url
*
* @FormElement("textfield")
*/
class Textfield extends FormElement {
......
......@@ -14,6 +14,21 @@
/**
* Provides a form element for input of a URL.
*
* Properties:
* - #default_value: A valid URL string.
*
* Usage example:
* @code
* $form['homepage'] = array(
* '#type' => 'url',
* '#title' => t('Home Page'),
* '#size' => 30,
* ...
* );
* @end_code
*
* @see \Drupal\Core\Render\Element\Textfield
*
* @FormElement("url")
*/
class Url extends FormElement {
......
......@@ -15,6 +15,27 @@
/**
* Provides a text format render element.
*
* Properties:
* - #base_type: The form element #type to use for the 'value' element.
* 'textarea' by default.
* - #format: (optional) The text format ID to preselect. If omitted, the
* default format for the current user will be used.
* - #allowed_formats: (optional) An array of text format IDs that are available
* for this element. If omitted, all text formats that the current user has
* access to will be allowed.
*
* Usage Example:
* @code
* $form['body'] = array(
* '#type' => 'text_format',
* '#title' => 'Body',
* '#format' => 'full_html',
* '#default_value' => '<p>The quick brown fox jumped over the lazy dog.</p>',
* );
* @endcode
*
* @see \Drupal\Core\Render\Element\Textarea
*
* @RenderElement("text_format")
*/
class TextFormat extends RenderElement {
......@@ -54,14 +75,7 @@ public function getInfo() {
* @endcode
*
* @param array $element
* The form element to process. Properties used:
* - #base_type: The form element #type to use for the 'value' element.
* 'textarea' by default.
* - #format: (optional) The text format ID to preselect. If omitted, the
* default format for the current user will be used.
* - #allowed_formats: (optional) An array of text format IDs that are
* available for this element. If omitted, all text formats that the
* current user has access to will be allowed.
* The form element to process. See main class documentation for properties.
* @param \Drupal\Core\Form\FormStateInterface $form_state
* The current state of the form.
* @param array $complete_form
......
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