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).
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:
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:
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.
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.
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; }
This section contains the following topics:
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.
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.
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.
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.
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:
The SpryValidationCheckbox.css file has extensive comments, explaining the selectors and the logic behind certain rules. Check it out for further information on styling.
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:
The following classes define the look of the elements associated to the Validation Checkbox widget:
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:
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>
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.
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:
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:
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:
To combine multiple attributes, simple include them within the {}, separated by commas.
Copyright © 2006. Adobe Systems Incorporated. All rights reserved.