Using Spry Widgets: Validation Password Overview

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 Password widget are called SpryValidationPassword.css and SpryValidationPassword.js).

• Anatomy of the Validation Password widget
• CSS for the Validation Password widget
• Using the Validation Password widget
• Validation Password Behaviors
• Validation Password Methods

See the Validation Password reference file and sample.

Anatomy of the Validation Password widget

The Validation Password widget is a password text field that can be used to enforce password rules (number and type of characters) and provide warning or error messages to the user.

To create a Validation Password widget, you need a password field that can be turned into a Spry Validation Password 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 Password widget Structure

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

<span id="sprypassword1">
	<input type="password" name="password1" id="password1" />
	<span class="passwordRequiredMsg">A value is required.</span>
	<span class="passwordMinCharsMsg">The minimum number of characters not met.</span>
	<span class="passwordMaxCharsMsg">The maximum number of characters exceeded.</span>
	<span class="passwordInvalidStrengthMsg">The password strength condition not met.</span>
	<span class="passwordCustomMsg">User defined condition not met.</span>
</span>

...
<script type="text/javascript">
	var sprypassword1 = new Spry.Widget.ValidationPassword("sprypassword1");
</script>

CSS for the Validation Password widget

The SpryValidationPassword.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 SpryValidationPassword.css file:

   .passwordRequiredMsg, 
   .passwordInvalidStrengthMsg, 
   .passwordMinCharsMsg,
   .passwordMaxCharsMsg,
   .passwordCustomMsg,
   .passwordValidMsg {
      display: none;
   }
   .passwordRequiredState .passwordRequiredMsg,
   .passwordMinCharsState .passwordMinCharsMsg,
   .passwordMaxCharsState .passwordMaxCharsMsg,
   .passwordInvalidStrengthState .passwordInvalidStrengthMsg,
   .passwordCustomState .passwordCustomMsg
   {
      display: inline;
      color: #CC3333;
      border: 1px solid #CC3333;
   }
   .passwordValidState input, input.passwordValidState {
       background-color: #B8F5B1;
   }
  
   input.passwordRequiredState, .passwordRequiredState input, 
   input.passwordInvalidStrengthState, .passwordInvalidStrengthState input, 
   input.passwordMinCharsState, .passwordMinCharsState input, 
   input.passwordCustomState, .passwordCustomState input, 
   input.passwordMaxCharsState, .passwordMaxCharsState input {
      background-color: #FF9F9F;
   }
   .passwordFocusState input, input.passwordFocusState {
      background-color: #FFFFCC;
   }
 

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

Using Validation Password widget

This section contains the following topics:

• Inserting a Validation Password widget
  
  
• Styling the Validation Password widget
  

Inserting a Validation Password widget

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

2. Locate the SpryValidationPassword.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 SpryValidationPassword.js file to your web page by inserting a script tag in the page’s head section:

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

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

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

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

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

5. Insert a password text field.

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

6. Add a container to the Password validation widget by inserting the span tag around the Password input. Give the container an ID attribute.

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

7. Initialize the Spry Validation Password object by inserting the following script block in the HTML source code, after the container.

   <script type="text/javascript">
   
     var pw1  = new Spry.Widget.ValidationPassword("PasswordWidget");
   
   </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.ValidationPassword method. It is also important that you make sure the JavaScript call comes after the HTML code for the widget.

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

   <head>
      ...
      <script src="includes/SpryValidationPassword.js" type="text/javascript"></script> 
      <link href="includes/SpryValidationPassword.css" rel="stylesheet" type="text/css" />
     ...
   </head>
   <body>
     ...
     <span id="PasswordWidget">
       <input type="password" name="fieldName" value="" />
   </span>
   
      <script type="text/javascript">
         var pw1  = new Spry.Widget.ValidationPassword("PasswordWidget");
      </script>
     ...
   </body> 

To style the Validation Password widget

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

The Validation Password widget comes with a CSS file (SpryValidationPassword.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 Password Validation widget:

1. Open the SpryValidationPassword.css file. You can find the SpryValidationPassword.css file in the 'widgets/passwordvalidation' directory.

2. The Password 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.

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

   .passwordRequiredState .passwordRequiredMsg,
   .passwordMinCharsState .passwordMinCharsMsg,
   .passwordMaxCharsState .passwordMaxCharsMsg,
   .passwordInvalidStrengthState .passwordInvalidStrengthMsg,
   .passwordCustomState .passwordCustomMsg
   {
   	display: inline;
   	color: #CC3333;
   	border: 1px solid #CC3333;
   }
   

   The above rules set the error message to red text with a border. 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 SpryValidationPassword.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 PasswordWidgetObject = new Spry.Widget.ValidationPassword("PasswordWidget", {requiredClass: "required", invalidClass: "invalid" ,validClass: "valid"});
   </script>  

   Option	Type	Default	Description
   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	passwordFocusState	Custom CSS class to use for the focus state. Replaces the default .passwordFocusState class.
   requiredClass	string	passwordRequiredState	Custom CSS class to use for the required state. Replaces the default .passwordRequiredState class.
   invalidCharsMinClass	string	passwordMinCharsState	Custom CSS class to use for the invalidCharsMin state. Replaces the default .passwordMinCharsState class.
   invalidCharsMaxClass	string	passwordMaxCharsState	Custom CSS class to use for the invalidCharsMax state. Replaces the default .passwordMaxCharsState class.
   invalidStrengthClass	string	passwordInvalidStrengthState	Custom CSS class to use for the InvalidStrengthState state. Replaces the default .passwordInvalidStrengthState class.
   validClass	string	passwordValidState	Custom CSS class to use for the valid state. Replaces the default .passwordValidState class.

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

Validation Password widget Behaviors

The behavior of the Validation Password widget consists of:

• Blocking form submission if the password 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 password strength, the form submission is blocked and the passwordRequiredState class is applied to the widget container.

Make the Validation Password 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 PasswordWidgetObject = new Spry.Widget.ValidationPassword("PasswordWidget", {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 Password widget loses its focus. The validateOn: "change" option will trigger the validation process when the user is making the changes for the Password widget. You can add these options as follows:

<script type="text/javascript">
      var PasswordWidgetObject = new Spry.Widget.ValidationPassword("PasswordWidget", {validateOn:["blur", "change"]});
</script>

Setting Password Strength

The key part of the Password widget is the ability to specify the strength of the value typed. Using options in the constructor, the developer can specify the minimum length of the password and also determine if combinations of letters, numbers, uppercase or special characters are required to make a valid password.

To set a password strength, use a combination of these options. For instance:

<script type="text/javascript">
      var PasswordWidgetObject = new Spry.Widget.ValidationPassword("PasswordWidget", {minAlphaChars;3, maxSpecialChars:2, maxChars:8});
</script>

Combining Attributes

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

 <script type="text/javascript">
      var PasswordWidgetObject = new Spry.Widget.ValidationPassword("PasswordWidget", {maxChars:8, validateOn:["blur", "change"]});
 </script> 

Password Methods

The password validation widget has 2 public methods.

Reset

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

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

Validate

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

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

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