Overview

A textbox is a basic control that allows user to input values for capture, storage, or calculation. Each textbox must be associated with a Single Named Range (SNR) in the workbook.

Properties

The properties of a textbox are outlined below.

Named Range

A list of all Single Named Ranges (SNR) from the workbook. The value entered into this input will be sent to the calculation engine, as if the user entered the value into the spreadsheet model.

Selecting a named range from the list may default some of the other textbox properties based on some metadata captured from the spreadsheet model, such as the default value.

If you select a named range that contains formulas, the textbox control will be disabled, but still display the results of that named range. Named ranges that have already been bound to a different input in your user interface will be excluded from this list.

Enable Formula Override

This option becomes available only if you select a Name Range that contains a formula.

Enabling this option allows the formula result in the control to be overwritten. This essentially means that users can set a new value for this control during runtime, and the associated formula will not change the cell value once edited.

If a cell with Enable Formula Override is edited, a button will become available right next to the cell, that can be used to clear the formula override and revert the value of the cell back to the original formula-based calculated value.

Force Override on Save

This option becomes available only when Enable Formula Override is enabled, and the Name Range selected for the control contains a formula. Using this option is limited to the scenario in which the published application has an Action Button control with Save event.

When you Save a record in the published application, each control that has Force Override on Save option enabled will save its current value, and override the formula at the same time, even if you haven’t overwritten the value in the control manually. Force Override on Save option does that automatically when the record is being saved.

Name

The Name property constitutes the label that will appear in the user interface. Other properties, such as Placeholder, will also derive their dynamic {FriendlyName} value from this property.

Placeholder

The Placeholder property defines the text that will be visible in the textbox when no input has been entered. This will only appear if no default value is selected or if the user clears the input's value.

This property supposed the special {FriendlyName} tag to insert the value of the Name property into the placeholder.

Type

The Type property designates whether the textbox will be a single or multi-line textbox.

Size

The Size property denotes the size of the textbox in the user interface. Note that altering the style of textboxes via Cascading Style Sheets (CSS) may affect whether or not the size property is visibly relevant in your published application.

Text Alignment

The Text Alignment property indicates where the user's entered text will be aligned within the control. The available options are Left,Center and Right. Note that altering the style of these controls via Cascading Style Sheets (CSS) may affect whether or not this property is relevant in your published application.

Label Horizontal Alignment

The Label Horizontal Alignment property determines the horizontal orientation of the label. This value can be set to Left, Center, or Right. The default horizontal alignment is Left.

Label Vertical Alignment

The Label Vertical Alignment property determines the vertical orientation of the label. This value can be set to Top, Middle, or Bottom. The default vertical alignment is Middle.

Label Size

The Label Size property is the spacing distribution of the input control's label vs. the input control. The maximum width of both controls cumulatively is considered to be 12 - a width of 12 for the label would indicate that the label occupies a full row within its container and the input control occupies a full row beneath it.

Any label distribution below 12 will indicate that the label and the input control occupy the same row in the user interface. The label's width will be used to calculate the control's width such that the two controls cumulatively occupy the full width of 12.

For example, setting the Label Size to 6 will indicate that the control width is also 6. This means the label will occupy 50% the width of the row and the control will occupy 50% the width of the row.

Likewise, setting the Label Size to 3 will indicate that the control width is 9, meaning that the label will occupy 25% the width of the row while the input control occupies 75% the width of the row.

Setting the Label Size to 0 will hide the label in the user interface.

Pull Default Value From Metadata

When this option is selected, the default value of the control will be pulled from the default value of the named range it’s tied to. The default value coming from the named range can be overridden from the Metadata Editor (Names). When you enable this option, the Default Value property will be hidden.

Default Value

The Default Value property specifies the value that will be visible in this textbox when the user interface is first loaded. This property may have a suggestion populated if the target named range for the textbox includes a default value.

Tooltip Type

Tooltips are informative message boxes that are displayed when you mouse-over or click on a control. The Tooltip Type property determines the message style, and when the information will be shown.

Tooltip: The content will appear in a small bubble when the user enters focus on the target input by moving their mouse over the control.
Popover: The content will appear in a pop-up box when the user clicks on the target input.

Tooltip Content

