Using Spry Widgets: Validation Textarea Overview

About Spry Widgets

A Spry widget is a page element containing built-in behaviors 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 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).

Anatomy of the Validation Textarea widget

The Validation Textarea widget is a textarea form field with validation support for the inserted text. Users can easily adjust the validation rules they need to enforce.

At a first glance, the Validation Textarea widget has the same appearance as a standard textarea form control, but what differs is the added validation that triggers on the client-side (browser).

To create a Validation Textarea widget, you only need a simple textarea input. Turn it into a Spry widget by adding a few simple elements to it.

The following illustration shows a Validation Textarea widget as seen in browser:

Validation Textarea

You can create a widget by simply adding a HTML tag container(<SPAN> for instance) around the TEXTAREA 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 TEXTAREA tag, but error messages cannot be used. Instead, only CSS classes will be used to show the different states.

The Validation Textarea widget has a set of default states associated. 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 Select widget at any moment, depending on the validation results and other events.

A Validation Textarea 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 SpryValidationTextarea.css file associated to the widget.

Error messages can be added to a Validation Textarea widget by simply creating a span tag (or any other container tag) 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 widget container has a specific class applied (when the widget state changes).

The following illustration shows some states for Validation Textarea widget:
Validation Textarea


You can change the default appearance of the Validation Textarea 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 in the SpryValidationTextarea.css file.

The code for the Validation Textarea widget also includes script tags in the head of the document and after the textarea HTML markup. The script tag in the head of the document defines all the JavaScript functions related to the Validation Textarea widget. The script tag after the Validation Textarea widget contains the instantiation of the corresponding JavaScript widget object.

Following is the HTML markup for a Validation Textarea widget, along with an error message and the associated JavaScript:

<head>
...         
    <!-- Link the JavaScript library to the textarea widget -->   
    <script src="includes/SpryValidationTextarea.js" type="text/javascript"></script>
    <!-- Link the CSS style sheet to the textarea widget -->
    <link href="SpryValidationTextarea.css" rel="stylesheet" type="text/css" />
</head>
<body>
      <span id="TextareaWidget">
          <textarea name="fieldName" cols="45" rows="5"></textarea>
          <span class="textareaRequiredMsg">Please add a description. </span>    
      </span>
      <script type="text/javascript">
            var TextareaWidgetObject = new Spry.Widget.ValidationTextarea("TextareaWidget");
       </script>
</body>

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 applying different classes on the HTML widget tag container when the widget enters a validation state.

Spry Validation Textarea Widget Structure

In the example above, SPANs are used to create the Validation Textarea widget structure with its error messages.

Instead of the SPAN tag you can use almost any container tag you want, because the widget is identified by the tag ID, not the actual container tag. The appearance of the error message is done using CSS cascading that doesn't look at the actual tag of the error message.

The widget constructor identifies the HTML element whose ID has been passed as an argument to the constructor and then it looks inside the container for the corresponding TEXTAREA tag. If the ID passed to the constructor is the ID of a TEXTAREA tag, it uses this element to attach validation triggers on it. However, because in this case there is no widget container tag, no error messages can be used.

Another example of widget structure:

Notice: Multiple input textarea elements do not work inside the same HTML container. Each text area should be its own widget.

CSS for the Validation Textarea widget

The SpryValidationTextarea.css file contains the rules which style the Validation Textarea 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 SpryValidationTextarea.css file:

/*Validation Textarea styling classes*/ 

.textareaRequiredMsg, .textareaMinCharsMsg, .textareaMaxCharsMsg, .textareaValidMsg {
	display:none;
}

.textareaRequiredState .textareaRequiredMsg,
.textareaMinCharsState .textareaMinCharsMsg,
.textareaMaxCharsState .textareaMaxCharsMsg
{
	display: inline;
	color: #CC3333;
	border: 1px solid #CC3333;
}

.textareaValidState textarea, textarea.textareaValidState {
	background-color:#B8F5B1;
}

textarea.textareaRequiredState, .textareaRequiredState textarea, 
textarea.textareaMinCharsState, .textareaMinCharsState textarea, 
textarea.textareaMaxCharsState, .textareaMaxCharsState textarea {
	background-color:#FF9F9F;
}

.textareaFocusState textarea, textarea.textareaFocusState {
	background-color:#FFFFCC;
}

.textareaFlashState textarea, textarea.textareaFlashState{
	color:red !important;
}

Using Validation Textarea widget

This section contains the following topics:

To insert a Validation Textarea widget

  1. Locate the SpryValidationTextarea.js and add it to your web site, if you haven't done this already. You can find the SpryValidationTextarea.js file in the widgets/ValidationTextarea folder in the Spry zip.

