API

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).

.relevance( 'relevant', true )

indicates an element should be made relevant (shown). No change for relevant elements, irrelevant elements will trigger a relevant event.

.relevance( 'relevant', false )

indicates an element should be made irrelevant (hidden). No change for irrelevant elements, relevant elements will trigger an irrelevant event.

.relevance( 'show' )

1. enables descendent form elements and self
2. removes @hidden attribute
3. removes aria-hidden
4. shows the element (uses a slideDown transition)
5. fires event relevant-done

.relevance( 'hide' )

1. hides element (no animation, hiding is immediate)
2. disables descendent form fields and self (if a form field)
3. adds @hidden attribute
4. adds aria-hidden
5. fires event irrelevant-done

.relevance( 'relevantWhen', config )

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

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:

1. do you like ice cream?
2. what is your favourite flavour? (only relevant if ‘yes’ is selected)
3. 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.

.relevance( 'instructions', [ options ] )

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:

1. If you chose 'value' above (example: If you chose ‘vanilla’ above)
2. 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'
}

Default markup patterns

<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.