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 ...@@ -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 * A "state" means a certain property on a DOM element, such as "visible" or
* The structured array that may contain an array item named states. This * "checked". A state can be applied to an element, depending on the state of
* array describes the different JavaScript states that can be applied to the * another element on the page. In general, states depend on HTML attributes and
* element when certain conditions are met. The #states array is first keyed * DOM element properties, which change due to user interaction.
* by one of the following states: *
* - enabled * Since states are driven by JavaScript only, it is important to understand
* - invisible * that all states are applied on presentation only, none of the states force
* - invalid * any server-side logic, and that they will not be applied for site visitors
* - untouched * without JavaScript support. All modules implementing states have to make
* - optional * sure that the intended logic also works without JavaScript being enabled.
* - filled *
* - unchecked * #states is an associative array in the form of:
* - irrelevant * @code
* - expanded * array(
* - readwrite * STATE1 => CONDITIONS_ARRAY1,
* * STATE2 => CONDITIONS_ARRAY2,
* 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 * @endcode
* conditioning array are the states that are checked on the element (empty, * Each key is the name of a state to apply to the element, such as 'visible'.
* checked, value, collapsed, etc) and the expected value of that condition. * Each value is a list of conditions that denote when the state should be
* * applied.
* @code *
* $form['email_canceled']['settings'] = array( * Multiple different states may be specified to act on complex conditions:
* '#type' => 'container', * @code
* '#states' => array( * array(
* // Hide the settings when the cancel notify checkbox is disabled. * 'visible' => CONDITIONS,
* 'invisible' => array( * 'checked' => OTHER_CONDITIONS,
* 'input[name="email_canceled_toggle"]' => array('checked' => FALSE), * )
* ), * @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) { function drupal_process_states(&$elements) {
$elements['#attached']['js']['misc/states.js'] = array('weight' => JS_LIBRARY + 1); $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