For example, create a folder called “includes” in the root folder of your web site, and upload the SpryValidationTextarea.js file to it. The SpryValidationTextarea.js file contains all of the necessary code for making the Validation Textarea widget interactive.

  1. If not already done, locate the SpryValidationTextarea.css file and add it to your web site. You might choose to add it to the root folder or to a CSS folder, if you have one. 
  1. In the page code, link the SpryValidationTextarea.js file to your web page by inserting the following script tag in the page’s head tag:
<script src="includes/SpryValidationTextarea.js" type="text/javascript"></script>

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

  1. Link the SpryValidationTextarea.css file to your web page by inserting the following link tag in the page’s head section:
<link href="SpryValidationTextarea.css" rel="stylesheet" type="text/css" />

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

  1. Insert a textarea form field (if you don't have one already added) where you want the validation textarea widget to appear on the page:
<textarea name="fieldName"></textarea>     

  1. Add a container to the textarea validation widget by inserting the span tag around the textarea input. Add SPAN with an error message.
<span id="TextareaWidget">
<textarea name="fieldName"></textarea>
<span class="textareaRequiredMsg">Please enter a description.</span>  
</span>

  1. Initialize the Spry Validation Textarea object by inserting the following script block in the HTML source code, after the container:
<script type="text/javascript">
    var TextareaWidgetObject  = new Spry.Widget.ValidationTextarea("TextareaWidget");
</script>     

It’s important that you make sure the ID of the span tag matches the ID parameter you specified in the Spry.Widget.ValidationTextarea method. It’s also important that you make sure the JavaScript call comes after the HTML code for the widget.

  1. Save the page. The complete code should look as follows:
<head>
 ...
  <script src="includes/SpryValidationTextarea.js" type="text/javascript"></script>
  <link href="SpryValidationTextarea.css" rel="stylesheet" type="text/css" />
...
</head>
<body>
...
<span id="TextareaWidget">
  <textarea name="fieldName" cols="45" rows="5"></textarea>
       <span class="textareaRequiredMsg">Please enter a description.</span>    
 </span>
  <script type="text/javascript">
     var TextareaWidgetObject  = new Spry.Widget.ValidationTextarea("TextareaWidget");
  </script>
...
</body>

To style the Validation Textarea widget

The Validation Textarea widget comes with a CSS file (SpryValidationTextarea.css) that provides default styling for the widget and other widget elements. You can easily style the widget to your liking by simply changing the appropriate CSS style.

The CSS rules for error messages in the SpryValidationTextarea.css style sheet use the same class names as the related elements in the HTML, so it’s easy for you to know which CSS rules correspond to which parts of the Validation Textarea widget.

To change the appearance of the Validation Textarea widget:

  1. Open the SpryValidationTextarea.css file. You can find the SpryValidationTextarea.css file in the widgets/ValidationTextarea folder in the package.
  1. Locate the CSS rule for the part of the textarea that you want to change. For example, if you want to change the background color of the validation textarea widget’s required state, you need to edit the .textareaRequiredState textarea, textarea.textareaRequiredState rule in the SpryValidationTextarea.css file.
  1. Make your changes to the CSS and save the file.

The SpryValidationTextarea.css file contains extensive comments, explaining the selectors and the logic behind each rule. Check it out for further information on styling.

Validation Textarea Widget Behaviors

The behaviors of the Validation Textarea widget consist in blocking form submission for not allowed values 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 textareaRequiredState class is applied on the widget container so that the user can receive a visual feedback (the background color for the textarea turns red) and the corresponding error message is also displayed. Also the Validation Textarea offers you a character counter.
If you don't want the CSS feedback behaviors, simply leave the CSS blank.

To change the state appearance of the Textarea Validation widget:

  1. Open the SpryValidationTextarea.css file. You can find the SpryValidationTextarea.css file in the widgets/ValidationTextarea directory.
  1. The Textarea Validation widget comes with some built-in CSS rules for the error messages associated with the widget states.

The following classes define the look for the elements associated to the Validation Textarea widget and for the widget itself:


.textareaRequiredState (Activates when the textarea widget has an empty value.)
.textareaMinCharsState (Activates when the textarea widget has too few characters.)
.textareaMaxCharsState (Activates when the textarea widget has too many characters.)
.textareaValidState (Activates when the entered value is valid.)
.textareaFocusState (Activates when the textarea widget receives focus.)
.textareaFlashState (Activates for short periods when the user is typing and the maximum number of characters has been reached, but the user is blocked in typing more text)

The following classes define the behavior for the elements that can be added for a state. (In our case these are the error messages specific for some states). The names of these classes are not hard coded in the JavaScript code. You can change them in both CSS and HTML as you wish. We just provide them into the CSS file as default values for a faster integration of the textarea widget. These classes are:

.textareaRequiredMsg (Defines the look and feel for required error message in different textarea widget states.)
.textareaMinCharsMsg (Defines the look and feel for minimum number of characters not met error message in different textarea widget states.)
.textareaMaxCharsMsg (Defines the look and feel for maximum number of characters exceeded error message in different textarea widget states.)

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

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

<script>
        var TextareaWidgetObject = new Spry.Widget.ValidationTextarea("TextareaWidget", {requiredClass: "required", invalidCharsMaxClass: "max", invalidCharsMinClass: "min", validClass: "valid", textareaFlashClass: "flash"});

</script>


Make the Validation Textarea widget not required

In order to allow the user to submit empty values, the widget should have '{isRequired: false}' as a property of the optional parameters. By default this property is set to true in the Spry framework, which means that empty values cannot be submitted.

<script type="text/javascript">
        var TextareaWidgetObject  = new Spry.Widget.ValidationTextarea("TextareaWidget", {isRequired:false});
</script>

Make the Validation Textarea widget not accept values having less than a specified number of characters

There will be cases when you don't want the user to insert less than a minimum number of characters. This can be accomplished by adding the minChars option in the widget constructor definition. Using this option you can define a minimum number of characters to be entered into the textarea before submitting the form. The value set should be a positive integer. The CSS class associated with this option is textareaMinCharsState. The code is the following:

<script type="text/javascript">
        var TextareaWidgetObject  = new Spry.Widget.ValidationTextarea("TextareaWidget", {minChars:"10"});
</script>

Make the Validation Textarea widget not accept values having more than a specified number of characters

There will be cases when you don't want the user to insert more than a maximum number of characters. This can be accomplished by adding the maxChars option in the widget constructor definition. Using this option you can define a maximum number of characters to be entered in the textarea widget before submitting the form. The value set should be a positive integer. The CSS class associated to this option is textareaMaxCharsState. The code is the following:

<script type="text/javascript">
        var TextareaWidgetObject  = new Spry.Widget.ValidationTextarea("TextareaWidget", {maxChars:10});
</script>

Enforce the Maximum Number of Characters into the Validation Textarea Widget

The Validation Textarea widget allows the maximum number of characters to be enforced. This means that once the user reaches the maximum number of characters, no more characters can be typed in. For this validation rule to work, the maxChars parameter should also be set and have a valid value. The option name is useCharacterMasking. The valid values for this option are true or false which will enable or disable the enforcement behavior. The default value is true. When this limitation is reached, the textareaFlashState CSS class is applied for a fraction of a second.

<script type="text/javascript">
        var TextareaWidgetObject  = new Spry.Widget.ValidationTextarea("TextareaWidget", {maxChars:10, useCharacterMasking: true});
</script>

Define the actions that will trigger the validation process

The submit action will always check the validity of the widget's value. You can define two other options for the validation process: validateOn:"blur" and validateOn:"change". The validateOn:"blur" option will trigger the validation process when the textarea widget loses its focus. The validateOn:"change" option will trigger the validation process when the user is making changes to the text. You can add these options as follows:

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

 

Set a Hint value for the Validation Textarea widget

When no value for the textarea is present, the Validation Textarea widget allows you to suggest the data you expect to be entered. This can be accomplished by using the hint option. This option receives a string value which will be displayed in the textarea when it is empty. When the textarea widget receives focus or it has a default value, the hint will disappear. This option doesn't depend on the validation type; you can always specify it:

<script type="text/javascript">
        var TextareaWidgetObject  = new Spry.Widget.ValidationTextarea("TextareaWidget", {hint:"Please enter your address"});
</script>


Display a counter with the number of characters entered

Validation Textarea widget allows you to display the number of typed characters. In order to use this option, you have to locate the widget container and insert an HTML pair of tags with an unique ID after the TEXTAREA tag. The preferred tag is <span>. The content of this tag will be later filled in by the widget. Then you need to add the following two options: counterType and counterId to the JavaScript constructor.
counterType defines the type of counter that will be used and will have one the following string options: "chars_count" and "chars_remaining".
- "chars_count" will count the number of characters that are typed into the textarea.
- In case you have a maxChars limitation you may also use the "chars_remaining" value which will display the number of characters remaining until the maxChars limit is reached.
counterId contains the ID of the tag where the counter will be displayed. This parameter is required for the counter.

Bellow is a full example of a Validation Textarea with the counter enabled:

<span id="TextareaWidget">
    <textarea name="fieldName" cols="45" rows="5"></textarea>
    <span id="my_counter_span"> </span>
    <span class="textareaRequiredMsg">Maximum number of characters exceeded.</span>    
</span>
<script type="text/javascript">
     var TextareaWidgetObject  = new Spry.Widget.ValidationTextarea("TextareaWidget", {maxChars:100, counterType:"chars_remaining", counterId:"my_counter_span"});
</script>

 

Note that attribute can be combined by listing them within the {}, separated by commas.


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