-
Notifications
You must be signed in to change notification settings - Fork 2
Use .relevance( 'relevant', boolean )
to toggle relevance. This will check if elements in the matched set are changing state, and if they are, fire the appropriate event.
In most cases, you will not need to use .relevance( 'show' )
or .relevance( 'hide' )
. There is a default event listener bound to document
that will invoke show and hide based on relevant/irrelevant events. However, you will need to intercept these events if you wish to show/hide a parent or ancestor element. See [forms example](Forms example).
indicates an element should be made relevant (shown). No change for relevant elements, irrelevant elements will trigger a relevant
event.
indicates an element should be made irrelevant (hidden). No change for irrelevant elements, relevant elements will trigger an irrelevant
event.
- enables descendent form elements and self
- removes
@hidden
attribute - removes
aria-hidden
- shows the element (uses a
slideDown
transition) - fires event
relevant-done
- hides element (no animation, hiding is immediate)
- disables descendent form fields and self (if a form field)
- adds
@hidden
attribute - adds
aria-hidden
- fires event
irrelevant-done
Specify a form control and value that will become the toggle for the matched objects.
The matched object and form controls must be in the same <form>
element.
config is an object that specifies the form control and the value(s) required for the object to be relevant.
Config | Description |
---|---|
name |
The @name of the form control |
id |
The @id of the form control |
container |
A jquery selector for an element that contains the form control |
value |
The value that indicates the object is relevant |
values |
An array of values—the element will be relevant if any of these values are selected |
The form control can be identified by @name
, @id
or a jquery selector for the parent.
It must be a ‘choice’ control: radio buttons, checkboxes or select lists, and it must have a name
attribute (even though you don't need to specify it in the method call).
Nested relevance is supported with relevantWhen
. The form control that controls relevance must be relevant itself. For example, if a form has the following 3 questions:
- do you like ice cream?
- what is your favourite flavour? (only relevant if ‘yes’ is selected)
- do you like chocolate toppping? (only relevant if ‘vanilla’ is selected)
If the user says "yes", they will be asked their favourite flavour. If they answer "vanilla", they will be asked if they like chocolate topping. If they then change their answer to the first question to "no", the 2nd question is hidden. Because the 2nd question is no longer relevant, the 3rd question will also be hidden. If they change their mind again and say "yes", question 2 will become relevant again. Web browsers remember the form state, so "vanilla" will still be selected and the 3rd question will become relevant again too.
For forms that follow specific markup patterns and include text instructions describing relevance…
This method will initialise those forms with the relevance behaviour. A shortcut to calling the relevantWhen
method for each item within the form.
Instructions must be in the format:
- If you chose 'value' above (example: If you chose ‘vanilla’ above)
- If different to label (example: If different to home address)
By default, instructions are found within an element with the class .relevance
for a given question. Questions are identified by the selector .questions > li
You can change these selectors using the options
parameter.
Example:
{
instructionSelector : '.relevancy',
questionSelector : '.Choice, .Text, .group'
}
<ol class="questions">
<li>
<label for="foo">
<span class="label">Foo</span>
</label>
<select id="foo" name="foo">
<option selected="selected">Foo</option>
<option>Bar</option>
</select>
</li>
<li>
<label for="bar">
<span class="label">Bar</span>
<small class="relevance">(If you chose ‘Bar’ above)</small>
</label>
<select id="bar" name="bar">
<option>Bar</option>
<option selected="selected">Baz</option>
</select>
</li>
<li>
<label for="baz">
<span class="label">Baz</span>
<small class="relevance">(If you chose ‘Baz’ above)</small>
</label>
<input id="baz" />
</li>
</ol>
Given the above markup, $( 'form' ).relevance( 'instructions' );
is a shortcut for:
$( '#bar' ).closest( '.questions > li' ).relevance( 'relevantWhen', { name: 'foo', value: 'Bar' });
$( '#baz' ).closest( '.questions > li' ).relevance( 'relevantWhen', { name: 'bar', value: 'Baz' });
The value is provided in the instruction and must be enclosed in quotes. The script will look for a question that has that value in the form above the current matched object.
The instructions
method is intended to support a light-weight HTML API for situations where it is easy to control the HTML but difficult to author javascript—for example, supporting writers who are not web developers by trade. There is an added benefit of providing guidance to users filling out the form who may have javascript disabled (you will require appropriate server-side handling of form submissions), and supports printing of forms for offline use.