1_Mask

TOCSTART

• Key Features
• Basic Configuration
• Creating the Own Mask Literals
• Customizing Styles
• Server-Side Event Listeners
• Client-Side Events
• Client-Side API

TOCEND

The MaskEdit component supports all of the features of the standard JSF InputText component and extends it with some additional features such as mask, blank, blankVisible that allows you to enter the data in a certain format.

Online Demo

Key Features

• All features of the standard InputText component
• Custom Mask Literals
• Extended styling

Basic Configuration

The MaskEdit component can be added to a page using the <o:maskEdit> tag. You should note the blank and mask attributes in the basic configuration.

The following example shows a definition of the MaskEdit with the basic attributes:

    <o:maskEdit id="creditCard"
                blank="#{OrderBean.creditCardBlank}"
                mask="#{OrderBean.creditCardMask}"/>

The attribute mask determine the type and amount of characters, and the blank responds for the input text form

before the entering. The attribute meanings must have strictly the same length and in positions, where

mask and blank symbols coincide, they are considered as separators.

Creating the Own Mask Literals

You have an opportunity to create your own mask literals and expand the base features. You should use the

maskSymbolConstructors attribute in which you send <tt>Collection&lt;MaskSymbolConstructor&gt;</tt>.</p>

Here's an example of using this feature:

<o:maskEdit
        id="customersId"
        blank="#{OrderBean.customersIdBlank}"
        mask="#{OrderBean.customersIdMask}"
        value="#{OrderBean.customersId}"
        maskSymbolConstructors="#{OrderBean.symbolConstructors}"
        blankVisible="true"
        />

The "#{OrderBean.symbolConstructors}" expression points to a backing bean method that returns Collection<MaskSymbolConstructor>. Here's how this collection might be specified:

    private Collection<MaskSymbolConstructor> symbolConstructors =
                            new LinkedList<MaskSymbolConstructor>();

    public OrderBean() {
        symbolConstructors.add(new MaskSymbolConstructor('X', "ABCD"));
        symbolConstructors.add(new MaskSymbolConstructor('x', "abcd"));
    }

Thereafter it is possible to use symbols 'X' and 'x' for the mask definition of the Order's backing bean:

    private String customersIdMask = "Xxx-###";
    private String customersIdBlank = "   -   ";

Here is a result:

Customizing Styles

You can apply styles for the MaskEdit component when it's in a normal, focused or rollover state.

The table below lists all style attributes:

Attribute	Description
style and styleClass	A style applied to the entire MaskEdit component.
rolloverStyle and rolloverClass	A style applied to the MaskEdit component in the rollover state.
focusedStyle and focusedClass	A style applied to the MaskEdit component when it is focused.

The following example demonstrates the usage of style-related attributes of the MaskEdit component:

     <o:maskEdit
             id="phone"
             blank="#{OrderBean.phoneBlank}"
             mask="#{OrderBean.phoneMask}"
             value="#{OrderBean.phone}"
             maskSymbolConstructors="#{OrderBean.symbolConstructors}"
             blankVisible="true"
             styleClass="defaultMaskEditStyle"
             rolloverStyle="background-color: #e0ffff;
                            border: 1px #1bb6d3 solid;"
             focusedStyle="background-color: #e0ffe0;
                           border: 1px #1bb6e9 solid;"
             />

The next image is for the MaskEdit component in a normal state:

<span><img src="https://github.com/TeamDev-Ltd/OpenFaces/blob/master/wikiResources/MaskEdit/MaskEdit_default_style.png"></span><br>
The appearance of the MaskEdit component in the rollover state is the next:
<span><img src="https://github.com/TeamDev-Ltd/OpenFaces/blob/master/wikiResources/MaskEdit/MaskEdit_rollover_style.png"></span><br>
When the user is typing the value, this style is changed to the following:<br>
<span><img src="https://github.com/TeamDev-Ltd/OpenFaces/blob/master/wikiResources/MaskEdit/MaskEdit_focused_style.png"></span><br></p>

Server-Side Event Listeners

Given that the MaskEdit component is a UIInput component, it can fire javax.faces.event.ValueChangeEvent just like any other UIInput component does. To handle a value change event on the server side, the valueChangeListener attribute should be used in the same way as for the HTMLInputText component. You can also add a value change listener to the component by using the <f:valueChangeListener> tag.

Client-Side Events

The MaskEdit component supports a set of standard client-side events such as onclick, ondblclick, onmousedown, onmouseover, onmouseup, onmouseout, onmousemove, onselect, onchange, onfocus, onblur, onkeyup, onkeydown, onkeypress.

Client-Side API

All client-side API methods for the MaskEdit component are listed in the following table:

Method	Description
getValue()	Returns a text currently entered in the MaskEdit component on which this function is invoked. This function should be used instead of the usual value field to get a correct result in case when prompt text is used.
setValue(text)	Sets a text for the MaskEdit component. This function should be used instead of the usual value field assignment to get correct results in case when prompt text is used.