Mask converter

Convert a JSF-formatted masked string value to/from a JavaScriptâ„¢ string. For example, the String converter converts the string "171-38-4339" to "171384339" after validating that the characters match the pattern specified by the mask.

The Mask Converter verifies that the content of a string matches a pattern. The pattern consists of "markers" which designate positions where characters belonging to a specified character set must be present and "literals" which are positions where exactly the specified character must be present. Besides checking for valid characters, the converter inserts literals (converting from string to masked string) or removes them (converting from masked string to string).

Note that the result of a successful conversion is always "padded" to the full length of the mask. For example, if the mask allows trailing spaces, the result of valueToString is the length of the mask (padded with spaces if need be) and the result of stringToValue is the length of the mask less literals (again padded with spaces).

JavaScript constructor

hX_5.addConverter("id", new hX_5.MaskConverter(attributes)); where

id

The ID of the HTML tag to which the component is attached.

Attributes

Table 1. Mask converter attributes

Attribute name

Description

mask

The pattern that the string must match. See below for details.

protect-mask

Protects the character in a "marker" position from being validated and input, i.e., you can "protect" a position in the string that contains a marker (#,?,!,~) so that a user can't type this character in, instead the value of that position is set programmatically (usually in the initial value). Effectively this turns a character in the value into a literal. If the protect-mask is provided, it should be the same length string as the mask. A position is marked as protected if it has an X (an upper-case X) in it. Positions without an X are not protected.

char1-regexpression

The Javaâ„¢ regular expression used to test characters marked with the # character in the mask. If not supplied, the expression [0-9] is used (that is, the character must be a digit).

char2-regexpression

The Java regular expression used to test characters marked with the ? character in the mask. If not supplied, the expression [A-Za-z] is used (that is, the character must be a Latin alphabetic character).

char3-regexpression

The Java regular expression used to test characters marked with the ! character in the mask. If not supplied, the ! character is not treated as a mask character.

char4-regexpression

The Java regular expression used to test characters marked with the ~ character in the mask. If not supplied, the ~ character is not treated as a mask character.

Mask

A mask defines which characters are allowed in which position in a value and specifies "literal" characters that appear in the in it. A mask consists of:
  • Input Markers - Special characters which designate a position in the mask where any character that matches a specified character set is allowed.
  • Literal Characters - All other characters in the mask are treated as literals. The literal character (and only that character) must appear in this position in the string.

By default, there are two input marker characters, # and ? (pound sign and question mark). By default, # means "a digit character between 0 and 9" is allowed here and ? means "a Latin alphabetic character between a and z and A and Z" is allowed here.

Given this combination of markers and literals, the mask "###-##-####" defines a US social security number, that is, in a value, each position occupied by a # in the mask must have a digit in the value and each position occupied by a - in the mask must have a - in the value. Thus "191-33-1897" matches the mask. "191 33 1897" does not match the mask nor does "191-33-189".

Instead of using the default character sets assigned to the # and ? marker characters (digit and alphabetic), you can define your own character set for each marker by specifying a Java regular expression that is run to test characters in the marked positions. The regular expression should evaluate whether a single character matches or does not match. For example:

[A-Z]

Upper case Latin Alphabetic characters are allowed in this position

[A-Za-z ]

Upper and lower case Latin Alphabetic characters and space are allowed

[A-Za-z\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u00FF]

ISO 8859-1 alphabetic characters are allowed

In addition to specifying the characters allowed where the # and ? marker characters appear in the mask, up to two additional marker characters (! and ~) can be defined by specifying the regular expressions used with these two characters.

For example, the mask #???-!!!!! with:
  • char1-regexpression = [A-Z] (char1 is the # marker)
  • char2-regexpression = [A-Za-z0-9] (char2 is the ? marker)
  • char3-regexpression = [A-Za-z0-9 ] (char3 is the ! marker)

Means the string must start with an upper-case letter followed by at least three alphanumeric characters, followed by a dash. This may be followed by at most five more alphanumeric characters.

API calls

Table 2. Mask converter API calls

API call

Description

number = stringToValue(string)

Converts a string to a JavaScript number object. Returns null if fails.

string = valueToString(number)

Converts a JavaScript number to a string. Returns null if fails.

string = lastError()

If a conversion fails, returns the reason for the failure as a localized string.

object = setAttribute(attribute)

Sets an attribute or changes its value (if it was set previously).

string = getAttribute(attribute-name)

Retrieves the current value of an attribute.

Limitations

Example code

Convert the (masked) value of an input field to a string, "increment" part of the resulting value and put the result back.

// Construct the converter with a format of '?# feet ?# 
inches' where # is any digit and ? is any non-zero digit or 
space hX.addConverter("AZ1", new hX.MaskConverter
("mask:?# feet ?# inches", "strict:2", 
"char2-regexpression:[1-9 ]"));

var x = document.getElementById("form1:textA");
var cvt = hX.getConverterById("AZ1");
var d = cvt.stringToValue(x.value);

// Check for errors
if (d==null)
    alert ("ERROR: " + cvt.lastError());

// Increment the "inches" and put it back
else {
	var n = parseInt(d.substr(2),10)+1;
	if (n <= 12)
		d = d.substr(0,2)+((n<10)?" ":"")+n;
	else {
		d = (parseInt(d.substr(0,2),10)+1)+"";
		if (d.length==1) d = " " + d;
		d = d.substr(0,2)+" 1";
	}
    x.value = cvt.valueToString(d);
}
Related tasks
Adding input components to a Faces JSP page

Feedback