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 functions 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 Textfield widget is a input form field of type text with validation support for the inserted text. Users can easily adjust the validation rules they need to enforce.
To create a Validation Textfield widget, you only need a simple textfield input. It will turn into a Spry widget by simply adding a few elements to it.
The following illustration shows the Validation Textfield that received focus:
You can create a widget by simply adding a HTML tag container(<SPAN> for instance) around the <input> 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 <input> tag, but error messages cannot be used. Instead, only CSS classes will be used to show the different states.
The Validation Textfield widget has a set of default states associated. All 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 Textfield widget at any moment, depending on the validation results and other events.
A Validation Textfield 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 SpryValidationTextfield.css file associated to the widget.
Error messages can be added to a Validation Textfield widget by simply creating a span tag (or any other tag type) 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 the widget state changes).
The following illustration shows some states for Validation Textfield widget:
You can change the default appearance of the Validation Textfield 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 (if it’s not already present) in the SpryValidationTexfield.css file.
The code for the Validation Textfield widget also includes script tags in the head of the document and after the widget markup. The script tag in the head of the document defines all the JavaScript functions related to the Validation Textfield widget. The script tag after the widget contains the constructor of the corresponding widget object.
Following is the HTML markup for a Validation Textfield 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 the widget when it enters a validation state.
In the example above, SPANs are used to create the Validation Textfield widget structure.
Instead of the SPAN tag you can use almost any container tag you want, because the mechanism uses the tag ID to create the widget. It doesn't care about the actual tag used. The appearance of the error message is done using CSS cascading that doesn't look at the actual tag type of the error message.
The widget constructor identifies the HTML element whose ID has been passed inand then it looks inside the container for the corresponding INPUT tag. If the ID passed to the constructor is the ID of the INPUT tag, it uses this element to attach validation triggers on it. However, because in the case where there is no widget container tag, no error messages can be used. The validation states will only change the look of the INPUT element (usually it changes its background color).
Another example of widget structure:
Notice: Multiple INPUTs do not work inside the same HTML widget container. Each text field should be its own widget.
The SpryValidationTexfield.css file contains the rules which style the Validation Textfield 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 the SpryValidationTextfield.css file:
.textfieldRequiredMsg, .textfieldInvalidFormatMsg, .textfieldMinValueMsg, .textfieldMaxValueMsg, .textfieldMinCharsMsg, .textfieldMaxCharsMsg, .textfieldValidMsg { display: none; } .textfieldRequiredState .textfieldRequiredMsg, .textfieldInvalidFormatState .textfieldInvalidFormatMsg, .textfieldMinValueState .textfieldMinValueMsg, .textfieldMaxValueState .textfieldMaxValueMsg, .textfieldMinCharsState .textfieldMinCharsMsg, .textfieldMaxCharsState .textfieldMaxCharsMsg { display: inline; color: #CC3333; border: 1px solid #CC3333; } .textfieldValidState input, input.textfieldValidState { background-color: #B8F5B1; } input.textfieldRequiredState, .textfieldRequiredState input, input.textfieldInvalidFormatState, .textfieldInvalidFormatState input, input.textfieldMinValueState, .textfieldMinValueState input, input.textfieldMaxValueState, .textfieldMaxValueState input, input.textfieldMinCharsState, .textfieldMinCharsState input, input.textfieldMaxCharsState, .textfieldMaxCharsState input { background-color: #FF9F9F; } .textfieldFocusState input, input.textfieldFocusState { background-color: #FFFFCC; } .textfieldFlashText input, input.textfieldFlashText{ 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 SpryValidationTextfield.js file inside it. The SpryValidationTextfield.js file contains all of the necessary code for making the Validation Textfield widget interactive.
It’s important that you make sure the ID of the span tag matches the ID parameter you specified in the Spry.Widget.ValidationTextfield method. It’s also important that you make sure the JavaScript call comes after the HTML code for the widget.
The Validation Textfield widget comes with a CSS file (SpryValidationTextfield.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 Textfield widget means that you will change the appearance for the textfield widget and for error messages when in a specific state. In the SpryValidationTextfield.css file you will find all the classes you need to change.
To change the appearance of the Validation Textfield widget:
The SpryValidationTextfield.css file has extensive comments, explaining the selectors and the logic behind certain rules. Check it out for further information on styling.
The behaviors of the Validation Textfield widget consist in blocking form submission for invalid values, auto filling fixed regions of a pattern (if one is used) 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 textfieldRequiredState class is applied on the widget container so that the user can receive a visual feedback (the background color for the textfield turns red) and the corresponding error message is also displayed.
If you don't want the CSS feedback behaviors, simply leave the CSS blank.
To change the state appearance of the Textfield Validation widget:
The following classes define the default behavior for the elements associated with the Validation Textfield widget and for the widget itself:
The following classes define the look of the error messages. The names of these classes can be changed. You may 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 textfield widget. These classes are:
You cannot rename/replace class names associated with states in the SpryValidationTextfield.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 textfield widget constructor.
Here is an example on how you can change the required state CSS class name:
The user has a large range of options to set for the Validation Textfield constructor in order to trigger different types of validation for the typed text. These options can be specified as the second and third parameter of the widget constructor. The last parameter (the third) is a javascript array of options that depend on the type of validation selected in the second parameter. The second parameter represents the validation type and it's mandatory if you plan to use the third (you can set "none" if no type validation is required).
Generic constructor for the Validation Textfield:
1. Available validation types to be specified as the second parameter:
2. Available options for the hash parameter (the third one) - some of them can be used only if a certain validation type is selected on the second parameter: (a full table is presented below)
a. Common options:
b. Options that override the build-in CSS class names applied on top-level widget container when the widget enters one of its states (can be used for any validation type):
c. Advanced options
A table with possible values to be set for different options depending on the validation type selected as the second constructor parameter:
Second parameter | Third Parameter | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Type | format | validateOn | isRequired | useCharacterMasking | minChars / maxChars | minValue / maxValue | pattern | ||||
"none" | - | ["blur"] |
true (default) |
- | positive integer value | - | any pattern | ||||
"integer" | - | ["blur"] ["change"] ["blur", "change"] |
true (default) false |
false (default) |
- | integer value | - | ||||
"email' | - | ["blur"] ["change"] ["blur", "change"] |
true (default) false |
- | positive integer value | - | - | ||||
"date" | "mm/dd/yy" (default) |
["blur"] ["change"] ["blur", "change"] |
true (default) false" |
false (default) true |
- | date value in the specified format |
- | ||||
"time" | "HH:mm" (default) |
["blur"] ["change"] ["blur", "change"] |
true (default) false |
false (default) true |
- | time value in the specified format |
- | ||||
"credit_card" | no format -all CCs |
["blur"] ["change"] ["blur", "change"] |
true (default) false |
false (default) true |
- | - | - | ||||
"zip_code" | "zip_us9" (default) |
["blur"] ["change"] ["blur", "change"] |
true (default) false |
false (default) true |
- | - | custom zip code pattern - used when format="zip_custom" |
||||
"phone" | "phone_us" (default) |
["blur"] ["change"] ["blur", "change"] |
true (default) false |
false (default) true |
- | - | custom phone pattern - used when format="phone_custom" |
||||
"social_security_number" | - | ["blur"] ["change"] ["blur", "change"] |
true (default) false |
false (default) true |
- | - | custom ssn pattern | ||||
"currency" | "comma_dot" (default) |
["blur"] ["change"] ["blur", "change"] |
true (default) false |
false (default) true |
- | numeric value two decimals allowed |
- | ||||
"real" | - | ["blur"] ["change"] ["blur", "change"] |
true (default) false |
false (default) true |
- | numeric value with decimals |
- | ||||
"ip" | "ipv4" (default) "ipv6" "ipv6_ipv4" |
["blur"] ["change"] ["blur", "change"] |
true (default) false |
false (default) true |
- | - | - | ||||
"url" | - | ["blur"] ["change"] ["blur", "change"] |
true (default) false |
- | positive integer value | - | - | ||||
"custom" | - | ["blur"] ["change"] ["blur", "change"] |
true (default) false |
false (default) true |
- | - | custom pattern |
All these validation types and formats will be described in detail in the followings section, describing how to combine different options to get a specific validation.
In order to allow the user to submit empty values, the widget should have isRequired:false as a property of the optional parameters hash. By default this property is set to true in the Spry framework.
The submit action will always check the validity of the widget's value. Besides the validation on submit that will always be done, 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 Validation Textfield widget loses focus. The validateOn:"change" option will trigger the validation process when the user is making changes to the Validation Textfield widget. You can add these options as follows:
The Validation Textfield widget input can be set to accept only integer values by simply adding in the second widget parameter the "integer" value. The widget will allow negative and positive values as data input.
If you want to accept only positive values, you should add in the third parameter the option "allowNegative" set on false.
You can specify email validation for your textfield widget by setting the "email" value in the second parameter in the widget constructor. Using this validation, the value entered in the textfield widget will pass as valid when it has the standard email format.
There will be situations when you want to enforce a date validation for the textfield widget. "You should set the second parameter to "date". For this type of validation you can specify the format option. This format is a string indicating a particular appearance for the date. The default value is: "mm/dd/yy", the US date format. The other valid values as format options are: "mm/dd/yyyy", "dd/mm/yyyy", "dd/mm/yy", "yy/mm/dd", "yyyy/mm/dd", "mm-dd-yy", "dd-mm-yy", "yyyy-mm-dd", "mm.dd.yyyy", "dd.mm.yyyy".
Using the Validation Textfield widget you can add a time validation for the data entered. Set the second parameter of the widget constructor to "time". This validation type also accepts a format option in the third parameter. The default value is: "HH:mm", but you have other valid values that you can specify for the time format option: "HH:mm:ss", "hh:mm tt", "hh:mm:ss tt", "hh:mm t", "hh:mm:ss t".
To set a credit card validation to your Validation Textfield widget you should add the "credit_card" value as the second parameter in the widget constructor. This type of validation has several formats. If format is not specified, it validates all types. This means that any of the following credit card types is recognized as valid: Visa, MasterCard, American Express, Discover, Diner's Club. The corresponding values for the format option are: "visa", "mastercard", "amex", "discover", "dinersclub".
You can specify zip code validation by setting the "zip_code" value as the second parameter in the widget constructor. The accepted zip code types for this type of validation are: US-9, US-5, UK, Canada . The corresponding values for the format options are: "zip_us9", "zip_us5", "zip_uk", "zip_canada". The default format has the "zip_us5" value.
An important advantage for the zip code validation type is that you can define your own pattern for the zip code format. To add a pattern for the zip code validation type you should specify the "zip_custom" value for the format option, and the actual pattern option for the pattern option. The accepted pattern characters can be: "0" - digits between 0 and 9, "A";"a" - case sensitive alphabetic characters, "B";"b" - case insensitive alphabetic characters, "X"; "x" - case sensitive alpha-numeric characters, "Y"; "y" - case insensitive alpha-numeric characters and "?" - any character. Using these pattern characters you can define the pattern you want for the zip code.
The "A", "a", "X", "x" special pattern characters are case-sensitive. The matching character will be converted to the case of the character mask.
Any other character is considered an auto-complete sequence which is automatically inserted in the text field at the appropriate times.
To use one of the special characters as part of an auto-complete sequence, you must escape it using a double-backslash sequence. (e.g.: ‘I h\\ave 00 ye\\ars.’ matches ‘I have 31 years.’
escapes the 'a'.)
To use a backslash as an auto-complete character, you should double it and escape it with a double-backslash. (Example: ‘AA\\\\00\\AA’ will match ‘UB\99AW’ and the backslash is auto-completed after U and B are pressed.)
For example, the pattern for the "zip_us9" format is: "00000-0000" and for "zip_us5" format the pattern is: "00000". Below is a code example for a custom zip code:
To add a phone number validation you should set the value for the second parameter to: "phone_number". The default phone number type is the U.S format: (000) 000-0000.
The "A", "a", "X", "x" special pattern characters are case-sensitive. The matching character will be converted to the case of the character mask.
Any other character is considered as an auto-complete sequence which is automatically inserted in the text field at the appropriate times.
To use one of the special characters as part of an auto-complete sequence, you must escape it using a double-backslash sequence. (Example: ‘I h\\ave 00 ye\\ars.’ This will match ‘I have 31 years.’
)
To use a backslash as an auto-complete character, you should double it and escape it with a double-backslash. (Example: ‘AA\\\\00\\AA’ will match ‘UB\99AW’ and the backslash is auto-completed after U and B are pressed.)
In the example below you can see the code for a phone number validation using pattern characters:
To specify the social security number validation for the textfield widget, you should set the value of the second parameter to: "social_security_number". The supported social security number format is: '000-00-0000'. If you want to validate another type of social security number you should add the pattern option inside the third parameter, with the desired value.
The Validation Textfield widget also supports currency validation. To set this validation add the "currency" value in the widget constructor. The default value for the format option is: "comma_dot"'(1,000.00), but you can also specify "dot_comma" (1.000,00) value for the format. In both cases, the separators for the 3-digit groups can be optional and the decimal part is not required.
To specify the real number/scientific notation for the Validation Textfield widget you should set the value for the second parameter to "real". The accepted input should be a real number, in scientific notation (e.g.: 1.231e10)
To specify the IP address validation you should add as the second parameter the "ip" value. This validation has three accepted types: IPv4, IPv6 only, IPv6_and_IPv4. The corresponding values for the format option are: "ipv4", "ipv6", "ipv6_ipv4". The default value for the format option is:"ipv4".
You can set Validation Textfield widget to trigger the URL validation by adding the "url" value as the second widget parameter. Protocols supported for the url: http(s), ftp.
To have a better control for the Validation Textfield widget input, depending on the validation type, you can add the character masking option in the constructor. Using this option the user will be able to insert only characters that match the validation type and fit into the format accepted for that type.
The Character Masking option is not available when you don't have a validation type specified (when the second parameter from constructor is: "none").
When no value for the input is present, the Validation Textfield widget allows you to suggest a desired format for the expected input data. This can be accomplished by using the "hint" option. This option receives a string value that will be displayed in the textfield when empty. The hint will disappear when the textfield widget receives focus. This option doesn't depend on the validation type, you can always specify it. On blur, the hint is restored in the textfield if there is no value.
By using the Min/Max Chars option for the textfield widget you can control the number of characters entered in the textfield. You can enforce a minimum number of characters that should be typed when the submission occurs and also you can specify the maximum number of allowed characters that can be submitted. This option is available for the following validation types: "none" , "integer", "email" and "url".
Note: "minChars" option doesn't have any effect if the textfield widget is not required.
There will be instances when you will want to verify that the data entered in the textfield is inside a specified range through a interval of min and max values. This option makes sense for these validation types: "integer", "date", "time", "currency", "real". For all these validation types you can specify a minimum and maximum value.
Copyright © 2006. Adobe Systems Incorporated. All rights reserved.