dijit/form/ValidationTextBox

Authors:Becky Gibson, Doug Hays, Bill Keese, Craig Riecke
Project owners:Doug Hays, Bill Keese
since:V1.0

Introduction

A ValidationTextBox is an <input>-like widget that checks to make sure the user’s input is valid (according to a specified criterion). It flags invalid input by changing the box color, showing an icon, and displaying a tooltip detailing the error.

Note that a ValidationTextBox by itself will not prevent invalid entries from submission. To ensure they’re not, simply surround your form with a dijit/form/Form widget.

Usage

The following attributes can be specified when you create a ValidationTextBox:

Parameter Type Description
required boolean Whether the field is required or not. false by default.
promptMessage String Tooltip text that appears when the text box is empty and on focus. Null by default.
invalidMessage String Tooltip text that appears when the content of the text box is invalid.
missingMessage String Tooltip text that appears when the content of the text box is empty and the field is required.
constraints Object Holds constraints (like min and max values) for use in subclasses of ValidationTextBox.
regExp RegExp Regular expression pattern to be used for validation. If this is used, do not use regExpGen.
regExpGen function Function that should return a string representing the body of a regular expression; see the String.replace() format. If this is used, do not use regExp.
tooltipPosition String Define where Tooltip will appear.

Methods:

isValid()
Method that calls validator function.
validator()
Method that determines whether the content of the text box is valid. Called at these events: onblur, oninit, onkeypress. See also: tips.
displayMessage()
Method that displays validation errors or prompt messages. Uses dijit/Tooltip by default.

Examples

Declarative example

ValidationTextBox widgets usually use Regular Expression validation, as in the following example:

require(["dojo/parser", "dijit/form/ValidationTextBox"]);
<label for="phone">Phone number, no spaces:</label>
<input type="text" name="phone" id="phone" value="someTestString" required="true"
    data-dojo-type="dijit/form/ValidationTextBox"
    data-dojo-props="regExp:'[\\w]+', invalidMessage:'Invalid Non-Space Text.'" />

Using regular expressions

The regular expression syntax comes directly from JavaScript. The start and ending qualifiers of the regular expression, ^ and $, are implicit - you do not need to include them. This code demonstrates a ValidationTextBox that only accepts a 5 digit zip code.

require(["dojo/parser", "dijit/form/ValidationTextBox"]);
<label for="zip">Also 5-Digit U.S. Zipcode only:</label>
<input type="text" name="zip" value="00000" required="true"
    data-dojo-type="dijit/form/ValidationTextBox"
    data-dojo-props="regExp:'\\d{5}', invalidMessage:'Invalid zip code.'" />

Generate regular expressions

ValidationTextBox also supports functions that generate regular expressions. Having a generating function enables you to write much more dynamic Web applications. ValidationTextBox passes its constraints object to the generating function. The following code demonstrates a dynamic ValidationTextBox that only accepts a 5 digit zip code after 5:00PM, and only accepts a county name before then.

require(["dojo/parser", "dijit/form/ValidationTextBox"]);

var after5 = function(constraints){
    var date = new Date();
    if(date.getHours() >= 17){
        return "\\d{5}";
    }else{
        return "\\D+";
    }
}
<label for="zip2">Also 5-Digit U.S. Zipcode only:</label>
<input type="text" name="zip" value="00000" id="zip2" required="true"
    data-dojo-type="dijit/form/ValidationTextBox"
    data-dojo-props="regExpGen:after5, invalidMessage:'Zip codes after 5, county name before then.'" />

Accessibility

Keyboard

The ValidationTextBox widget uses native HTML INPUT (type=text) controls.

Screen Readers

If an invalid value is entered into a validating Text Box the “state” of the Text box changes, i.e. its background color changes. To accommodate users who are blind, the Text Box’s ARIA state is changed to “invalid” so a screen reader can notify the screen reader user. In addition to the “state” change, a pop-up appears. When the pop-up appears screen readers should read the contents of the pop-up. The pop-up text comes from the “invalidMessage” parameter.

Known Issues

Sometimes the popup message supplied by invalidMessage attribute may be unnecessary. For example, omitting a required field already displays an icon when the cursor leaves the field. In these cases you can omit the “invalidMessage” parameter, but keep in mind that good labels and instructions are still necessary for accessibility, i.e. if the invalid popup will not be displayed then there must be clear instructional text indicating the field is required.

As of the Dojo 1.0 release and beyond: Window-Eyes 6.1 speaks “read only” for fields that have been marked with the ARIA property invalid=true even though the field is still editable.

Error in the documentation? Can’t find what you are looking for? Let us know!