Using Spry Widgets: Validation Checkbox Overview

About Spry Widgets

A Spry widget is a page element containing built-in behaviors and functions that provide a richer user experience by enabling user interaction. These behaviors can include functionality that lets users show or hide content on the page, change the appearance (such as color of the input) in the page, interact with menu items, and much more.

The Spry framework supports a set of re-usable widgets, written in standard HTML, CSS, and JavaScript. You can easily insert these widgets — the code is HTML and JavaScript at its simplest — and then style the widget according to your liking.

Each widget in the Spry framework is associated with unique CSS and JavaScript files. The CSS file contains everything necessary for styling the widget, and the JavaScript file gives the widget its functionality. You must link both of these files to the page on which you want the widget to function and appear styled. Otherwise, the widget won’t have any functionality or styling. For more information, see the appropriate sections about linking associated files in the topics that follow.

The CSS and JavaScript files associated with a given widget are named after the widget, so it’s easy for you to know which files correspond to which widgets. (For example, the files associated with the Validation Checkbox widget are called SpryValidationCheckbox.css and SpryValidationCheckbox.js).

Anatomy of the Validation Checkbox widget

The Validation Checkbox widget is a checkbox form field or a group of checkboxes with validation support for the selection. Users can easily adjust the validation rules they need to enforce. The Validation Checkbox widget can enforce the selection of one checkbox or multiple checkboxes, when a checkbox group is used.

To create a Validation Checkbox widget, you only need a simple checkbox input or a group of checkboxes that can be turned into a Spry Validation Checkbox widget by adding a few elements to it.

The following illustration shows a Validation Checkbox widget as seen in browser:

Validation Checkbox

You can create a widget by simply adding a HTML tag container (e.g. <SPAN>) around the INPUT type="checkbox" tag(s). Checkbox groups require the container tag to have an ID. For a single checkbox, the container is not mandatory, but the checkbox requires an ID attribute.

The Validation Checkbox widget has a set of default states associated. All these states are used to describe the browser behavior when the validation occurs.

A Validation Checkbox widget can be in one of the following states:

When the widget enters one of the above states, a specific CSS class is applied to the HTML tag container. The class definitions for each state are implemented in the SpryValidationCheckbox.css file associated to the widget.

Error messages can be added to a Validation Checkbox widget by simply creating a span tag (or any other tag type) to hold the error message text. By applying a css class on the message, you can hide the error message by default and show it only when the widget container has the specific class applied (when the widget state changes).

The code for the Validation Checkbox widget also includes JavaScript script tags in the head section of the document and after the HTML markup. The script tag in the head of the document includes a JavaScript file where all the functions related to the Validation Checkbox widget are defined. The script tag after the Validation Checkbox widget HTML code contains the constructor of the corresponding Javascript widget object.

Following is the HTML code for a Validation Checkbox widget along with an error message and the associated JavaScript code:

<head>
 ...          
 <!-- Link the JavaScript library to the checkbox widget -->
 <script src="includes/SpryValidationCheckbox.js" type="text/javascript"></script>
 <!-- Link the CSS style sheet to the checkbox widget -->
 <link href="SpryValidationCheckbox.css" rel="stylesheet" type="text/css" />
</head>  
<body>
 <span id="CheckboxWidget">
        <input type="checkbox" name="fieldName_1" value="1">
        <input type="checkbox" name="fieldName_2" value="2">
        <span class="checkboxRequiredMsg">Please make a selection. </span>    
 </span>
 <script type="text/javascript">
        var CheckboxWidgetObject  = new Spry.Widget.ValidationCheckbox("CheckboxWidget");
 </script>
</body>

You may add multiple checkboxes to the same container, in case you need to check the validity for a group of checkboxes.

The constructor in the sample receives one parameter, the ID of the HTML tag container that holds the widget markup.

You’ll also notice that the span tag for the error message has a CSS class applied. The message can be hidden or shown by triggering different CSS rules on the error message container. This is done dynamically by applying different classes on the HTML widget tag container when the widget enters a validation state.

Spry Validation Checkbox widget Structure

In the example above, SPANs are used to create the Validation Checkbox widget structure with its error messages.

Instead of the SPAN tag, any HTML structure can be used, because Spry uses the tag ID to identify the widget container. The appearance of the error message is done using CSS cascading that doesn't look at the actual tag type of the error message.

In the above structure, the widget constructor identifies the HTML element whose ID has been passed as an argument and then looks inside the container for the corresponding checkbox tag (or checkboxes) that needs to have validation applied. Error messages within the container SPAN can be used for validation.

In the below example, if the ID passed in the constructor is the ID of the actual checkbox tag, it uses this element to attach validation triggers to it. However, because in this case there is no widget container tag, the error messages cannot be used and different CSS rules can be triggered to modify up the checkbox appearance in different states.

