Validation Text Field widget overview and structure

A Spry Validation Text Field widget is a text field that displays valid or invalid states when the site visitor enters text. For example, you can add a Validation Text Field widget to a form in which visitors type their e-mail addresses. If they fail to type the @ sign and a period (.) in the e-mail address, the widget displays a message stating that the information the user entered is invalid.

The following example shows a Validation Text Field widget in various states:

A.: Text Field widget, hint activated
B.: Text Field widget, valid state
C.: Text Field widget, invalid state
D.: Text Field widget, required state

The Validation Text Field widget includes a number of states (for example, valid, invalid, required value, and so on). You can alter the properties of these states by editing the corresponding CSS file (SpryValidationTextField.css), depending on the desired validation results. A Validation Text Field widget can validate at various points—for example, when the site visitor clicks outside the widget, when they type, or when they try to submit the form.

Initial state: When the page loads in the browser, or when the user resets the form.
Focus state: When the user places the insertion point in the widget.
Valid state: When the user enters information correctly, and the form can be submitted.
Invalid state: When the user enters text in an invalid format. (For example, 06 for a year instead of 2006).
Required state: When the user fails to enter required text in the text field.
Minimum Number Of Characters state: When the user enters fewer than the minimum number of characters required in the text field.
Maximum Number Of Characters state: When the user enters greater than the maximum number of characters allowed in the text field.
Minimum Value state: When the user enters a value that is less than the value that the text field requires. (Applies to integer, real, and data type validations.)
Maximum Value state: When the user enters a value that is greater than the maximum value that the text field allows. (Applies to integer, real, and data type validations.)
Whenever a Validation Text Field widget enters one of these states through user interaction, the Spry framework logic applies a specific CSS class to the HTML container for the widget at run time. For example, if a user tries to submit a form, but enters no text in a required text field, Spry applies a class to the widget that causes it to display the error message, “A value is required,” and blocks the form submission. The rules that control the style and display states of error messages exist in the SpryValidationTextField.css file that accompanies the widget.

The default HTML code for the Validation Text Field widget, usually inside a form, is made up of a container span tag that surrounds the input tag of the text field. The HTML code for the Validation Text Field widget also includes script tags in the head of the document and after the widget’s HTML code. The script tag in the head of the document defines all of the JavaScript functions related to the Text Field widget. The script tag after the widget code creates a JavaScript object that makes the text field interactive.

Following is the HTML code for a Validation Text Field widget:

<head> 
...  
<!-- Link the Spry Validation Text Field JavaScript library --> 
<script src="SpryAssets/SpryValidationTextField.js" type="text/javascript"></script> 
<!-- Link the CSS style sheet that styles the widget -->
<link href="SpryAssets/SpryValidationTextField.css" rel="stylesheet" type="text/css" /> 
</head>
<body>
	<form id="form1" name="form1" method="post" action="">
		<!-- Create the text field widget and assign a unique id-->
		<span id="sprytextfield1">
			<input type="text" name="mytextfield" id="mytextfield" />
			<!--Display an error message-->
			<span class="textfieldRequiredMsg">A value is required.</span>
		</span>
	</form>
<!-- Initialize the Validation Text Field widget object-->
<script type="text/javascript">
	var tf1 = new Spry.Widget.ValidationTextField("sprytextfield1");
</script>
</body>

In the code, the new JavaScript operator initializes the Text Field widget object, and transforms the span content with the ID of sprytextfield1 from static HTML code into an interactive page element.

The span tag for the error message in the widget has a CSS class applied to it. This class (which is set to display:none; by default), controls the style and visibility of the error message, and exists in the accompanying CSS file SpryValidationTextField.css. When the widget enters different states as a result of user interaction, Spry places different classes on the container for the widget, which in turn affects the error-message class.

To add other error messages to a Validation Text Field widget, create a span tag (or any other type of tag) to hold the text of the error message. Then, by applying a CSS class to it, you can hide or show the message, depending on the widget state.

You can add other error messages to a Validation Text Field widget by creating the corresponding CSS rule in the SpryValidationTextField.css file. For example, to change the background color for a state, edit the corresponding rule or add a new rule (if it’s not already present) in the style sheet.

Variation on tags used for Text Field widget structure

In the preceding example, we used span tags to create the structure for the widget:

Container SPAN
	INPUT type="text"
	Error message SPAN

You can, however, use almost any container tag to create the widget:

Container DIV
	INPUT type="text"
	Error Message P

Spry uses the tag ID (not the tag itself) to create the widget. Spry also displays error messages using CSS code that is indifferent to the actual tag used to contain the error message.

The ID passed into the widget constructor identifies a specific HTML element. The constructor finds this element and searches the identified container for a corresponding input tag. If the ID passed to the constructor is the ID of the input tag (rather than a container tag), the constructor attaches validation triggers directly to the input tag. If no container tag is present, however, the widget cannot display error messages, and different validation states alter only the appearance of the input tag element (for example, its background color).

Note: Multiple INPUT tags do not work inside the same HTML widget container. Each text field should be its own widget.