inputMask minimizes the chances for the user to input incorrect data. It applies client-side validation with the provided masking template.
A basic example of an input mask for a phone number input would be as follows:
<p:inputMask value="#{inputMaskBean.phone}"
mask="(999) 999-9999"/>As can be seen with the mask (999) 999-9999, it is stated that only numbers can be input along with the parenthesis and dashed structure. The initial visual of the input will be as seen in the following screenshot:
The fields that are filled up with number 9 in the mask will be empty and the rest will be rendered with the initial phase. The character 9 is used to depict only numeric characters that could be input for the field. By providing the alphabetic character a, input could also be restricted to alphabetic characters only. An example would be the input of a product key, as follows:
<p:inputMask value="#{inputMaskBean.productKey}" mask="a999-a9"/>This will restrict the input of the first characters of the two sections that are separated by the dash, only to the alphabetic characters.
The inputMask component decorates the input text component with JavaScript to provide the masking feature. With each keypress event, the value is checked against the mask provided for the validation on the client-side. The component will unmask itself when the readonly attribute is set to true. PrimeFaces wraps masked input plugin of jQuery for the inputMask component.
There is also the slotChar attribute, which renders the character(s) given in the template. The default value of the slotChar is the _ character. For instance, we can change the slotChar value for the phone input with the definition X; the component would be defined as follows:
<p:inputMask value="#{inputMaskBean.phone}"
mask="(999) 999-9999" slotChar="X" />The component will be rendered as shown in the following screenshot:
With the asterisk character, we can represent an alphanumeric character to be input by the user, which could be A to Z, a to z, or 0 to 9.
<p:inputMask value="#{inputMaskBean.productKey}"
mask="a*-999-a999" />With the preceding inputMask definition, inputs such as ac-223-a481 or a2-223-a481 will be validated as true.
It is also possible to make a part of the mask optional with the use of a question mark character. Anything listed after ? within the mask definition will be considered as an optional user input. A common example for this is a phone number with an optional extension:
<p:inputMask value="#{inputMaskBean.phoneExt}"
mask="(999) 999-9999? x99999" />When the user finishes the input by reaching the ? character and un-focusing the component, the rest of the validation will be skipped, and the input up to that section will not be erased. Input values such as (555) 204-2551 or (555) 204-2551 x1980 will be valid for this optional input.
With the help of some JavaScript, it's also possible to change the mask value of the component dynamically. In the screenshot given next, we define two masks, one is (99)9999-9999, which is the default value, and the other one is (99)9-9999-9999, which is enabled when checkbox gets clicked:
The JavaScript and component definition would be as follows:
<script type="text/javascript">
function setMask() {
var c = PF('cbxMask'),
var i = PF('phoneMask'),
if (c.isChecked()) {
i.jq.mask('(99)9-9999-9999'),
i.jq.focus();
} else {
i.jq.mask('(99)9999-9999'),
i.jq.focus();
}
}
</script>
<p:inputMask id="phone" widgetVar="phoneMask"
value="#{inputMaskBean.phone2}" mask="(99)9999-9999"/>
<p:selectBooleanCheckbox itemLabel="Extended Mask"
onchange="setMask()" widgetVar="cbxMask"/>This recipe is available in the demo web application on GitHub (https://github.com/ova2/primefaces-cookbook/tree/second-edition). Clone the project if you have not done it yet, explore the project structure, and build and deploy the WAR file on every Servlet 3.x compatible application server, such as JBoss WildFly or Apache TomEE.
The showcase for the recipe is available under http://localhost:8080/pf-cookbook/views/chapter3/inputMask.jsf.