Commit d4379fbd authored by webchick's avatar webchick

#767738 by rfay, sun: Complete and much more betterer re-write of...

#767738 by rfay, sun: Complete and much more betterer re-write of drupal_process_states() documentation.
parent ed1e9a46
......@@ -3891,41 +3891,129 @@ function drupal_process_attached($elements, $weight = JS_DEFAULT, $dependency_ch
}
/**
* Adds JavaScript to the element to allow it to have different active states.
* Adds JavaScript to change the state of an element based on another element.
*
* @param $elements
* The structured array that may contain an array item named states. This
* array describes the different JavaScript states that can be applied to the
* element when certain conditions are met. The #states array is first keyed
* by one of the following states:
* - enabled
* - invisible
* - invalid
* - untouched
* - optional
* - filled
* - unchecked
* - irrelevant
* - expanded
* - readwrite
*
* Each of these states is an array containing conditions that must be met in
* order for this state to be active. The key to this conditioning array is
* a jQuery selector for the element that is checked. The value of the
* conditioning array are the states that are checked on the element (empty,
* checked, value, collapsed, etc) and the expected value of that condition.
*
* @code
* $form['email_canceled']['settings'] = array(
* '#type' => 'container',
* '#states' => array(
* // Hide the settings when the cancel notify checkbox is disabled.
* 'invisible' => array(
* 'input[name="email_canceled_toggle"]' => array('checked' => FALSE),
* ),
* A "state" means a certain property on a DOM element, such as "visible" or
* "checked". A state can be applied to an element, depending on the state of
* another element on the page. In general, states depend on HTML attributes and
* DOM element properties, which change due to user interaction.
*
* Since states are driven by JavaScript only, it is important to understand
* that all states are applied on presentation only, none of the states force
* any server-side logic, and that they will not be applied for site visitors
* without JavaScript support. All modules implementing states have to make
* sure that the intended logic also works without JavaScript being enabled.
*
* #states is an associative array in the form of:
* @code
* array(
* STATE1 => CONDITIONS_ARRAY1,
* STATE2 => CONDITIONS_ARRAY2,
* ...
* )
* @endcode
* Each key is the name of a state to apply to the element, such as 'visible'.
* Each value is a list of conditions that denote when the state should be
* applied.
*
* Multiple different states may be specified to act on complex conditions:
* @code
* array(
* 'visible' => CONDITIONS,
* 'checked' => OTHER_CONDITIONS,
* )
* @endcode
*
* Every condition is a key/value pair, whose key is a jQuery selector that
* denotes another element on the page, and whose value is an array of
* conditions, which must bet met on that element:
* @code
* array(
* 'visible' => array(
* JQUERY_SELECTOR => REMOTE_CONDITIONS,
* JQUERY_SELECTOR => REMOTE_CONDITIONS,
* ...
* ),
* )
* @endcode
* All conditions must be met for the state to be applied.
*
* Each remote condition is a key/value pair specifying conditions on the other
* element that need to be met to apply the state to the element:
* @code
* array(
* 'visible' => array(
* ':input[name="remote_checkbox"]' => array('checked' => TRUE),
* ),
* )
* @endcode
*
* For example, to show a textfield only when a checkbox is checked:
* @code
* $form['toggle_me'] = array(
* '#type' => 'checkbox',
* '#title' => t('Tick this box to type'),
* );
* $form['settings'] = array(
* '#type' => 'textfield',
* '#states' => array(
* // Only show this field when the 'toggle_me' checkbox is enabled.
* 'visible' => array(
* ':input[name="toggle_me"]' => array('checked' => TRUE),
* ),
* );
* @endcode
* ),
* );
* @endcode
*
* The following states may be applied to an element:
* - enabled
* - disabled
* - visible
* - invisible
* - checked
* - unchecked
* - expanded
* - collapsed
*
* The following states may be used in remote conditions:
* - enabled
* - disabled
* - visible
* - invisible
* - checked
* - unchecked
* - value
*
* The following states exist for both states and remote conditions, but are not
* fully implemented and may not change anything on the element:
* - required
* - optional
* - relevant
* - irrelevant
* - valid
* - invalid
* - touched
* - untouched
* - filled
* - empty
* - readwrite
* - readonly
*
* When referencing select lists and radio buttons in remote conditions, a
* 'value' condition must be used:
* @code
* '#states' => array(
* // Show the settings if 'bar' has been selected for 'foo'.
* 'visible' => array(
* ':input[name="foo"]' => array('value' => 'bar'),
* ),
* ),
* @endcode
*
* @param $elements
* A renderable array element having a #states property as described above.
*
* @see form_example_states_form()
*/
function drupal_process_states(&$elements) {
$elements['#attached']['js']['misc/states.js'] = array('weight' => JS_LIBRARY + 1);
......
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