How to create conditional form fields with the wForms javascript library

Jump to : setup | how it works | customization

The wForms Switch behavior tackles one of the most common problem in web forms: How to make a form field or section conditional to a previous answer.

Example

Conditional Section Activated by a Checkbox

 

Setup

Retrieve the wForms files and enable the wForms extension by adding the following code to the <head> element of your page:

<script type="text/javascript" src="wforms_core.js"></script>
<script type="text/javascript" src="wforms_switch.js"></script>

 

How it Works

The Switch Behavior uses the "switch" metaphor, as in switching the light on and off. The switch has a "target" (the light). The target has two states, "on" and "off".

In the example above, the switch is the checkbox. The target is the text field. The target's "on" state is visible. The "off" state is hidden.

It's important to note that the switch behavior only responds to click events. It cannot be activated by another mechanism (the value of a free text field for instance).

Classes

switch-switchname
A switch is identified by the class "switch-" followed by a unique name. For example ‘switch-myswitch’. This class is usually placed on the following HTML elements:
  • INPUT type="checkbox"
  • INPUT type="radio"
  • OPTION (inside a SELECT)

    <input type="checkbox" ... class="switch-myswitch"/>

    When used on any other element, like a link or image, the element will automatically get another class to hold the state of the switch. See swtchIsOn and swtchIsOff below.
onstate-switchname
Indicates that the element is the target of the switch switchname and that its current state is "on". This class can be placed on any HTML element, but is most often used on a DIV or FIELDSET that includes one or several fields and their labels.

<div class="onstate-myswitch"> <input type="text" .../> ... </div>

offstate-switchname
Indicates that the element is the target of the switch switchname and that its current state is "off". When you setup your form you only need to set the onstate-* class. wForms will automatically replace the onstate-* class by the offstate-* class when the switch is triggered.

<div class="offstate-myswitch"> <input type="text" .../> ... </div>

swtchIsOn and swtchIsOff
These classes are automatically added to an element with the switch-* class that does not have a built-in mechanism to determine its state (like the checked and selected attributes in radio/checkbox inputs and selects).
You may use CSS to differentiate the on and off states and give a visual feedback to the user

(note that the particular spelling of this class is not a typo)

Required CSS

The visual rendering of the "on" and "off" states is CSS driven. Setting the display property will do the show/hide effect that we need.

<style type="text/css">
.onstate-myswitch { display: block; }
.offstate-myswitch { display: none; }
</style>

If you are using the switch behavior on links, images or anything that is not a checkbox, radio button or a select menu, you may want to style the swtchIsOn and swtchIsOff classes. For instance:

.swtchIsOn { color: red; }
.swtchIsOff { color: black; }

 

The javascript-only CSS stylesheet

The wForms library comes with a built-in stylesheet activation system that allows you to reserve a stylesheet for javascript-enabled browsers only.

The stylesheet name must ends with "wforms-jsonly.css", it must have a title attribute and the rel attribute must be set to "alternate stylesheet".

<link type="text/css" href="wforms-jsonly.css" rel="alternate stylesheet" title="stylesheet activated by javascript" />

The purpose of this stylesheet is to hold css declarations that should not be used if the wForms library cannot run (ie. in a javascript-disabled browser).

The .offstate-* declaration is a good example. If javascript were to be disabled and the .offstate.* css still applied, the section would never be visible and could never be filled out.

In a javascript-disabled configuration, it is usually better to make all conditional sections visible and let the user use his/her own judgement as to which fields are relevant.

So in conclusion, place all .offstate.* rules in the js-only.css stylesheet.

 

Customization

The Switch Behavior allows you to create conditional sections by dynamically changing the visibility of form fields, but all form fields will be submitted regardless of their switch state.

If you do not want to submit fields that are switched off, simply add the validation behavior. As of wForms v2.0 R42, the validation removes switched-off fields before submission.

If you are using the Validation behavior and still want to submit all form fields, simply add the following script to your form.

<script type="text/javascript">
wFORMS.behaviors.validation.submitSwitchedOffFields = false;
</script>

 

wForms is an open-source, unobtrusive javascript library that adds commonly needed behaviors to traditional web forms without the need for any programming skill.