AX1045
You can configure cells in a Grid data source to behave as text boxes, so that the user can enter or edit text that gets submitted back to the form source file. There are two ways to do this:
-
You can configure a cell in the Grid data source as unlocked. For more information on this option, see Interactivity options for Formatted Grids.
-
You can use the TextArea content tag for formatted grids to configure a cell in the Grid data source as a text box. The TextArea tag has no effect within the source file itself, but when the file is viewed as an Axiom form, the cell containing the TextArea tag will render as a text box. This topic discusses how to use the TextArea tag.
The TextArea tag is the preferred approach in many cases, because it provides additional options to control the display and behavior of the editable cell. Generally speaking, simple unlocked cells should only be used for very basic edits where the additional options are not needed—for example, if you are displaying a grid of numbers in a report-style format, but users also need the option to edit the numbers.
Content tag syntax for text boxes
The syntax for the TextArea content tag is as follows:
[TextArea; TargetCell=CellAddress; FormState=KeyName; SharedVariable=VariableName; Placeholder=Text; MaxLength=Number; ReadOnly=True/False; Kind=KindName; MultiLine=True/False; RichTextEditor=True/False; ShowToolBar=True/False; ToolBarOptions=Code; Mask=Format; PreserveMask=True/False; MinRange=Number; MaxRange=Number; AutoSubmit=Enabled/Disabled/Grid; Tooltip=Text; Columns=Number; ColumnStyle=StyleName;]
Parameters can be listed in any order after the TextArea tag. Optional parameters can be omitted.
To create the tag, you can manually type it within a cell, or you can use the Data Source Assistant / Tag Editor. For more information, see Creating and editing content tags in Formatted Grids.
| Parameter | Description |
|---|---|
|
TargetCell |
The cell to place the user input. You can specify the cell using one of the following options:
For more information, see Referencing cells in content tag parameters. The target cell cannot be the same cell that contains the TextArea tag. The target cell can be anywhere in the spreadsheet and does not need to be visible within the formatted grid. NOTES:
|
|
FormState |
The key name for the text input to be stored in form state memory. For example, Description. When a form state key name is defined, the user's text input is not placed anywhere in the source file. Instead, it is stored in form state memory for the current file. If you need to reference the value within the form, you can use the GetFormState function to return the value into a cell. The FormState parameter should only be used if the form is intended to be used as a dialog in the Excel Client or the Windows Client, and you need to be able to pass values from the form to the currently active spreadsheet. For more information, see Passing values between an Axiom form and the active client spreadsheet (form state). |
| SharedVariable |
The shared variable name to save the selected value as. For example, Description. When a variable name is defined, the user's text input is not placed anywhere in the source file. Instead, it is saved to the variable list that is stored in memory for the shared form instance. If you need to reference the value within the form, you can use the GetSharedVariable function to return the value into a cell. The SharedVariable parameter should only be used if the form is intended to be used in a embedded form context (as either the parent form or a child form), and you need to share this value with other forms in the shared form instance. For more information, see Sharing variables between parent and child forms. |
|
AutoSubmit |
Optional. Specifies how interactive controls submit values back to the source file:
If omitted, the default behavior is Grid. NOTE: For TextArea tags, this parameter is ignored if Use Lightweight Auto Submit has been enabled for the grid. |
|
Placeholder |
Optional. A message to display within the cell when no user input has yet been entered. This applies when the target cell does not have any contents, or when the form state key or shared variable does not currently have an assigned value. For example: "Enter a comment." Once the user has input text, the contents of the target cell (or the stored form state / shared variable value) display instead of the placeholder text. You can define the placeholder text within the tag directly, or you can use a bracketed cell reference to read the placeholder text from another cell. For more information, see Referencing cells in content tag parameters. NOTE: The appearance of the placeholder text depends on the skin assigned to the form, and on the browser used to view the form. In most environments the placeholder text displays in a lighter color than text values, but not always. |
| Tooltip |
Optional. Specifies tooltip text to display when a user hovers the cursor over the cell contents. Alternatively, you can use a bracketed cell reference to read the tooltip text from the referenced cell. This approach is useful if you want to dynamically determine the text, because then the formula can be in the referenced cell instead needing to construct the tag using a formula. For more information, see Referencing cells in content tag parameters. |
|
MaxLength |
Optional. The maximum length, in characters, of the text input. Note that not all browsers will enforce this limit. |
|
ReadOnly |
Optional. Specifies whether the input cell is "active" (True/False). The default value, False, means that the cell is active and that the user can input text as needed. If True, then the cell becomes "frozen" and no further edits can be made. The cell will display the current value of the text box. This parameter can be used to control whether a user can edit the cell's value. Generally speaking, this parameter would only be used within a formula to dynamically enable / disable the text box. |
|
Kind |
Optional. Specify a kind for the text box:
NOTE: When using the Data Source Assistant / Tag Editor, this option displays using the label Type. |
|
Columns |
Optional. Specifies how many columns the text box will span in the grid. If this parameter is omitted or set to 1, then content generated by the tag will only span the current column. If you want the content to span multiple columns, enter a number such as 2 to span 2 columns. The column span extends to the right. NOTE: The row and column styles impact how the column span displays in the rendered grid. For example, if the content in the starting column is left-aligned and does not naturally exceed the width of the starting column, then the spanned columns will simply be blank because no content is extending to those columns. However, if the content is long enough to extend out of the starting column, or if the content is center-aligned or right-aligned, then content will display in the spanned columns. |
|
ColumnStyle |
Optional. Specifies one or more column styles to apply to the current cell. The specified styles override the current column styles set by the Enter one or more valid column style names, separated by commas. If you are using the Data Source Assistant / Tag Editor, you can click the [...] button to open the Choose Styles dialog and select from available styles. The available styles depend on the skin specified for the form. For more information, see Using row and column styles with Formatted Grids. Alternatively, you can use a bracketed cell reference to read the style from the referenced cell. This approach is useful if you want to dynamically determine the style, because then the formula can be in the referenced cell instead needing to construct the tag using a formula. For more information, see Referencing cells in content tag parameters. |
The following parameters only apply if the Kind parameter is set to Text.
| Parameter | Description |
|---|---|
|
MultiLine |
Optional. Specifies whether the text input supports multi-line input (True/False). By default, this is True. If False, then wrapped text will not be enabled for the input cell or the target cell. If RichTextEditor is enabled for the text box, then the MultiLine parameter does not apply. Rich text boxes always support multi-line input. |
|
RichTextEditor |
Optional. Specifies whether the text box supports rich text (True/False). By default this is False, which means that text entered into the text box is plain text. If True, then users can apply limited formatting to the text, such as bold or italics. This can be done by using the formatting toolbar, or by using standard shortcut keys (such as CTRL+B for bold). The text written back to the target cell uses HTML tags to indicate the formatted elements. This works the same way as the separate Text Box component with rich text enabled. For an example, see Rich text box behavior. NOTES:
|
|
ShowToolBar |
Optional. Specifies whether the formatting toolbar displays on the text box (True/False). Only applies if RichTextEditor is True. By default this is False, which means that the text box displays as a bordered box, with no toolbar. In this case, users must use shortcut keys to format the text. If True, then the text box displays in a framed box, with a toolbar at the top to apply formatting. You can specify which formatting options display on the toolbar. The appearance is the same as the separate Text Box component with rich text enabled. For an example, see Rich text box behavior. |
|
ToolbarOptions |
Optional. Specifies which formatting options display on the toolbar, when the toolbar is enabled. By default, the toolbar contains font formatting options. It is only necessary to configure this parameter if you want the toolbar to display different options. The ToolbarOptions parameter resolves to a code that tells Axiom Software which options to display. It is recommended to always use the Tag Editor or Data Source Assistant to configure the options, to ensure that a valid code is used. To configure the options, click the [...] button and then select the check boxes for the desired options:
|
The following parameters only apply if the Kind parameter is set to InputMask.
| Parameter | Description |
|---|---|
|
Mask |
Defines the input mask format for the text box. For example, you might enter The input mask format uses the same rules as the separate Text Box component. For more information, see Defining the input mask format. NOTE: When using the Data Source Assistant / Tag Editor, this option displays using the label Format. |
|
PreserveMask |
Optional. Specifies whether the text submitted back to the source file includes the input mask format or not. By default this is False, which means that the user input is written back as raw text, without any formatting. If True, then the user input is written back using the same format as it is displayed to the end user. 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. |
The following parameters only apply if the Kind parameter is set to Numeric.
| Parameter | Description |
|---|---|
|
MinRange |
Optional. The minimum number that can be entered into the text box, to restrict the user input to a specified numeric range. By default, this parameter is omitted, which means there is no minimum value. Specify 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 will display on the right side of the text box. Additionally, the tooltip will display a validation message, such as "The value must be greater than or equal to 1." |
| MaxRange |
Optional. The maximum number that can be entered into the text box, to restrict the user input to a specified numeric range. By default, this parameter is omitted, which means there is no maximum value. Specify 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 will display on the right side of the text box. Additionally, the tooltip will display a validation message, such as "The value must be less than or equal to 100." |
When using a numeric text box, the target cell should be formatted as Number, Currency, or Percentage, so that the inputted value displays in the desired numeric format. If you are using a shared variable or a form state key (and therefore there is no target cell), then you should format the cell containing the tag with the desired numeric format. This behavior is the same as when using a numeric Text Box component. For more information, see Using numeric text boxes.
Behavior notes
The cell containing the TextArea tag becomes a text box when the form is rendered. The basic appearance and behavior of the text box is the same as the separate Text Box component.
Alternatively, some themes provide a special column style that you can use to display the cell as a regular cell until the user clicks in it, at which point it will display as a text box (the click-to-edit style). This style requires the form to use the Web Client container, and does not apply if the text box is a rich text box.
It is assumed that the target cell is off to one side (not visible in the formatted grid), within a work column. If you are saving the user's input to the database, the column to save is the column containing the target cell (not the column containing the input cell).
Tag examples
[TextArea; TargetCell=K23; Kind=Text; Columns=4; Placeholder=Enter Comment]
This example allows the user to enter a comment. The input cell spans four columns wide. The cell will display the text "Enter Comment" until the user enters some text. The inputted text will be placed in cell K23.
="[TextArea; TargetCell=K; Kind=Text; Columns=4; Placeholder=Enter comment; ReadOnly="&A2&"]"
This example is similar to the first example, except:
- The target cell is indicated by just the column letter K. The user input will be placed in column K within the current row (for example, if the tag is defined on row 22, the target cell is K22).
- The ReadOnly parameter is used to toggle the input cell on or off based on the contents of cell A2. At some point in the process, A2 could be changed to True, which would prevent users from editing the existing comment.
[TextArea; TargetCell=K; Kind=Text; MultiLine=False; Placeholder=Enter Name]
In this example, the multi-line parameter is used to turn off the wrapped text for the input. Although you could simply use an unlocked normal cell for this input, using the TextArea tag provides the following benefits:
- Separate placeholder text that does not need to be entered directly in the input cell (as it would if using a normal cell).
- The ability to place the user input into a target cell.
[TextArea; FormState=Filter; Kind=Text; Placeholder=Enter a Filter]
In this example, the text input is being stored in form state memory rather than being placed in a target cell. When the Axiom form is used as a dialog, this text input can be passed to the currently active spreadsheet file. For example, the user can define a filter statement to apply to a query in the active spreadsheet file.
[TextArea; SharedVariable=Description; Kind=Text; Placeholder=Enter a Description]
In this example, the text input is being stored in memory as a shared variable rather than being placed in a target cell. For example, you might do this so that the user can define a description in a child form (displayed using the Embedded Form component), and then that description can be referenced in the parent form as well as other child forms within the shared form instance.
[TextArea; TargetCell=K; Kind=Text; MultiLine=False; ColumnStyle=col, click-to-edit]
In this example, the ColumnStyle parameter is being used to apply the special click-to-edit style to the text box. This means that the cell contents will display as a regular cell until the user clicks inside the cell, at which point the normal text box borders and styling apply.
[TextArea; TargetCell=K; Kind=InputMask; Mask=(000) 000-0000; PreserveMask=True;]
In this example, the text box uses an input mask to enforce entry of a phone number in the desired format. The input mask format is preserved so that the user input will be written to the source file using the specified format instead of as raw text.
[TextArea; TargetCell=K; Kind=Numeric; MinRange=1; MaxRange=100;]
In this example, the text box uses a numeric format and a specified number range. If the user enters a number outside of this range, say 101, then a red validation bar will display on the side of the text box and the tooltip will display a validation message.
[TextArea;TargetCell=+1;RichTextEditor=True;ShowToolBar=True;ToolBarOptions=2047;Kind=Text;]
In this example, the text box uses rich text, and additional toolbar options of alignment and lists have been enabled. If you are using the default behavior of only showing the font formatting options on the toolbar, then the ToolbarOptions parameter is omitted.
