AX1584

Using an input mask with text boxes

You can configure a text box to use an input mask. An input mask defines the allowed inputs for a text box, and specifies a format for the input.

For example, imagine that you need users to enter a phone number into a text box, to be saved to the database. If you use a regular text box, users might enter phone numbers in a variety of formats, such as 555-555-1111 or 555.555.1111 or (555) 555-1111. Some users might not include the area code, and other users might add an extension. This approach will result in inconsistent data in the database. Instead, you can use an input mask to define the specific allowed input and format for the phone number, so that all entries will be consistent.

Configuring a Text Box component to use an input mask

To configure a Text Box component for numeric input, set the Type property to Input Mask. You can then configure the following options:

Item	Description
Format	Define the input mask format. For example, you might enter (000) 000-0000 to specify a phone number format. See the following section for more information on defining an input mask format.
Preserve Input Mask	Specifies whether the text submitted to the source file includes the input mask format or not. If disabled (default), then the user input will be written back to the source file as raw text with no format. If enabled, then the user input will be written back to the source file using the specified format. For example, imagine the input mask is defined as (000) 000-000, and the user enters (123) 456-7899. If this option is disabled, then the input will be written to the source file as raw text: 1234567899. If this option is enabled, then the input will be written to the source file as it displays to the user, including the formatting characters. You should enable this option if you need to display the input in a different component using the same format, or if you need to save the input to the database using the format.

Example input mask text box configuration

When the text box is set to Input Mask type, all settings relating to the Text and Numeric types do not apply. If defined on the Form Control Sheet, these options will be ignored. This includes options such as rich text, multi-line input, and minimum / maximum numeric values.

Defining the input mask format

The input mask format defines both the allowed characters for input and the display format for the input. The following tables list the recognized characters that can be used to define an input mask.

Input characters

The following characters determine what a user can enter into the text box:

Character	Description
0	User must enter a number between 0 and 9.
9	User must enter a number between 0 and 9, or a space.
#	Same as 9, except user can also enter plus (+) or minus (-) signs.
L	User must enter a letter from a-z, in upper or lower case.
?	User must enter a letter from a-z, in upper or lower case, or a space.
&	User can enter any character.
C	User can enter any character, or a space.
A	User can enter any alphanumeric character.
a	User can enter any alphanumeric character, or a space.

Display characters

The following characters define display elements of the input mask:

Character	Description
.	Decimal placeholder. The decimal separator will be determined by the current regional format.
,	Thousands placeholder. The display character will be determined by the current regional format.
$	Currency placeholder. The display character will be determined by the current regional format.
All other characters	All other characters not listed as recognized display or input characters will be rendered as is.

The following examples illustrate some potential uses of input mask formats:

Input mask behavior

The following example of input mask behavior uses an input mask format of (000) 000-000.

If no text has been input (and no default text is present in the Text field), then the text box displays placeholder text as normal (or blank if no placeholder text is defined).

When the user tabs or clicks into the text box, the input mask displays. The underscores indicate areas where text input is expected.

As the user types in text, the underscores are replaced by the inputted text.

The inputted text always displays in the text box using the defined format mask. The value submitted back to the source file is either formatted text (exactly as shown in the text box) or raw text (only the user input with no formatting), depending on whether Preserve Input Mask is enabled.