UI Elements User Input Mask Input

Updated: July 23, 2018
SAPUI5 Version 1.34

Mask Input

Intro

The mask input control (sap.m.MaskInput) governs what a user is permitted to enter in an input field. It allows users to easily enter data in a certain format and in a fixed-width input (such as a date, time, phone number, credit card number, currency, and IP address).

Usage

Use the mask input if:

  • You have to govern what a user is allowed to enter in an input field.
  • You have to enter data easily in a certain format and in a fixed-width input.
  • You have to enter input such as a date, time, phone number,  serial number, ISBN, or product activation key.

Do not use the mask input if:

  • The mask prevents users from entering essential data.
  • The users need to enter data in a format other than the one used by the mask (for example, if users have to enter a phone number with a format for a different region).
Possible uses - may require additional coding
Possible uses - may require additional coding
Possible uses - may require additional coding
Possible uses - may require additional coding

Responsiveness

The mask input extends the input control (sap.m.Input) and has all the normal properties of an input field.

Components

The mask input has a fixed length format based on instantiation, and the user’s input must conform to it. This may be particularly useful when the user needs to enter text or numbers with specific formatting, such as a phone number, postcal code, or credit card number.

Immutable Characters

When defining the mask format, the developer can place immutable characters, such as brackets and dashes, in specific positions. The format also specifies the range of valid characters for each separate position, thus preventing the user from entering invalid input.

For example, when the user enters a phone number, the area code in brackets and the space between the numbers are already present.

Note that the sap.m.MaskInput control extends sap.m.Input and has all the normal properties of an input field.

When creating a new mask, the developer can change the configuration of some default properties. For example, the default placeholder symbol “_” can be changed to something else.

Behavior and Interaction (incl. Gestures)

Entering Text

  • Mask string appears in the input field in focus.
  • The default placeholder symbol is “_” and can be changed to something else.

Copying and Pasting

Copying to a mask input field:

Users can copy both formatted and unformatted strings into a mask input field. When the texts are pasted, they take on the format defined for the mask input field.

Example: Mask input field for a number with the format:  (000) 000 000000

Copied source string Value in mask input field after pasting
(555) 333 123456 (555) 333 123456
555-333-123456 (555) 333 123456
555 (333) 12 34 56 (555) 333 123456

Copying from a mask input field:

If you copy a string from a mask input field and paste it elsewhere, the format of the mask input field is copied as well.

Information
For information on how to manage leading and treading whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Deleting Content

  • Select the entire string and delete it. The placeholders will reappear.
  • Deleting a character from the string leaves the input information unchanged, except for the deleted character, which is replaced by a placeholder. (The mask does not shift if a character is deleted.)
Deleting one/all characters in mask input
Deleting one/all characters in mask input

Guidelines

Validation Rules

Another option is to define new validation rules, such as allowing lowercase characters from “a” to “e” only. This is particularly flexible because these rules are defined with regular expression syntax.

The mask comes with two predefined validation rules: one for all characters in the English alphabet, and one for the numbers from zero to ten.

Therefore, when the mask format is being defined, the alphabetic rule is represented by the letter “a”, and the numeric rule by the number “9”. For example, a numeric mask format with a length of five characters would be specified as “99999”, a mask that accepts only alphabetical characters would be specified as “aaaaa”, and a mixed mask could be “aaa99”. In the mixed mask example, the user would not be able to enter numeric characters anywhere other than in the last two positions.

When you create the MaskInput instance, you can specify the following settings:

  • Mask: The format specification, such as (123) 999-999.
  • PlaceholderSymbol: A single character used to represent empty positions in a mask value, such as _ _ _ _ _.
  • Rules: A collection of sap.m.MaskInputRule instances.

Properties

Mask string

The mask is defined by its character type (or by its length, as applicable). You should consider the following important facts:

  1. The mask characters normally correspond to an existing rule (one rule per unique character). Characters that do not are considered immutable characters. For example, the mask ‘2099’, where ‘9’ corresponds to a rule for digits, has ‘2’ and ‘0’ as immutable characters.
  2. Adding a rule that corresponds to the symbol placeholder is not recommended and would lead to unpredictable behavior.

Placeholder symbol string  “_”

This defines a placeholder symbol. It is shown in a position where there has not yet been any user input.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation