At one of the recent Drupal Camps (Donetsk, I guess, it was) someone mentioned #states. As I personally had never come across one, only heard of them, I decided to dig into the issue and share my observwtions with you (as this topis will be useful for every Drupal developer, I guess).
So, what kind of feature is it?
# States keeps adding JavaScript that prompts changing the state of one element based on the state of another, after a user action's occurred.
What does it do?
Originally, #states was meant to prompt creating dynamic forms. A simple example: here we have a form with radio buttons "Job Search" and "Employer", while different values are being chosen, the user is displayed various elements of the form for filling.
What exactly can be done using the #states?
To cut a long story short, let's follow the demo-link:
http://drupalexamples.info/
Everything you see here can be done without a single line of JavaScript, only the php, only the Drupal Form API.
Thus, let's consider a basic example:
'# States' => array (
STATE1 => CONDITIONS_ARRAY1,
STATE2 => CONDITIONS_ARRAY2,
...
)
here:
STATE1, STATE2 - a condition that must be applied to the element
CONDITIONS_ARRAY1, CONDITIONS_ARRAY2 - sets of conditions under which a property should be used.
Sets of conditions are specified in an array mode whereby the key being the Jquery selector for any other element on the page (not obligatory restricted to the current form), and the value being a set (as well as a php array) of properties of this element, given the coincidence between the above we need to apply to the initial state of the element STATE1, namely:
‘#states’ => array(
STATE1 => array(
JQUERY_SELECTOR1 => array(
REMOTE_CONDITION1 => REMOTE_VALUE1,
REMOTE_CONDITION2 => REMOTE_VALUE2,
),
JQUERY_SELECTOR2 => array(
REMOTE_CONDITION3 => REMOTE_VALUE3,
REMOTE_CONDITION4 => REMOTE_VALUE4,
),
),
STATE2 => array.......
)