### Textfield Validation Widget

#### Description

The Spry Textfield Validation Widget is used to validate a textfield. The widget can validate data types, patterns and custom strings.

#### Required Files

> SpryValidationTextfield.js

> SpryValidationTextfield.css

#### Reference File

> SpryValidationTextfield.html

#### Sample Files

> TextfieldValidationSample.html

### Structure

The widget structure is as follows:

       <widget container>
          <input textfield>
          <message container(s)>
       </widget container>

The Textfield Validation Widget supports one text field per widget.

The markup used in this structure can be most any HTML, as long as it follows the rules for nesting.

Using the provided files, the default mark up is:

    <span id="comments">
      <input type="text" name="textfield3" id="textfield3">
    <span class="textfieldRequiredMsg">A value is required.</span>
    </span>

### Constructor

Widget Constructors are small pieces of javascript that activate the markup into the working widget. These scripts must come AFTER the markup on the page, since the markup needs to exist before the constructor fires.

    <script type="text/javascript">
    var username = new Spry.Widget.ValidationTextfield("uname");
    </script>

#### Basic Constructor

A basic constructor specifies the name of the widget and identifies the ID of the main markup container. The name of the widget is used to identify the widget for functions and methods. The text field also takes a required argument specifying the type of data to validate. The acceptable values are listed in the table below.

     <script type="text/javascript">
       var widgetname = new Spry.Widget.ValidationTextfield("id of widget container", "validation type");
    </script>

Validation type | Format
--- | ---
none | No particular format required.
integer | Text field accepts numbers only.
email | Text field accepts e-mail addresses that contain the @ sign and a period (.) that is both preceded and followed by at least one letter.
date | Formats vary.
time | Formats vary.
credit_card | Formats vary.
zip_code | Formats vary.
phone_number | Text field accepts phone numbers formatted for U.S. and Canada (000) 000-0000 as well as custom formats.
social_security_number | Text field accepts social security numbers formatted as 000-00-0000 by default.
currency | Text field accepts currency formatted as 1,000,000.00 or 1.000.000,00.
real | Validates various kinds of numbers and scientific notation: integers (for example, 1); float values (for example, 12.123); and float values in scientific notation (for example, 1.212e+12, 1.221e-12 where e is used as a power of 10).
ip | Validates IPv4, IPv6, or both kinds of IP addresses.
url | Text field accepts URLs formatted as http://xxx.xxx.xxx, https://xxx.xxx.xxx, or ftp://xxx.xxx.xxx.
custom | Lets you specify a custom validation type and format.

#### Constructor Options

Constructor options allow users to specify certain attributes of the widget. Many of the options availble are determined by the validation type set in teh constructor. Check the options for the validation type.

Constructor options follow the ID parameter, wrapped in curly braces {}. Options are name:value pairs, separated by a colon (:).

     <script type="text/javascript">
    var sprytextfield1= new Spry.Widget.ValidationTextField("WidgetContainerID", "ValidationType", {option1:"value1", option2:"value2", ..});
    </script>

Option | Values | Default | Description
--- | --- | --- | ---
hint | string | null | The defined string will show in the textfield when the page loads. It will be removed when the user starts typing within the field.
isRequired | true or false | true | Determines whether any checkboxes need to be checked. Set to 'false' to bypass validation.
maxChars | number | null | Determines the maximum number of characters that can be used with the textfield.
minChars | number | null | Determines the minimum number of characters that can be used with the textfield.
requiredClass | class name | null | Overrides the "textfieldRequiredState" built-in value
invalidFormatClass | class name | null | Overrides the "textfieldInvalidFormatState" built-in value
pattern | string | null | Determines the pattern of the text field. Read here for more info.
validClass | class name | null | Overrides the "textfieldValidState" built-in value
focusClass | class name | null | Overrides the "textfieldFocusState" built-in value
invalidFormatClass | class name | null | Overrides the "textfieldInvalidFormatState" built-in value
invalidRangeMinClass | class name | null | Overrides the "textfieldMinValueState" built-in value
invalidRangeMaxClass | class name | null | Overrides the "textfieldMaxValueState" built-in value
invalidCharsMinClass | class name | null | Overrides the "textfieldMinCharsState" built-in value
invalidCharsMaxClass | class name | null | Overrides the "textfieldMaxCharsState" built-in value
textfieldFlashTextClass | class name | null | Overrides the "textfieldFlashText" built-in value
hintClass | class name | null | Overrides the "textfieldHintState" built-in value
useCharacterMasking | true or false | false | Enforces a pattern on the text field. Read here for more info.
validateOn | "blur", "change" | submit | The widget always validates onSubmit. onBlur and onChange can be added with this option. Both can be applied with an array ['blur', 'change']

     <script type="text/javascript">
       var textfield1 = new Spry.Widget.ValidationTextfield("textfield1",{isRequired:false, minChars:20, maxChars:50, validateOn:['blur','change']});
     </script>

