# Using Spry Widgets: Validation Confirm Overview

The Validation Confirm Widget is a textfield or a password form field in an HTML code form that display valid or invalid states when the user re-type or fails to re-type a value typed in another similar field from the same form. For example you can add a Validation Confirm Widget to a form in which a user should type twice the same password. If the user fails to type the same password in both fields, the widget returns a message stating that the password retype condition was not met.

### About Spry Widgets

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 can include functionality that lets users show or hide content on the page, change the 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 Validation Confirm widget are called SpryValidationConfirm.css and SpryValidationConfirm.js).

- Anatomy of the Validation Confirm widget
- CSS for the Validation Confirm widget
- Using the Validation Confirm widget
- Validation Confirm Behaviors
- Validation Confirm Methods

See the Validation Confirm reference file and sample.

### Anatomy of the Validation Confirm widget

The Validation Confirm widget enables a commonly used pattern of verifying passwords by having users repeat the password or other field and 'confirming' they are identical before proceeding with the form submit. The Confirm widget is the second field that confirms the first.

Password: - A password field or Spry Password Validation widget.

Retype Password: - This is the confirm widget.

To create a Validation Confirm widget, a text field can be turned into a Spry Validation Confirm widget by adding a few elements to it.

You can create a widget by simply adding a HTML tag container (e.g. <SPAN>) around text field. The container tag must have an ID. Any error messages go within this container. A small constructor script is added after the markup.

#### Spry Validation Confirm widget Structure

A basic Confirm Validation widget, with multiple error messages, looks like:

    Password:<input type="password" name="password1" id="password1" />

    <span id="spryconfirm1">
    	<label for="confirm1">Confirm:</label>
    	<input type="password" name="confirm1" id="confirm1" />
    	<span class="confirmRequiredMsg">A value is required.</span>
    	<span class="confirmInvalidMsg">The values do not match</span>
    </span>

    ...
    <script type="text/javascript">
    var ConfirmWidgetObject = new Spry.Widget.ValidationConfirm("spryconfirm1", "password1", {validateOn: ['blur']});
    </script>

In the constructor script, the values are: ("id of the widget container", "id of the field to confirm",{options})

### CSS for the Validation Confirm widget

The SpryValidationConfirm.css file contains rules which trigger the messages to display. The rules in the CSS file correspond to the class names specified in the HTML markup for the error messages. However, more complex selectors are required, which take into account the fact that a parent container can have a state class applied to it.

The following is the CSS code for SpryValidationConfirm.css file:

       .confirmRequiredMsg,
       .confirmInvalidMsg,
       .confirmValidMsg {
          display: none;
       }

       .confirmRequiredState .confirmRequiredMsg,
       .confirmInvalidState .confirmInvalidMsg {
          display: inline;
          color: #CC3333;
          border: 1px solid #CC3333;
       }
       .confirmValidState input, input.confirmValidState {
          background-color: #B8F5B1;
       }
       input.confirmRequiredState, .confirmRequiredState input,
       input.confirmInvalidState, .confirmInvalidState input{
          background-color: #FF9F9F;
       }
       .confirmFocusState input, input.confirmFocusState {
          background-color: #FFFFCC;
       }

As you can see, most of the rules simply handle the error states.

### Using Validation Confirm widget

This section contains the following topics:

- Inserting a Validation Confirm widget
- Styling the Validation Confirm widget

#### Inserting a Validation Confirm widget

1. Locate the SpryValidationConfirm.js and add it to your site, if you didn't do it already. You can find the SpryValidationConfirm.js file in the 'widgets/confirmvalidation' folder in the Spry zip.

2. Locate the SpryValidationConfirm.css file and add it to your site, if you haven't done so already. You might choose to add it to the root folder or to a CSS folder, if you have one.