CSS for the Validation Checkbox widget

The SpryValidationCheckbox.css file contains the rules which trigger the messages display. The rules in the CSS file correspond to the class names specified in the HTML markup for the error messages. However, more complex selectors are required, which take into account the fact that a parent container can have a state class applied to it.

The following is the CSS code for SpryValidationCheckbox.css file:

.checkboxRequiredMsg, .checkboxMinSelectionsMsg, .checkboxMaxSelectionsMsg{
	display: none;
}

.checkboxRequiredState .checkboxRequiredMsg,
.checkboxMinSelectionsState .checkboxMinSelectionsMsg,
.checkboxMaxSelectionsState .checkboxMaxSelectionsMsg {
	display: inline;
	color: #CC3333;
	border: 1px solid #CC3333;
}

Using Validation Checkbox widget

This section contains the following topics:

To insert a Validation Checkbox widget

  1. Locate the SpryValidationCheckbox.js and add it to your web site, if you didn't do it already. You can find the SpryValidationCheckbox.js file in the widgets/ValidationCheckbox folder in the Spry zip.

For example, create a folder called “includes” in the root folder of your web site, and upload the SpryValidationCheckbox.js file to it. The SpryValidationCheckbox.js file contains all of the necessary code for making the Validation Checkbox widget interactive.

  1. Locate the SpryValidationCheckbox.css file and add it to your web site, if you haven't done so already. You might choose to add it to the root folder or to a CSS folder, if you have one. 
  1. In the page code, link the SpryValidationCheckbox.js file to your web page by inserting the following script tag in the page’s head section:
<script src="includes/SpryValidationCheckbox.js" type="text/javascript"></script>

Make sure the file path to the SpryValidationCheckbox.js file is correct. This path will vary depending on where you include the file in your web site.

  1. Link the SpryValidationCheckbox.css file to your web page by inserting the following link tag in the page’s head tag:
<link href="SpryValidationCheckbox.css" rel="stylesheet" type="text/css" />

Make sure the file path to the SpryValidationCheckbox.js file is correct. This path will vary depending on where you put the file in your web site.

  1. Insert the number of Checkbox input fields you need.
<input type="checkbox" name="fieldName_1" value="1" />
<input type="checkbox" name="fieldName_2" value="2" />

  1. Add a container to the Checkbox validation widget by inserting the span tag around the Checkbox input.
<span id="CheckboxWidget">
    <input type="checkbox" name="fieldName_1" value="1" />
    <input type="checkbox" name="fieldName_2" value="2" />
</span>

  1. Initialize the Spry Validation Checkbox object by inserting the following script block in the HTML source code, after the container.
<script type="text/javascript">
var CheckboxWidgetObject = new Spry.Widget.ValidationCheckbox("CheckboxWidget");
</script>     

It’s important that you make sure the ID of the span tag matches the ID parameter you specified in the Spry.Widgets.ValidationCheckbox method. It’s also important that you make sure the JavaScript call comes after the HTML code for the widget.

  1. Save the page. The complete code looks as follows:
<head>
 ...
 <script src="includes/SpryValidationCheckbox.js" type="text/javascript"></script>
 <link href="SpryValidationCheckbox.css" rel="stylesheet" type="text/css" />
...
</head>
<body>
...
<span id="CheckboxWidget">  
      <input type="checkbox" name="fieldName_1" value="1" />
      <input type="checkbox" name="fieldName_2" value="2" />
      <span class="CheckboxRequiredMsg">Please enter a value.</span>    
 </span>
 <script type="text/javascript">
    var CheckboxWidgetObject  = new Spry.Widget.ValidationCheckbox("CheckboxWidget");
 </script>
...
</body>

To style the Validation Checkbox widget

Styling the Validation Checkbox widget means changing the appearance of the error messages for different states.

The Validation Checkbox widget comes with a CSS file (SpryValidationCheckbox.css) that provides default styling for the error messages . You can easily style the error messages to your liking by simply changing the appropriate CSS rules.

To change the appearance of the Validation Checkbox widget:

  1. Open the SpryValidationCheckbox.css file. You can find the SpryValidationCheckbox.css file in the widgets/ValidationCheckbox folder in the package.

  2. Locate the CSS rule for the part of the Checkbox that you want to change. For example, if you want to change the background color of the Validation Checkbox widget’s required state error message, you can edit the .checkboxRequiredState .checkboxRequiredMsg rule in the SpryValidationCheckbox.css file.

  3. Make your changes to the CSS and save the file.

The SpryValidationCheckbox.css file has extensive comments, explaining the selectors and the logic behind certain rules. Check it out for further information on styling.