#### Validate an integer

To set the text field to accept only integer values, add "integer" as the value for the second parameter in the constructor, as follows:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "integer");
    </script>

The integer validation type accepts both negative and positive values. To accept only positive values, add the allowNegative option to the third parameter, and set the value to false.

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "integer", {allowNegative:false});
    </script>

The following table shows other common options and values for the third parameter.

Option | Value
--- | ---
format | Not applicable
validateOn | ["blur"]; ["change"]; or both together (["blur", "change"])
isRequired | true (the default); false
useCharacterMasking | false (the default); true
minChars/maxChars | Not applicable
minValue/maxValue | Integer value
pattern | Not applicable

#### Validate an email

To set the text field to accept only standard e-mail formats, add "email" as the value for the second parameter in the constructor, as follows:

    <script type="text/javascript">
    	var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "email");
    </script>

You can also set options for the third parameter by using the following syntax:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "email", {option:value});
    </script>

The following table shows some common options and values for the third parameter.

Option | Value
--- | ---
format | Not applicable
validateOn | ["blur"]; ["change"]; or both together (["blur", "change"])
isRequired | true (the default); false
useCharacterMasking | Not applicable
minChars/maxChars | Positive integer value
minValue/maxValue | Not applicable
pattern | Not applicable

#### Validate a date

To set the text field to accept a date format, add "date" as the value for the second parameter in the constructor, as follows:

    <script type="text/javascript">
    	var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "date");
    </script>

The default date format is "mm/dd/yy" (U.S. date format). You can, however, set a number of other date formats in the third parameter by using the format option, as in the following example:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "date", {format:"yyyy-mm-dd"});
    </script>

The following table shows a full list of formatting options, as well as some other common options and values, for the third parameter.

Option | Value
--- | ---
format | "mm/dd/yy" (default); "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";
validateOn | ["blur"]; ["change"]; or both together (["blur", "change"])
isRequired | true (the default); false
useCharacterMasking | false (the default); true
minChars/maxChars | Not applicable
minValue/maxValue | Date value in the specified format
pattern | Not applicable

#### Validate a time

To set the text field to accept a time format, add "time" as the value for the second parameter in the constructor, as follows:

    <script type="text/javascript">
    	var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "time");
    </script>

The default date format is "HH:mm" (hours and minutes). You can, however, set a number of other time formats in the third parameter by using the format option, as in the following example:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "time", {format:"HH:mm:ss"});
    </script>

The following table shows a full list of formatting options, as well as some other common options and values, for the third parameter.

Option | Value
--- | ---
format | "HH:mm" (the default); "HH:mm:ss"; "hh:mm tt"; "hh:mm:ss tt"; "hh:mm t"; "hh:mm;ss t"; (where "tt" stands for am/pm format, and "t" stands for a/p format.)
validateOn | ["blur"]; ["change"]; or both together (["blur", "change"])
isRequired | true (the default); false
useCharacterMasking | false (the default); true
minChars/maxChars | Not applicable
minValue/maxValue | Time value in the specified format
pattern | Not applicable

#### Validate a credit card

To set the text field to accept a credit card format, add "credit_card" as the value for the second parameter in the constructor, as follows:

    <script type="text/javascript">
    	var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "credit_card");
    </script>

The default is to validate all types of credit cards, but you can specify particular credit card formats to accept in the third parameter by using the format option, as in the following example:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "credit_card", {format:"visa"});
    </script>

The following table shows a full list of formatting options, as well as some other common options and values, for the third parameter.

Option | Value
--- | ---
format | No format (the default); "visa"; "mastercard"; "amex"; "discover"; "dinersclub"
validateOn | ["blur"]; ["change"]; or both together (["blur", "change"])
isRequired | true (the default); false
useCharacterMasking | false (the default); true
minChars/maxChars | Not applicable
minValue/maxValue | Not applicable
pattern | Not applicable

