AX1583

Using numeric text boxes

You can configure a text box as numeric, in order to restrict the user input to a number. This input can also be validated against an optional range of valid values. To do this, you must:

• Configure the Text Box component settings to support numeric input
• Set the number format of the Text cell to the desired number format

Configuring a Text Box component for numeric input

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

Item	Description
Min	Optional. The minimum number that can be entered into the text box, to communicate the desired numeric range to the user. By default, this option is blank, which means there is no minimum value. Enter a number if you want to define a minimum value. For example, if the minimum is set to 1, then the user can enter any number that is 1 or higher (up to the defined maximum number). If the user enters a number lower than the minimum, such as 0 or -5, then a red validation bar displays on the right side of the text box.
Max	Optional. The maximum number that can be entered into the text box, to communicate the desired numeric range to the user. By default, this option is blank, which means there is no maximum value. Enter a number if you want to define a maximum value. For example, if the maximum is set to 100, then the user can enter any number that is 100 or lower (down to the defined minimum number). If the user enters a number higher than the maximum, such as 150, then a red validation bar displays on the right side of the text box.

NOTE: Once a minimum or maximum value is set for the text box, the text box cannot be left blank or else it will display with the red validation bar. Therefore, the defined range should not be used with optional values unless there is a default value that you can define for the text box.

You can define just a minimum value or just a maximum value if the range only needs to be validated at one end. For example, the minimum could be set to 0 with no defined maximum, if you only need to verify that users do not enter negative numbers. You can also leave both values blank to allow any number.

If a user enters a number that is out of bounds, the tooltip displays a validation message as follows:

• If both a Min and Max are defined: "The value must be between Min and Max."
• If only a Min is defined: "The value must be greater than or equal to Min."
• If only a Max is defined: "The value must be less than or greater to Max."

If you intend the numeric input to be a percentage, the minimum and maximum values can be entered as either decimals (.1) or with percentage signs (10%).

Example numeric text box configuration

IMPORTANT: The minimum and maximum values provide validation messages only; the text box does not prevent the entry of a number that is outside of the range. The user is given feedback about the invalid value, but the value is still submitted back to the source file. There are no built-in controls to prevent the invalid value from being saved to the database or used in any other form processes. If you want to prevent a save-to-database based on the presence of an invalid value, then you must manually build in these controls. For example, you can dynamically enable or disable the button that executes the save-to-database based on whether certain values are valid, or you can use custom save validation to include these controls within the save-to-database process itself.

When the text box is set to Numeric type, all settings relating to the Text and Masked Input 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 input mask format.

Setting the number format for the Text cell

When using the Numeric type for a Text Box component, it is recommended to set the number format of the Text field to one of the following: Number, Currency, or Percentage. To do this, you must format the cell on the Form Control Sheet.

To quickly locate the Text field, you can do the following:

• Select the text box in the Form Designer dialog, or in the canvas thumbnail on the Form Assistant task pane.
• In the component properties, double-click the Text label.

This places your cursor on the corresponding Text property in the Form Control Sheet. You can then use regular spreadsheet features to change the number format as desired.

Setting the number format for the cell helps ensure that the numeric input will be handled and displayed as expected. If the cell is set to General or some other non-numeric format, the numeric text box may not behave as expected.

Numeric text box behavior

Users can type numbers into the text box. If the number does not fall within the defined minimum and maximum range, a red validation bar displays in the text box, and the tooltip displays a validation message.

The validation of the inputted value happens immediately after exiting the text box, regardless of whether the text box is set to auto-submit. It is not necessary to submit the value in order to validate it. As mentioned previously, invalid values are not prevented from submitting and do not prevent any processes such as save-to-database.

If the Text field is set to a numeric cell format (as described in the previous section), then the text box behaves as follows:

• The inputted value displays in the text box according to the defined numeric format. For example, a user may enter 1000 into the cell, which then displays as $1,000.00 if the cell uses Currency formatting.

• When a user tabs or clicks into the text box in order to edit an existing value, the raw value is displayed and the full contents of the cell are selected. This makes it easy to overwrite the current value with a new inputted value. Users can click in the cell again to de-select the full cell contents and make targeted edits to the value.

• If the cell uses Percentage format, numbers should be entered in decimal format. For example, enter .1 for 10%. It is not necessary to enter the percent sign; this will be applied by the cell format.

NOTE: Although users cannot type non-numeric characters into the text box, it is possible to copy and paste any text into the box. Any non-numeric entry will be flagged as invalid.