This property accepts the special {FriendlyName} tag if you want to insert the value of the Name property of this control into the tooltip.

Tooltip

The Tooltip Content property determines the information that will appear in the tooltip bubble.

Popover

The Popover Content property determines the information that will appear in the popover message.

Clicking on the Edit Content button will launch an instance of a rich-text editor that supports HTML code. The editor includes a simple menu for inserting certain control sets such as tables, lists, images, videos, and links, as well as text formatting controls, such as boldness, highlighting, and font.

Modifying the HTML Content

Clicking on the HTML (</>) button will change the the editor to HTML-mode. In this mode, you can enter your own HTML code, including references to classes that are defined in the Stylesheets module. Click the 'X' button in the right corner to close this window and save your changes.

Styles that are defined in the Stylesheets module will not be visible in the User Interface Designer view of the application. These stylesheets are only loaded during the Preview and Published versions of the application.

Note that scripts that are injected into the HTML will be stripped from the contents control.

Dynamic Content Injection

The value of calculated, and input named ranges can be injected directly into the HTML contents of the popover.

All dynamically injected variables must be entered inside double curly braces - {{ }}. To inject a variable into the contents, begin by entering double curly braces, and the system will automatically display available fields.

Single Named Ranges

When you enter double curly braces, you will see a list of Single Named Ranges (SNR). Selecting one of these from the list will populate the name of the named range in the contents.

Several formatting options are available when injecting the value of a Single Named Range (SNR). To use any of the formatting options, simply type in a colon character (:) after the name to see a list of supported data types. If you don't apply any formatting, the name will be injected as an unformatted value.

The data types (Integer, Decimal, DateTime, or Text) are necessary to determine the format of the field. The system will automatically format the value of the Single Named Range (SNR) when you select a data type. The text data type will get the formatted value directly from the calculation engine. Text data type also has an optional paramater (None) for formatting that has no effect on the output.

Upon selecting the data type, add a semicolon character (;) to begin defining the desired format for the output value. The .NET formatting standards apply to this property as outlined below.

Below are some examples.

{{NamedRangeName:Decimal;C2}}

For NamedRangeName = 12, the formatted value will be $12.00.
For NamedRangeName = 1.2345561, the formatted value will be $1.23.
For NamedRangeName = 'ABC', the formatted value will be blank.

{{NamedRangeName:Decimal;P3}}

For NamedRangeName = 0.12, the formatted value will be 12.000%.
For NamedRangeName = 1.2345561, the formatted value will be 123.457%.
For NamedRangeName = 'ABC', the formatted value will be blank.

{{NamedRangeName:Decimal;00000}}

For NamedRangeName = 1234.5678, the formatted value will be 01235.
For NamedRangeName = 1.2345561, the formatted value will be 00001.
For NamedRangeName = 'ABC', the formatted value will be blank.

Predefined Formats

You can also use a predefined Numeric, or Date and Time Formatting as outlined below.

Integer (Input value: 1234)

