If you want to force the data entered by a user into a certain pattern (for structured values such as dates and phone numbers) you can use mask converters. In this post, I’ll show how to implement them and explain what they do (and don’t do).
Adding a Mask Converter
To add a mask converter to a field, select the Data subtab of the field properties and change the Display type value to Mask.
Once you do this, a field will display below for you to enter the mask pattern.
Primary Input Markers
Mask patterns can contain input markers and literal characters.
The 3 most common input markers are the following:
- ? – a letter
- # – a digit
- A – a letter or digit
You can use these to define a pattern of a specific number of letters and/or digits.
For example, to define a value with 3 letters (such as a country code), the pattern would be ???.
Pretty straightforward.
Input Converter != Input Mask
At this point, it’s important to understand that the result of this might be different than you’d expect.
1) There is no visual indicator that a field is masked.
2) The data entry is not restricted in any way.
3) If you save the form and the data in any field doesn’t match the mask, then it appears that nothing happens.
If you have an Display Error control next to a masked field or a Display Errors control at the top of the page, you’ll see that it throws a “Source string is unmatched with mask pattern.” error in this case. (If you manually enter data that matches the defined mask pattern, the form is saved successfully.)
Even though you may have expected an input mask on the field, the behavior makes sense conceptually because it’s a converter; converters work to format the data after you enter it and submit the form (and before it’s displayed when viewed later).
You’ll need to display the pattern somewhere near the field or you will drive your users crazy by not letting them know how the data needs to be entered.
Input Mask jQuery Plugin
If you’re looking for an input mask, check out this post by Marky Roden regarding a jQuery plugin.
Including Literal Characters
Now back to the mask converter…
Defining the quantity of letters and digits is useful, but it’s often even more helpful to include literal characters to help format the data to increase the readability.
For example, a US phone number is more readable when in this format: (###) ###-####
As I sat to write this post, I did a cursory search and found that Brian Moore has also written about this recently. Take a look at his approach to removing literal characters in a phone number.
Other examples where literals are useful in formatting the data are credit card numbers, social security numbers, and dates (although date pickers are generally much more convenient to work with).
You may also have other patterns that are custom to your organization, such an an invoice number that starts with ‘INV-’. You could have a pattern like this: INV-#####
Computing a Mask Pattern
You can also compute the mask pattern, in case it needs to change based on some other factor. However, it is computed on page load, so do not expect it to change during a page refresh.
I could see a use case where you’d have some kind of identifier that starts with the current year. Here is a simple computed pattern to define this:
var d = new Date(); return d.getFullYear() + '-' + '#####';
The asis property
The asis property determines whether to filter out any literal characters in the mask.
The default is false, which will keep any formatting characters in the data saved to the field.
You can modify the property by selecting the input control, going to the All Properties subtab and then locating the mask under data>converter
Other Pattern Input Markers
There are a few other markers that you can use when defining the mask pattern:
- H – a hex character (0-9, A-F)
- * – anything
- ‘ – escape a formatting character
- U – convert lowercase to upper case
- L – lowercase stay lowercase