#### Validate a zip code

To set the text field to accept a zip code format, add "zip_code" as the value for the second parameter in the constructor, as follows:

    <script type="text/javascript">
    	var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "zip_code");
    </script>

The default format is the U.S. 5-digit zip code format, but you can specify a number of other formats in the third parameter by using the format option, as in the following example:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "zip_code", {format:"zip_uk"});
    </script>

The following table shows a full list of formatting options, as well as some other common options and values, for the third parameter.

Option | Value
--- | ---
format | "zip_us5" (the default); "zip_us9"; "zip_uk"; "zip_canada"; "zip_custom"
validateOn | ["blur"]; ["change"]; or both together (["blur", "change"])
isRequired | true (the default); false
useCharacterMasking | false (the default); true
minChars/maxChars | Not applicable
minValue/maxValue | Not applicable
pattern | Custom zip code pattern. Used when format="zip_custom"

The "zip_custom" format lets you specify your own customized pattern for zip-code format. After specifying "zip_custom" as your format, add the pattern option to the third parameter to define the format. For example, you might want to validate a zip code that has three numbers, followed by another set of numbers and case-sensitive alphabetic characters. After the format option, add the pattern option in the third parameter of the constructor to specify the custom pattern, as follows:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "zip_code", {format:"zip_custom", pattern:"000 00AA"});
    </script>

The following table shows a full list of values used for custom patterns.

Value | Description
--- | ---
"0" | Whole numbers between 0 and 9
"A" | Uppercase alphabetic characters
"a" | Lowercase alphabetic characters
"B"; "b" | Case-insensitive alphabetic characters
"X" | Uppercase alphanumeric characters
"x" | Lowercase alphanumeric characters
"Y"; "y" | Case-insensitive alphanumeric characters
"?" | Any character

The "A", "a", "X", and "x" custom pattern characters are case sensitive. In situations that use these characters, Spry converts the characters to the correct case, even if the user enters the wrong case.

#### Validate a phone number

To set the text field to accept a phone number format, add "phone_number" as the value for the second parameter in the constructor, as follows:

    <script type="text/javascript">
    	var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "phone_number");
    </script>

The default format is U.S. area code and phone number format: (000) 000-0000, but you can specify a custom format in the third parameter by using the "phone_custom" and "pattern" options, as in the following example:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "zip_code", {format:"phone_custom" , pattern:"00 0000 A"});
    </script>

The following table shows a full list of values used for custom patterns.

Value | Description
--- | ---
"0" | Whole numbers between 0 and 9
"A" | Uppercase alphabetic characters
"a" | Lowercase alphabetic characters
"B"; "b" | Case-insensitive alphabetic characters
"X" | Uppercase alphanumeric characters
"x" | Lowercase alphanumeric characters
"Y"; "y" | Case-insensitive alphanumeric characters
"?" | Any character

The "A", "a", "X", and "x" custom pattern characters are case sensitive. In situations that use these characters, Spry converts the characters to the correct case, even if the user enters the wrong case.

The following table shows some other common options and values for the third parameter.

Option | Value
--- | ---
format | "phone_number" (the default); "phone_custom"
validateOn | ["blur"]; ["change"]; or both together (["blur", "change"])
isRequired | true (the default); false
useCharacterMasking | false (the default); true
minChars/maxChars | Not applicable
minValue/maxValue | Not applicable
pattern | Custom phone pattern. Used when format="phone_custom"

#### Validate a social security number

To set the text field to accept a social security number format, add "social_security_number" as the value for the second parameter in the constructor, as follows:

    <script type="text/javascript">
    	var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "social_security number");
    </script>

The default format is U.S. social security number format with dashes: 000-00-0000, but you can specify a custom format in the third parameter by using the pattern option, as in the following example:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "social_security_number", {format:"custom" pattern:"00 0000 A"});
    </script>

The following table shows a full list of values used for custom patterns.

Value | Description
--- | ---
"0" | Whole numbers between 0 and 9
"A" | Uppercase alphabetic characters
"a" | Lowercase alphabetic characters
"B"; "b" | Case-insensitive alphabetic characters
"X" | Uppercase alphanumeric characters
"x" | Lowercase alphanumeric characters
"Y"; "y" | Case-insensitive alphanumeric characters
"?" | Any character