3. In the page code, link the SpryValidationConfirm.js file to your web page by inserting a script tag in the page’s head section:

        <script src="includes/SpryValidationConfirm.js" type="text/javascript"></script>

   Make sure the file path to the SpryValidationConfirm.js file is correct. This path will vary depending on where you include the file in your web site.

4. Link the SpryValidationConfirm.css file to your web page by inserting a link tag in the page’s head tag:

        <link href="includes/SpryValidationConfirm.css" rel="stylesheet" type="text/css" />

   Make sure the file path to the SpryValidationConfirm.css file is correct. This path will vary depending on where you put the file in your web site.

5. Add the password field that is going to be confirmed.

       <input type="password" id="password1" name="password1" />

6. Insert a password text field where the user will confirm the text.

       <input type="password" id="password1" name="password1" />
       <input type="password" name="fieldName" value="" />

7. Add a container by inserting the span tag around the confirm input. Give the container an ID attribute.

       <input type="password" id="password1" name="password1" />
       <span id="ConfirmWidget">

           <input type="password" name="fieldName" value="" />

       </span>

8. Add any error messages that are needed.

       <input type="password" id="password1" name="password1" />
       <span id="ConfirmWidget">
         <input type="password" name="fieldName" value="" />
         <span class="confirmInvalidMsg">The values do not match</span>
       </span>

9. Initialize the Spry Validation Confirm object by inserting the following script block in the HTML source code, after the container. The var name is the name of the widget. The first value in the constructor is the ID of the widget container. The second value is the ID of the password field that is being confirmed.

       <script type="text/javascript">
       	var ConfirmWidgetObject = new Spry.Widget.ValidationConfirm("spryconfirm1", "password1");
       </script>

   It is important that you make sure the ID of the container span tag matches the ID parameter you specified in the Spry.Widgets.ValidationConfirm method. It is also important that you make sure the JavaScript call comes after the HTML code for the widget.

10. Save the page. The complete code looks as follows:

        <head>
           ...
           <script src="includes/SpryValidationConfirm.js" type="text/javascript"></script>
           <link href="includes/SpryValidationConfirm.css" rel="stylesheet" type="text/css" />
          ...
        </head>
        <body>
        ...
        <input type="password" id="password1" name="password1" />
        <span id="ConfirmWidget">
            <input type="password" name="fieldName" value="" />
            <span class="confirmInvalidMsg">The values do not match</span>
        </span>

         <script type="text/javascript">
            var ConfirmWidgetObject  = new Spry.Widget.ValidationConfirm("ConfirmWidget","password1");
         </script>
          ...
        </body>

#### Styling the Validation Confirm widget

Styling the Validation Confirm widget means changing the appearance of the error messages for different states.

The Validation Confirm widget comes with a CSS file (SpryValidationConfirm.css) that provides default styling for the error messages. You can easily style the error messages to your liking by simply changing the appropriate CSS rules.

To change the state appearance of the Confirm Validation widget:

1. Open the SpryValidationConfirm.css file. You can find the SpryValidationConfirm.css file in the 'widgets/confirmvalidation' directory.

2. The Confirm Validation widget comes with built-in CSS rules for the states and also for the elements (in this case, the error messages) that can be displayed for these states.

   States define the look of the actual password field. 'Msg' classes control the look of the actual error messages.

   The following classes define the look of the error messages associated to the Validation Confirm widget:

          .confirmRequiredMsg,
          .confirmInvalidMsg,
          .confirmValidMsg {
             display: none;
          }

          .confirmRequiredState .confirmRequiredMsg,
          .confirmInvalidState .confirmInvalidMsg {
             display: inline;
             color: #CC3333;
             border: 1px solid #CC3333;
          }
          .confirmValidState input, input.confirmValidState {
             background-color: #B8F5B1;
          }
          input.confirmRequiredState, .confirmRequiredState input,
          input.confirmInvalidState, .confirmInvalidState input{
             background-color: #FF9F9F;
          }
          .confirmFocusState input, input.confirmFocusState {
             background-color: #FFFFCC;
          }

   These styles can be changed to whatever is required. The regular rules of CSS apply, so they can be split up or edited as needed.

