JavaScripTools Manual

InputMask

Working with the InputMask

InputMask is a general-purpose mask. It can restrict wich characters can be typed, restrict size and apply case transformations. If you want to mask numbers and dates, please, consider using NumberMask and DateMask instead, because they are specific to these data types and offers specific and richer features.

The mask is composed of one or more fields. Each field can be a literal or an input, and can apply an specific case transformation. A mask that accepts only numbers, allowing a maximum of 5 digits has a single field, that accepts numbers and limits the size to 5. A mask like ##/AA is composed of 3 fields: 2 numbers, a literal '/' and 2 letters.

Each field is a subclass of the MaskField class, and can be one of the following classes:

• Literal: Is a fixed string literal. Receives the string on the constructor
• Input: Is a typeable field. Receives a string containing the accepted characters. null means any character
• Lower: An Input that transforms the text to lowercase
• Upper: An Input that transforms the text to uppercase
• Capitalize: An Input that capitalizes the text

The MaskField was called Field on previous versions, but has been renamed to enable compatibility with the excellent Prototype Framework, that already has a class named Field.

There are higher-level ways of constructing the mask fields. The FieldBuilder and MaskBuilder classes offers methods to do this. There are default instanced for both of these classes declared that you can use: fieldBuilder and maskBuilder.

The InputMask first constructor argument is a field, a field array or a string. When it's a string, the MaskBuilder.parse method is called. It will parse the string, recognizing the following characters:

#, 0 or 9	A number
a or A	A letter
? or _	Any character
l or L	A lowercase letter
u or U	An uppercase letter
c or C	A capitalized letter
\\, \#, \0, ...	Those literal characters. Remember that, when you write a string, '\\' means a single backslask. To use a backslash on the mask, you need 4 on the string.
Any other character	Literal characters

The second constructor argument is the control name or reference. The next arguments are custom event handlers, and not recommended as constructor arguments, but as properties. For more information about custom event handlers, check the introduction.

Here are some examples:

//Accept only alpha, using the Input constructor
var mask = new InputMask(new Input(JST_CHARS_BASIC_ALPHA), "myControl");

//Accept only letters and spaces, and applying capitalization, using the fieldBuilder
var mask = new InputMask(fieldBuilder.capitalize(JST_CHARS_LETTERS + " "), "customerName");

//A custom mask, for 3 numbers, a slash and 2 uppercase letters
var mask = new InputMask("###/UU", "customField");

//A custom mask, for 3 numbers, a forward slash and 2 uppercase letters
var mask = new InputMask("###\\\\UU", "customField");

//Apply a custom event handler for onkeypress event
mask.keyPressFunction = function(event, mask) {
    setValue("output", "My new value is " + mask.control.value);
}

Note for Internet Explorer: To use a mask on a textarea in Internet Explorer, the mask must have a single field, only with a set of allowed input, without case transformations and without size limit.

Padding

Another, more advanced field function is called padding. Each field can have an associated function that can be used to complete the field value. The function receives the text, the minumim size and the maximum size. By contract, this function should always return a text with matches those size constraints (remember max = -1 means no limit). There is always a default pad function if none was informed (it uses the lpad and left functions to enforce the text size). Custom masks rarely will have custom padding.

Padding is triggered on the following events:

• The user types the first letter of the next literal field
• On the control onblur event, the last field is padded
• The user forces pad by typing ctrl + Enter or ctrl + Right

Examples on custom padding:

function myPadding(text, min, max) {
    setValue("out", text)
    switch (text.toLowerCase()) {
        case "m": return "Male";
        case "f": return "Female";
        default: return text;
    }
}
var mask = new InputMask(fieldBuilder.inputLetters(0, -1, myPadding), "myControl");
//If the user types "m" and leaves the field, the field value becomes "Male"