A Spry widget is a page element containing built-in behaviors 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 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).
The Validation Textarea widget is a textarea form field with validation support for the inserted text. Users can easily adjust the validation rules they need to enforce.
At a first glance, the Validation Textarea widget has the same appearance as a standard textarea form control, but what differs is the added validation that triggers on the client-side (browser).
To create a Validation Textarea widget, you only need a simple textarea input. Turn it into a Spry widget by adding a few simple elements to it.
The following illustration shows a Validation Textarea widget as seen in browser:
You can create a widget by simply adding a HTML tag container(<SPAN> for instance) around the TEXTAREA tag. The widget is identified by the ID attribute of the container. This container allows the widget to display error messages. If not container is used, the unique ID should be assigned to the TEXTAREA tag, but error messages cannot be used. Instead, only CSS classes will be used to show the different states.
The Validation Textarea widget has a set of default states associated. These states are used to describe the browser behavior when the validation occurs or/and when the widget receives focus. One or more states can be applied to the Validation Select widget at any moment, depending on the validation results and other events.
A Validation Textarea 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 SpryValidationTextarea.css file associated to the widget.
Error messages can be added to a Validation Textarea 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, the widget 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 for Validation Textarea widget:
You can change the default appearance of the Validation Textarea 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 rule in the SpryValidationTextarea.css file.
The code for the Validation Textarea widget also includes script tags in the head of the document and after the textarea HTML markup. The script tag in the head of the document defines all the JavaScript functions related to the Validation Textarea widget. The script tag after the Validation Textarea widget contains the instantiation of the corresponding JavaScript widget object.
Following is the HTML markup for a Validation Textarea widget, along with an error message and the associated JavaScript:
The constructor in the sample requires 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 Textarea widget structure with its error messages.
Instead of the SPAN tag you can use almost any container tag you want, because the widget is identified by the tag ID, not the actual container tag. The appearance of the error message is done using CSS cascading that doesn't look at the actual tag of the error message.
The widget constructor 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 TEXTAREA tag. If the ID passed to the constructor is the ID of a TEXTAREA tag, it uses this element to attach validation triggers on it. However, because in this case there is no widget container tag, no error messages can be used.
Another example of widget structure:
Notice: Multiple input textarea elements do not work inside the same HTML container. Each text area should be its own widget.
The SpryValidationTextarea.css file contains the rules which style the Validation Textarea widget in different states and trigger the display of the error messages. The rules in the cascading style sheet file correspond to the class names applied on the error messages markup. However, more complex selectors are required that take into account the fact that a parent container can have a state class applied on it.
The following is the CSS code for SpryValidationTextarea.css file:
/*Validation Textarea styling classes*/ .textareaRequiredMsg, .textareaMinCharsMsg, .textareaMaxCharsMsg, .textareaValidMsg { display:none; } .textareaRequiredState .textareaRequiredMsg, .textareaMinCharsState .textareaMinCharsMsg, .textareaMaxCharsState .textareaMaxCharsMsg { display: inline; color: #CC3333; border: 1px solid #CC3333; } .textareaValidState textarea, textarea.textareaValidState { background-color:#B8F5B1; } textarea.textareaRequiredState, .textareaRequiredState textarea, textarea.textareaMinCharsState, .textareaMinCharsState textarea, textarea.textareaMaxCharsState, .textareaMaxCharsState textarea { background-color:#FF9F9F; } .textareaFocusState textarea, textarea.textareaFocusState { background-color:#FFFFCC; } .textareaFlashState textarea, textarea.textareaFlashState{ color:red !important; }
This section contains the following topics:
For example, create a folder called “includes” in the root folder of your web site, and upload the SpryValidationTextarea.js file to it. The SpryValidationTextarea.js file contains all of the necessary code for making the Validation Textarea widget interactive.
Make sure the file path to the SpryValidationTextArea .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 SpryValidationTextArea .js file is correct. This path will vary depending on where you include 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.Widget.ValidationTextarea method. It’s also important that you make sure the JavaScript call comes after the HTML code for the widget.
The Validation Textarea widget comes with a CSS file (SpryValidationTextarea.css) that provides default styling for the widget and other widget elements. You can easily style the widget to your liking by simply changing the appropriate CSS style.
The CSS rules for error messages in the SpryValidationTextarea.css style sheet use the same class names as the related elements in the HTML, so it’s easy for you to know which CSS rules correspond to which parts of the Validation Textarea widget.
To change the appearance of the Validation Textarea widget:
The SpryValidationTextarea.css file contains extensive comments, explaining the selectors and the logic behind each rule. Check it out for further information on styling.
The behaviors of the Validation Textarea widget consist in blocking form submission for not allowed values and changing the CSS classes applied on the widget top container in order to trigger validation messages.
For instance, when a user tries to submit an empty value, the form submission is blocked and the textareaRequiredState class is applied on the widget container so that the user can receive a visual feedback (the background color for the textarea turns red) and the corresponding error message is also displayed. Also the Validation Textarea offers you a character counter.
If you don't want the CSS feedback behaviors, simply leave the CSS blank.
To change the state appearance of the Textarea Validation widget:
The following classes define the look for the elements associated to the Validation Textarea widget and for the widget itself:
The following classes define the behavior for the elements that can be added for a state. (In our case these are the error messages specific for some states). The names of these classes are not hard coded in 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 a faster integration of the textarea widget. These classes are:
You cannot rename/replace class names associated with states in the SpryValidationTextarea.css file with class names of your own because the behaviors are hard-coded in the Spry framework. However, you can replace the default class with your desired class name by sending the new value as argument to the textarea widget constructor. This does not apply for the error messages classes, as mentioned above.
Here is an example on how you can change the state CSS class names:
<script>
var TextareaWidgetObject = new Spry.Widget.ValidationTextarea("TextareaWidget", {requiredClass: "required", invalidCharsMaxClass: "max", invalidCharsMinClass: "min", validClass: "valid", textareaFlashClass: "flash"});
</script>
In order to allow the user 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, which means that empty values cannot be submitted.
There will be cases when you don't want the user to insert less than a minimum number of characters. This can be accomplished by adding the minChars option in the widget constructor definition. Using this option you can define a minimum number of characters to be entered into the textarea before submitting the form. The value set should be a positive integer. The CSS class associated with this option is textareaMinCharsState. The code is the following:
There will be cases when you don't want the user to insert more than a maximum number of characters. This can be accomplished by adding the maxChars option in the widget constructor definition. Using this option you can define a maximum number of characters to be entered in the textarea widget before submitting the form. The value set should be a positive integer. The CSS class associated to this option is textareaMaxCharsState. The code is the following:
The Validation Textarea widget allows the maximum number of characters to be enforced. This means that once the user reaches the maximum number of characters, no more characters can be typed in. For this validation rule to work, the maxChars parameter should also be set and have a valid value. The option name is useCharacterMasking. The valid values for this option are true or false which will enable or disable the enforcement behavior. The default value is true. When this limitation is reached, the textareaFlashState CSS class is applied for a fraction of a second.
The submit action will always check the validity of the widget's value. You can define two other options for the validation process: validateOn:"blur" and validateOn:"change". The validateOn:"blur" option will trigger the validation process when the textarea widget loses its focus. The validateOn:"change" option will trigger the validation process when the user is making changes to the text. You can add these options as follows:
When no value for the textarea is present, the Validation Textarea widget allows you to suggest the data you expect to be entered. This can be accomplished by using the hint option. This option receives a string value which will be displayed in the textarea when it is empty. When the textarea widget receives focus or it has a default value, the hint will disappear. This option doesn't depend on the validation type; you can always specify it:
Validation Textarea widget allows you to display the number of typed characters. In order to use this option, you have to locate the widget container and insert an HTML pair of tags with an unique ID after the TEXTAREA tag. The preferred tag is <span>. The content of this tag will be later filled in by the widget. Then you need to add the following two options:
counterType and counterId to the JavaScript constructor.
counterType defines the type of counter that will be used and will have one the following string options: "chars_count" and "chars_remaining".
- "chars_count" will count the number of characters that are typed into the textarea.
-
In case you have a maxChars limitation you may also use the "chars_remaining" value which will display the number of characters remaining until the maxChars limit is reached.
counterId contains the ID of the tag where the counter will be displayed. This parameter is required for the counter.
Bellow is a full example of a Validation Textarea with the counter enabled:
Note that attribute can be combined by listing them within the {}, separated by commas.
Copyright © 2006. Adobe Systems Incorporated. All rights reserved.