Validation Checkbox widget Behaviors

The behavior of the Validation Checkbox widget consist of blocking form submission if the selection criteria is not met and therefore changing the CSS classes applied on the widget top container in order to trigger validation messages. For instance, when users try to submit the form with a required checkbox not selected, the form submission is blocked and the checkboxRequiredState class is applied to the widget container.

To change the state appearance of the Checkbox Validation widget:

  1. Open the SpryValidationCheckbox.css file. You can find the SpryValidationCheckbox.css file in the widgets/ValidationCheckbox directory.
  1. The Checkbox Validation widget comes with built-in CSS rules for the states and also for the elements (in this case, the error messages) that can be displayed for these states.

The following classes define the look of the elements associated to the Validation Checkbox widget:

.checkboxRequiredState (Activates when the input checkbox is not selected.)
.checkboxMinSelectionsState (Activates when the number of input checkboxes selected from the group is too small.)
.checkboxMaxSelectionsState (Activates when the number of input checkboxes selected from the group is too large.)

The following classes define the look of the error messages that are added for a state. The names of these classes are not tied to the JavaScript code. You can change them in both CSS and HTML as you wish. We just provide them into the CSS file as default values for faster integration of the Validation Checkbox widget. These classes are:

.checkboxRequiredMsg (Defines the look and feel for required error message in different widget states.)
.checkboxMinSelectionsMsg (Defines the look and feel for the "min selections not met" message in different widget states.)
.checkboxMaxSelectionsMsg (Defines the look and feel for the "max selections exceeded" message in different widget states.)

  1. Add/change CSS rules for any of the behaviors you want.

You cannot rename/replace class names associated with states in the SpryValidationCheckbox.css file only with class names of your own, because the behaviors are hard-coded into the Spry framework. However, you can replace the default class with your desired class name by sending the new value as argument to the checkbox widget constructor. This does not apply for the error messages classes, as mentioned above.
Here is an example on how you can change the required state's CSS class name, without breaking its functionality:

<script>
    var CheckboxWidgetObject = new Spry.Widget.ValidationCheckbox("CheckboxWidget", {requiredClass: "required", minSelectionsClass: "min", maxSelectionsClass: "max", validClass: "valid"});
</script>

Make the Validation Checkbox widget not required

By default, this property is set to true in the Spry framework - that means that the user must select the checkbox in order to submit the form. In order to allow the user to submit an un-selected checkbox, the widget should have 'isRequired: false' as a property of the optional parameters.

<script type="text/javascript">
    var CheckboxWidgetObject = new Spry.Widget.ValidationCheckbox("CheckboxWidget", {isRequired:false});
</script>


Enforce Minimum number of selections

There are cases when you don't want the user to submit less than a minimum number of checkboxes. This can be accomplished by adding the 'minSelections' option in the widget constructor definition. Using this option, you can define a minimum number of checkboxes to be selected before submitting the form. For example, in case of an answer for a survey question, users should check at least a number of options that they consider important. The value for this option should be a positive integer. The CSS class associated with this option is 'checkboxMinSelectionsState'. The code is the following:

<script type="text/javascript">
    var CheckboxWidgetObject = new Spry.Widget.ValidationCheckbox("CheckboxWidget", {minSelections:3});
</script>

Enforce Maximum number of selections

There are cases when don't want the user to submit more than a maximum number of checkboxes. This can be accomplished by adding the 'maxSelections' option in the widget constructor definition. Using this option you can define a maximum number of checkboxes to be selected from the group before submitting the form. The value for this option should be a positive integer. The CSS class associated to this option is 'checkboxMaxSelectionsState'. The code is the following:

<script type="text/javascript">
    var CheckboxWidgetObject = new Spry.Widget.ValidationCheckbox("CheckboxWidget", {maxSelections:10});
</script>

Define what action will trigger the validation process

The 'submit' action always checks the validity of the widget's selections. Besides the validation on submit, you can define other two options for the validation process: validateOn: "blur" and validateOn: "change". The validateOn:"blur" option will trigger the validation process when the Checkbox widget loses its focus. The validateOn: "change" option will trigger the validation process when the user is making the changes for the Checkbox widget. You can add these options as follows:

<script type="text/javascript">
    var CheckboxWidgetObject = new Spry.Widget.ValidationCheckbox("CheckboxWidget", {validateOn:["blur", "change"]});
</script>

 

Combining Attributes

To combine multiple attributes, simple include them within the {}, separated by commas.

<script type="text/javascript">
    var CheckboxWidgetObject = new Spry.Widget.ValidationCheckbox("CheckboxWidget", {minSelections:3, maxSelections: 5,validateOn:["blur", "change"]});
</script>




Copyright © 2006. Adobe Systems Incorporated. All rights reserved.