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).
hX_5.addConverter("id", new hX_5.MaskConverter(attributes)); where
id |
The ID of the HTML tag to which the component is attached. |
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. |
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".
[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.
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 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. |
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); }