The "A", "a", "X", and "x" custom pattern characters are case sensitive. In situations that use these characters, Spry converts the characters to the correct case, even if the user enters the wrong case.

The following table shows some other common options for the third parameter.

Option | Value
--- | ---
format | Not applicable
validateOn | ["blur"]; ["change"]; or both together (["blur", "change"])
isRequired | true (the default); false
useCharacterMasking | false (the default); true
minChars/maxChars | Not applicable
minValue/maxValue | Not applicable
pattern | Custom social security pattern

#### Validate currency

To set the text field to accept a currency number format, add "currency" as the value for the second parameter in the constructor, as follows:

    <script type="text/javascript">
    	var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "currency");
    </script>

The default format is U.S. currency format: 1,000.00, but you can also specify the "dot_comma" format (1.000,00) in the third parameter, as follows:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "currency", {format:"dot_comma"});
    </script>

In both cases, the separators for the 3-digit groups can be optional and the decimal part (i.e. the .00 in 1,000.00) is not required.

The following table shows some other common options for the third parameter.

Option | Value
--- | ---
format | "comma_dot" (the default); "dot_comma"
validateOn | ["blur"]; ["change"]; or both together (["blur", "change"])
isRequired | true (the default); false
useCharacterMasking | false (the default); true
minChars/maxChars | Not applicable
minValue/maxValue | Numeric value with two decimal numbers allowed
pattern | Not applicable

#### Validate real numbers and scientific notation

To set the text field to accept real numbers and scientific notation, add "real" as the value for the second parameter in the constructor, as follows:

    <script type="text/javascript">
    	var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "real");
    </script>

The text field validates a real number in scientific notation, for example 1.231e10.

The following table shows some other common options for the third parameter.

Option | Value
--- | ---
format | Not applicable
validateOn | ["blur"]; ["change"]; or both together (["blur", "change"])
isRequired | true (the default); false
useCharacterMasking | false (the default); true
minChars/maxChars | Not applicable
minValue/maxValue | Numeric value with decimal numbers
pattern | Not applicable

#### Validate an IP address

To set the text field to validate an IP address, add "ip" as the value for the second parameter in the constructor, as follows:

    <script type="text/javascript">
    	var sprytextfield1= new Spry.Widget.ValidationTextField("sprytextfield1", "ip");
    </script>

The default accepted IP address format is IPv4, but you can set other IP address formats in the third parameter by using the format option, as in the following example:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "ip", {format:"ipv6"});
    </script>

The following table shows the formatting options, as well as some other common options, for the third parameter.

Option | Value
--- | ---
format | "ipv4" (the default); "ipv6"; "ipv4_ipv6"
validateOn | ["blur"]; ["change"]; or both together (["blur", "change"])
isRequired | true (the default); false
useCharacterMasking | false (the default); true
minChars/maxChars | Not applicable
minValue/maxValue | Not applicable
pattern | Not applicable

#### Validate a URL

To set the text field to accept only URL values, add "url" as the value for the second parameter in the constructor, as follows:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "url");
    </script>

The URL validation type accepts HTTP, HTTPS, and FTP URL values.

The following table shows other common options for the third parameter.

Option | Value
--- | ---
format | Not applicable
validateOn | ["blur"]; ["change"]; or both together (["blur", "change"])
isRequired | true (the default); false
useCharacterMasking | Not applicable
minChars/maxChars | Positive integer value
minValue/maxValue | Not applicable
pattern | Not applicable

#### Validate a custom format

To set the text field to accept any kind of customized format, specify "custom" as the value for the second parameter, and adding the pattern option in the third parameter, as follows:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "custom", {pattern:"00 0000 AX"});
    </script>

The following table shows a full list of values used for custom patterns.

Value | Description
--- | ---
"0" | Whole numbers between 0 and 9
"A" | Uppercase alphabetic characters
"a" | Lowercase alphabetic characters
"B"; "b" | Case-insensitive alphabetic characters
"X" | Uppercase alpha-numeric characters
"x" | Lowercase alpha-numeric characters
"Y"; "y" | Case-insensitive alpha-numeric characters
"?" | Any character

The "A", "a", "X", and "x" custom pattern characters are case sensitive. In situations that use these characters, Spry converts the characters to the correct case, even if the user enters the wrong case.

### Block invalid characters