{{ValueInteger:Integer;00}} => 1234
{{ValueInteger:Integer;#,##0}} => 1,234
{{ValueInteger:Integer;00000}} => 01234
{{ValueInteger:Integer;##-##}} => 12-34

Decimal (Input value: 123456.78)

{{ValueDecimal:Decimal;0.0}} => 123456.8
{{ValueDecimal:Decimal;0.00}} => 123456.78
{{ValueDecimal:Decimal;#,##0.0}} => 123,456.8
{{ValueDecimal:Decimal;#,##0.00}} => 123,456.78
{{ValueDecimal:Decimal;0.##}} => 123456.78
{{ValueDecimal:Decimal;00.00}} => 123456.78
{{ValueDecimal:Decimal;0,0.00}} => 123,456.78
{{ValueDecimal:Decimal;0%}} => 12345678%
{{ValueDecimal:Decimal;0.0%}} => 12345678.0%

Datetime (Input value: 12/05/2018 11:25:07 pm)

{{NamedRangeName:Datetime;yyyy}} => 2018
{{NamedRangeName:Datetime;MM}} => 12
{{NamedRangeName:Datetime;dd}} => 05
{{NamedRangeName:Datetime;yyyy/MM/dd}} => 2018/12/05
{{NamedRangeName:Datetime;MM/dd/yyyy}} => 12/05/2018
{{NamedRangeName:Datetime;dd/MM/yyyy}} => 05/12/2018
{{NamedRangeName:Datetime;HH}} => 23
{{NamedRangeName:Datetime;mm}} => 25
{{NamedRangeName:Datetime;ss}} => 07
{{NamedRangeName:Datetime;tt}} => PM
{{NamedRangeName:Datetime;HH:mm tt}} => 23:25 PM
{{NamedRangeName:Datetime;HH:mm:ss tt}} => 23:25:07 PM

Text

{{NamedRangeName:Text;None}} : None is an optional parameter
{{NamedRangeName:Text}} : Will work the same as above

While formats are Culture invariant when making a selection from the list, the values shown will be different for the current application Culture. For example #,##0.0 format will be shown as in "Thousands Comma Delimiter, Decimal Period Delimiter" Culture, but it will be shown as # ##0,0 for the "Thousands Space Delimiter, Decimal Comma Delimiter" Culture setting. Once you make a selection, the value will be inserted in the contents will be the same for all Cultures.

Inserting Stubs Using the Stubs Button

Clicking the Stubs button on the top right of the content editor will open the Insert Stub menu where you can add document stubs with the help of a graphical user interface.

On the Insert Stub menu, you can select a named range, type, and format to automatically add the stub corresponding to your selections. If you want to use text format you can click Pull format from Excel checkbox.

After selecting the named range, type and format properties, or selecting the named range field and clicking Pull format from Excel checkbox press the Insert Stub button to insert the stub text into the content editor.

Tooltip Position

The Tooltip Position property determines where the tooltip or popover will be positioned in respect to the target input.

If Auto is selected, the tooltip or popover position will be calculated automatically based on other parameters like the position of the target input, and content of the tooltip or popover.

Trigger Calculations

If Trigger Calculations is selected, changing the value in this input control will trigger a calculation. Calculations perform a server call with all of the inputs from the user interface and populate the output controls with the values from the updated calculation.

In workbooks with complex calculations, enabling calculations may lead to delays in the user experience.

The best practice when determining whether an input should trigger calculations should take into account the following factors:

Does this input affect any calculated values? If the field is simply informational, then there is no reason for that control to trigger calculations. If there are no formulas or other controls that are dependent on this control, the Trigger Calculations will be disabled by default, but you can enable it anyways if you'd like.
Does this input affect my user interface? If the field can change the visibility or enabled-ness of pages or other controls, then it is a good idea to trigger calculations when changes occur to the input.
Will something else trigger calculations before this input is relevant? If the user won't see the results of the calculations until reaching a different page, then you can hold off on triggering calculations until a button press or a different control's value is changed.

Text Mask

The Text Mask property defines the format of the input's entered values. The following formats are supported:

None: A standard textbox input allowing for free-form string values.
Decimal: A numeric textbox input allowing for decimal values.
Integer: A numeric textbox input allowing for integer values.
Percentage: A numeric textbox input allowing for percentage values. The percentage will be displayed in the textbox with a percentage sign (%) but will be sent as a decimal to the calculation engine (e.g. 50 % => 0.5).
Currency ($): A numeric textbox input allowing for USD currency values.
Currency (€): A numeric textbox input allowing for EUR currency values.
Currency (£): A numeric textbox input allowing for GBP currency values.
Time: A textbox input allowing for time values to be entered. In many cases, the Calendar control is a better option for time-based inputs.
Date: A textbox input allowing for date values to be entered. In many cases, the Calendar control is a better option for date-based inputs. This is oriented towards United States formatting, which includes the month first, followed by the day (i.e. MM/DD).
Masked: You can use "Masked" type for entering password style inputs. Saved values and calculations will still use entered value.
Telephone: For phone number inputs. The default phone number mask is "+111 (1111) 111111 1111111". You can navigate to the next number bracket using the space key.
Custom: You can enter a custom text mask for the control. See Custom Mask section for available options.

Enable Thousand Separator property adds comma separators for input numbers. This option only becomes available when you select a numeric Text Mask option such as Decimal, Integer, Percentage, and Currency.

Custom Mask

This property will only be displayed when you select Custom from the Text Mask property.

The table below defines special characters that can be used in custom text mask.

Character	Meaning
a	Alphabetical
9	Numeric
*	Alphanumeric
[]	Characters between brackets means optional mask

Below is a list of characters allowed for this property.

Character	Name	Character	Name
a-z	Lowercase letters a to z	A-Z	Capital letters A to Z
0-9	Numbers 0 to 9		White-space
*	Asterisk sign	+	Plus sign
,	Comma sign	-	Minus sign
.	Period	/	Solidus
[	Left bracket	]	Right bracket
(	Left parenthesis	)	Right parenthesis
:	Colon

The table below contains custom formatting examples.

Mask	Output
(999) 999-9999	(123) 456 7890
(99) 9999[9]-9999	(12) 12345-1234 or (12) 1234-1234 . One numeric character is optional ([9]).
[9-]AAA-999	License plate format. One character as numeric is optional, three characters required as alphanumeric, three characters required as numeric.
9[9][9][9].9[9][9][9].9[9][9][9].9[9][9][9]	IP address. One character is required for all sections, three of them are optional.
99/99/9999	Date format.
9999 9999 9999 9999	Credit card format.

Minimum Length

The minimum number of characters that can be entered for validation purposes. This property is only relevant for free-form text entry (i.e. for textboxes where the mask is set to None).

Maximum Length

The maximum number of characters that can be entered for validation purposes. This property is only relevant for free-form text entry (i.e. for textboxes where the mask is set to None).

Minimum Value

The minimum value that can be entered into the textbox for validation purposes. This property is only relevant for numeric text entry (i.e. for textboxes where the mask is set to Decimal, Integer, Percentage, Currency, or Date).

Maximum Value

The maximum value that can be entered into the textbox for validation purposes. This property is only relevant for numeric text entry (i.e. for textboxes where the mask is set to Decimal, Integer, Percentage, Currency, or Date).

Precision

The Precision setting determines the number of decimal places that an input value can have for validation purposes. This property is only relevant for numeric inputs allowing decimals (i.e. for textboxes where the mask is set to Decimal, Percentage or Currency).

When you set a Currency mask for a textbox with no Precision setting defined, the system will set the default Precision to "2".

If you don't want any fractional part of the numeric value to be shown, you can set the Precision setting to "0". Setting no Precision (not "0", but empty) will allow you to store numbers containing any number of digits after the decimal separator, depending on user input or calculations.

Validation Trigger

The Validation Trigger selection will indicate the events that will cause the validation rules to be processed against the control. Validation constitutes any of the other validation options, such as Required and Minimum/Maximum Length. If validation fails (e.g. input is required but no entry exists), then the request calculation will be skipped.

You can select multiple events to trigger validation. The following triggers are available:

After Change - As soon as the value in the control is changed.
Before Calculate - Before any calculation event is triggered. This could include navigation or button clicks, as well as any other control triggering calculations. It has the ability to cancel the calculation action when failed.
Before Navigate - Before any navigation event is triggered. This could include navigation via user clicking a page in the navigation bar or a button-trigger navigation action. It has the ability to cancel the subsequent action when failed.
Before Save - Only before a save action is triggered. It has the ability to cancel the subsequent action when failed.

Required

Indicates whether the textbox field is required during validation.

This can be configured as Always or Never to indicate whether the input is statically required or not.

Alternatively, if any Boolean Single Named Ranges (SNR) exist (i.e. ranges pointing to a single cell that evaluates to TRUE or FALSE), then the required-ness of the input can be configured to reflect the value of that named range using the 'By Value Of' setting.

Enabled

Indicates whether the textbox field is enabled.

This can be configured as Always or Never to indicate whether the input is statically enabled or not.

Alternatively, if any Boolean Single Named Ranges (SNR) exist (i.e. ranges pointing to a single cell that evaluates to TRUE or FALSE), then the enabled-ness of the input can be configured to reflect the value of that named range using the 'By Value Of' setting.

Visible

Indicates whether the textbox field is visible.

This can be configured as Always or Never to indicate whether the input is statically visible or not.

Alternatively, if any Boolean Single Named Ranges (SNR) exist (i.e. ranges pointing to a single cell that evaluates to TRUE or FALSE), then the visibility of the input can be configured to reflect the value of that named range using the 'By Value Of' setting.

Textboxes

Table of Contents