One of the new widgets just introduced in Kendo UI is kendoMaskedTextBox. This is something that we have been waiting for long time… no need to keep waiting. We can start today enjoying it. Let’s see how.
Introduction to KendoUI MaskedTextBox
What is a maked input field? Their definition: Define and restrict the data to be entered in an html input field.
Let me show it with an example, you have to define an input field and you want to control that what the user types follows some specific format (v.g. telephone number, credit card number, date…) so you are implicitly defining some validation rules. Both the user types it with the format that you want and it gets displayed with the correct format.
kendoMaskedTextBox: Defining a mask for a phone number
In my country, the telephone number are 9 digits and you typically have them in the format 999-999-999. So I want to define an input fields that only allows me to type phones so they have to be all digits and as soon as you finish a group of three the cursor moves to the next group.
What you would have is something like:
or when empty:
And the definition is as simple as:
<br /> $("#phone_number").kendoMaskedTextBox({<br /> mask: "000-000-000",<br /> value: "555123456"<br /> });<br />
or you can define using just HTML doing:
<div> <label for="phone_number">Phone number:</label> <input id="phone_number" data-role="maskedtextbox" data-mask="000-000-000" value="555123456"> </div>
Pretty simple and powerful!
kendoMaskedTextBox: Defining masks, the syntax
Kendo UI masked input predefines a series of mask rules (what to accept on each position of the mask). These are the predefined masks.
- 0 – Digit. Accepts any digit between 0 and 9.
- 9 – Digit or space. Accepts any digit between 0 and 9, plus space.
- # – Digit or space. Like 9 rule, but allows also (+) and (-) signs.
- L – Letter. Restricts input to letters a-z and A-Z. This rule is equivalent to [a-zA-Z] in regular expressions.
- ? – Letter or space. Restricts input to letters a-z and A-Z. This rule is equivalent to [a-zA-Z] in regular expressions.
- & – Character. Accepts any character. The rule is equivalent to \S in regular expressions.
- C – Character or space. Accepts any character. The rule is equivalent to . in regular expressions.
- A – Alphanumeric. Accepts letters and digits only.
- a – Alphanumeric or space. Accepts letters, digits and space only.
- . – Decimal placeholder. The decimal separator will be get from the current culture used by Kendo.
- , – Thousands placeholder. The display character will be get from the current culture used by Kendo.
- $ – Currency symbol. The display character will be get from the current culture used by Kendo.
kendoMaskedTextBox: Defining custom masks
But you do not have to use only those predefined mask rules, you might define your own.
Example: Defining a mask that allows typing only even numbers is as simple as:
$("#all-even").kendoMaskedTextBox({ mask: "eeee", rules: { "e": /[02468]/ } });
Where I define that the input supports 4 characters which mask rule is an e and then I define what e means by defining a rule that says that e might be a digit in the group 02468.
But the rule might even be a function. So this can also be implemented as:
$("#all-even").kendoMaskedTextBox({ mask: "eeee", rules: { "e": function(d) { return d % 2 == 0; } } });
Simply cool!!!
kendoMaskedTextBox: assigning values
This is important to note. In widgets as KendoDateTimePicker when you initialize the widget with an invalid date, this is displayed as it is until you edit the field.
Example: I initialize the DatePicker to February 29th, 2014 but this day does not exist. What we see is:
And when we enter in edition mode we get:
But, kendoMaskedTextBox works in a different way, the characters defined in the initialization are like typed by you and those that do not met the rule restriction are simply ignored.
So if we define a value of 12345678 for our 4 even digits mask, what we will get is:
$("#all-even").kendoMaskedTextBox({ mask: "eeee", rules: { "e": "/[02468]/" }, value: 123456789 });
That shows that the date that we used during the initialization is just ignored.
kendoMaskedTextBox: Still some features missing
This is actually a great widget. The only limitation that I’ve found is that masks do not support repeating factor something like saying that a number repeated seven times (something like 9(3) meaning that a digit between 0 and 9 repeated 3 times) or that some character mask should be typed between n and m times (something like 9(1..3) meaning that a number between 0 and 9 repeated between 1 and 3 times).