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 include functionality that allow users to show or hide content on the page, change the widget 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 Collapsible Panel widget are called SpryCollapsiblePanel.css and SpryCollapsiblePanel.js).
A Validation Select widget is a drop down list that provides validation for the selected item. When the validation triggers, if the option selected is not valid, the user receives visual feedback.
You only need a simple select input that can be turned into a spry widget by adding a few simple elements to it.
The following illustration shows a Validation Select widget expanded:
You can create a widget by simply adding a HTML container tag around the input SELECT tag. This container should have a unique ID. If the container is not used, the unique ID should be assigned to the SELECT tag.
The Validation Select widget has a set of default states. These states are used to describe the browser behavior when the validation occurs or/and when the widget receives focus. One or multiple states can be applied to the validation select widget at any moment, depending on the validation results and other events.
A Validation Select widget can be in one of the following states:
When the widget enters one of its states or receives focus, a specific CSS class is applied to the HTML tag container. The class definitions for each state are implemented in the SpryValidationSelect.css file.
Error messages can be added to a select widget by simply creating a span tag (or any other container tag ) to hold the error message text. By applying a css class to it, you can hide the error message by default and show it only when the widget container has a specific class applied (when the widget state changes).
The following illustration shows some states of the Validation Select widget:
You can change the default appearance of the Validation Select widget's states by editing the CSS file. For example, if you want to change the background color for a state, you can edit the corresponding rule or add a new one in the SpryValidationSelect.css file.
The HTML for the Validation Select widget also includes script tags in the head of the document and after the select's HTML markup. The script tag in the head of the document defines all the JavaScript functions related to the Validation Select widget. The script tag after the Validation Select widget contains the constructor of the corresponding JavaScript widget object.
The following is the HTML markup for a Validation Select widget:
In the above code, you can see that the constructor has one parameter: the ID of the HTML tag container holding 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 using this class by triggering different css rules on the error message container. The widget does this 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 Select widget structure.
Instead of the SPAN tag you can use almost any tag you want, because the algorithm that identifies the widget tag container by ID and the error message appearance is implemented using a CSS cascading mechanism.
The widget instantiation identifies the HTML element whose ID has been passed as an argument to the constructor, and then it looks inside the container for the corresponding SELECT tag that needs to have validation applied. If the ID passed to the constructor is the ID of a SELECT tag, it uses this element to attach validation triggers on it. However, because in that case there is no widget container tag, error messages cannot be used, and different css rules will trigger the different states.
Note: Multiple SELECT elements will not work inside the same container. Each SELECT should be its own widget.
The SpryValidationSelect.css file contains the rules that style the Validation Select widget in different states and trigger the messages to display. The names of the rules in the cascading style sheet file correspond to the names of the classes specified in the HTML markup for the error messages. However, more complex selectors are required to take into account the fact that a parent container can have a state class applied on it.
The following is the CSS code for SpryValidationSelect.css file:
.selectRequiredMsg, .selectInvalidMsg { display: none; } .selectRequiredState .selectRequiredMsg, .selectInvalidState .selectInvalidMsg { display: inline; color: #CC3333; border: 1px solid #CC3333; } .selectValidState select, select.selectValidState { background-color: #B8F5B1; } select.selectRequiredState, .selectRequiredState select, select.selectInvalidState, .selectInvalidState select { background-color: #FF9F9F; } .selectFocusState select, select.selectFocusState { background-color: #FFFFCC; }
This section contains the following topics:
For example, create a folder called “includes” in the root folder of your web site, and upload the SpryValidationSelect.js file to it. The SpryValidationSelect.js file contains all necessary code for making the Validation Select widget interactive.
If not already done, locate the SpryValidationSelect.css file and add it to your web site. You might choose to add it to the main directory or to a CSS directory if you have one.
In the page code, link the SpryValidationSelect.js file to your web page by inserting the following script tag in the page’s head tag:
It’s important that you make sure the ID of the span tag matches the ID parameter you specified in the Spry.Widget.ValidationSelect method. It’s also important that you make sure the JavaScript call comes after the HTML code for the widget.
The Validation Select widget comes with a CSS file (SpryValidationSelect.css) that provides default styling for the widget. You can, however, easily style the widget to your liking by simply changing the appropriate CSS.
To style the Validation Select widget means that you will change the default appearance for the select widget states and error messages. In the SpryValidationSelect.css file you will find all the classes that you need to change.
To change the appearance of the Validation Select widget:
The SpryValidationSelect.css file has extensive comments, explaining the code and the logic behind certain rules. Check it out for further information on styling.
The behaviors of the Validation Select widget consist of changing CSS classes when the validation is made, and not allowing the user to submit not-allowed values from the form.
For instance, when a user tries to submit an empty value, the form submission is blocked and the selectRequiredState class is applied on the widget container. The user can see a visual feedback or an error message. These behaviors are always applied to the Validation Select widget. If these behaviors are not wanted, simply leave the CSS blank. The classes have some properties added by default, but you can change them by adding new properties and values to the rules.
To change the behaviors of the Select Validation widget:
You cannot rename/replace class names associated with states in the SpryValidationSelect.css file with class names of your own because the behaviors are hard-coded as part of the Spry framework. You can however, trump the default class with your desired class name by sending the new value as argument to the select widget constructor.
Here is an example how to change the required state CSS class name:
In order to allow users to submit empty values, the widget should have '{isRequired:false}' as a property of the optional parameters. By default this property is set to 'true' in the Spry framework: that means that empty values cannot be submitted. However, using the isRequired property set to 'false', you can change the default behavior of the Validation Select widget.
There will be cases when you will not want to submit some values that are considered by you to be invalid. This can be accomplished by adding the invalidValue option in the widget constructor. Using this option, you can define a value to be invalid and it will not pass the validation process. The CSS class associated to this option is selectInvalidState class. For example, we can specify separators with the value '-1'. The code is the following:
The Validation Select widget will always check the validity of the widget's value on the 'on submit' action. Besides the 'on submit' validation, the user 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 select widget loses focus. The validateOn:"change" option will trigger the validation process when the user changing for the select widget. You can add these options as follows:
To combine attribute, simply list them with the {}, separated by commas.