You can prevent users from entering invalid characters in a Validation Text Field widget. For example, if you set this option for a widget set with the Integer validation type, nothing appears in the text field if the user tries to type a letter.

You must specify a validation type for this option because the specification of the third parameter depends on the second parameter. If no validation type is required, specify "none" as your validation type.

This option does not work in older browsers.

To block invalid characters, add the useCharacterMasking property to the constructor and set its value to true, as follows:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "validation_type", {useCharacterMasking:true});
    </script>

#### Specify custom patterns

The following table shows a full list of values used for custom patterns.

Value | Description
--- | ---
"0" | Whole numbers between 0 and 9
"A" | Uppercase alphabetic characters
"a" | Lowercase alphabetic characters
"B"; "b" | Case-insensitive alphabetic characters
"X" | Uppercase alpha-numeric characters
"x" | Lowercase alpha-numeric characters
"Y"; "y" | Case-insensitive alpha-numeric characters
"?" | Any character

Use these values to create a custom pattern for any of the format types. For example, to specify a custom social security number that’s a combination of numbers and capital letters, specify the following custom pattern in the constructor’s third parameter:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "social_security_number", {format:"custom", pattern:"AA00AA"});
    </script>

The preceding code results in a text field that accepts values such as UT99CW, AB87PP, GV44RE, and so on.

Note: Spry’s validation mechanism supports only ASCII characters.

#### Insert autocomplete characters

The following table shows a full list of values used for custom patterns.

Value | Description
--- | ---
"0" | Whole numbers between 0 and 9
"A" | Uppercase alphabetic characters
"a" | Lowercase alphabetic characters
"B"; "b" | Case-insensitive alphabetic characters
"X" | Uppercase alpha-numeric characters
"x" | Lowercase alpha-numeric characters
"Y"; "y" | Case-insensitive alpha-numeric characters
"?" | Any character

Any characters (letters, punctuation, and so on) other than the backslash (\) and those listed in the preceding table are considered autocomplete characters, and Spry can insert these kinds of characters at the appropriate time. For example, if you have a zip code like UT.99CW, you might want to have Spry insert the period automatically after the user types the first two capital letters.

To use an autocomplete character, insert the character in the format pattern, as follows:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "zip_code", {format:"zip_custom", pattern:"AA.00AA"});
    </script>

The preceding code results in a text field that accepts values such as UT.99CW, AB.87PP, GV.44RE, and so on, with the period appearing as an autocomplete character after the user types the first two capital letters.

You can also have Spry autocomplete letters (other than those in the preceding table), as in the following example:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "zip_code", {format:"zip_custom", pattern:"AA.00AAF3"});
    </script>

The preceding code results in a text field that accepts values such as UT.99CWF3, AB.87PPF3, GV.44REF3, and so on, with the period appearing as an autocomplete character after the user types the first two capital letters, and the F3 appearing after the user types the last two capital letters.

To use any of the special characters listed in the preceding table as an autocomplete character, escape them with a double backslash (\\), as in the following example:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "zip_code", {format:"zip_custom", pattern:"AA.00AA\\B3"});
    </script>

The preceding code results in a text field that accepts values such as UT.99CWB3, AB.87PPB3, GV.44REB3, and so on, with the period appearing as an autocomplete character after the user types the first two capital letters, and the B3 appearing after the user types the last two capital letters.

To use a backslash (\) as part of an autocomplete sequence, double it, and escape it using a double backslash—a total of four backslashes (\\\\)—as follows:

    <script type="text/javascript">
    	var textfieldwidget1 = new Spry.Widget.ValidationTextField("textfieldwidget1", "zip_code", {format:"zip_custom", pattern:"AA\\\\00AA"});
    </script>

The preceding code results in a text field that accepts values such as UT\99CW, AB\87PP, GV\44RE, and so on, with the backslash appearing as an autocomplete character after the user types the first two capital letters.

Recall that javascript is case sensitive.

## Textfield Validation Widget Methods

### reset

Reset the widget to its original state.

#### Format

widgetName.reset();

#### Example

     <a href="#" onclick="textfield1.reset(); return false;">Reset Textfield</a>

### validate

Validates the current state of the widget.

#### Format

widgetName.validate();

#### Example

    <a href="#" onclick="textfield1.validate(); return false;">Validate Textfield</a>

Copyright © 2007. Adobe Systems Incorporated.
All rights reserved.