3. Add/change CSS rules for any of the behaviors you want.

   You cannot rename/replace class names associated with states in the SpryValidationConfirm.css file only with class names of your own, because the behaviors are hard-coded into the Spry framework. However, you can replace the default class with your desired class name by sending the new value as argument to the text field widget constructor. This does not apply for the error messages classes, as mentioned above.
   Here is an example on how you can change the required state's CSS class name, without breaking its functionality:

       <script type="text/javascript">
       	var ConfirmWidgetObject = new Spry.Widget.ValidationConfirm("ConfirmWidget", "password1", {requiredClass: "required", invalidClass: "invalid" ,validClass: "valid"});
       </script>

   The SpryValidationConfirm.css file has comments, explaining the selectors and the logic behind certain rules. Check it out for further information on styling.

### Validation Confirm Defaults and Options

There are a few options for the widget that will let you customize the behavior of the validation confirm.

Option | Type | Default | Description
--- | --- | --- | ---
isRequired | true or false | true | The user must fill in the confirm text field or password field in order to submit the form
validateOn | ["blur"]; ["change"]; | ["change"] | ["blur"]; ["change"]; or both together (["blur", "change"]).
additionalError | string | none | The id of an element in the page where the classes that applies to the main container also are added.
focusClass | string |  | Custom CSS class to use for the focus state. Replaces the default .ConfirmFocusState class.
invalidClass | string |  | Custom CSS class to use for the invalid state. Replaces the default .ConfirmInvalidState class.
requiredClass | string |  | Custom CSS class to use for the required state. Replaces the default .ConfirmFocusState class.
validClass | string |  | Custom CSS class to use for the valid state. Replaces the default .ConfirmValidState class.

### Validation Confirm widget Behaviors

The behavior of the Validation Confirm widget consists of:

- Blocking form submission if the Confirm criteria is not met
- Changing the CSS classes applied on the widget top container in order to trigger validation messages.

For instance, when users try to submit the form with the incorrect Confirm strength, the form submission is blocked and the ConfirmRequiredState class is applied to the widget container.

#### Make the Validation Confirm widget not required

By default, the 'isRequired' property is set to true - that means that the user must fill in the text field in order to submit the form. In order to allow the user to submit an empty field, the widget should have 'isRequired: false' as a property of the optional parameters.

    <script type="text/javascript">
       var ConfirmWidgetObject = new Spry.Widget.ValidationConfirm("ConfirmWidget", "password1", {isRequired:false});
    </script>

#### Define what action will trigger the validation process

The 'submit' action always checks the validity of the widget's selections. Besides the validation on submit, you can define other two options for the validation process:

- validateOn: "blur"
- validateOn: "change".

The validateOn:"blur" option will trigger the validation process when the Confirm widget loses its focus. The validateOn: "change" option will trigger the validation process when the user is making the changes for the Confirm widget. You can add these options as follows:

    <script type="text/javascript">
          var ConfirmWidgetObject = new Spry.Widget.ValidationConfirm("ConfirmWidget", "password1", {validateOn:["blur", "change"]});
    </script>

#### Combining Attributes

To combine multiple attributes, simple include them within the {}, separated by commas.

     <script type="text/javascript">
          var ConfirmWidgetObject = new Spry.Widget.ValidationConfirm("ConfirmWidget", "password1", {requiredClass:"myclassname", validateOn:["blur", "change"]});
     </script>

### Confirm Methods

The Confirm validation widget has 2 methods.

Reset

Used if you want to set the validation widget back to its default state.

    <input type="button" value="Reset" onclick="ConfirmWidgetObject.reset();">

Validate

Used if you want to validate the widget from some other object or event.

    <input type="button" value="Validate the field" onclick="ConfirmWidgetObject.validate();">

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