AX1143
You can use the Select content tag within a Grid data source to allow users to select an item from a column in a table.
The list of items displays as a combo box, allowing selection from a drop-down list and/or typing into the box to find a specific value. Only the first 100 items display in the drop-down list, but all items can be selected by typing to search. The Select tag has no effect within the source file itself, but when the file is viewed as an Axiom form, the cell containing the Select tag will render as the combo box.
Content tag syntax for table column drop-down lists
The syntax for the Select content tag is as follows:
[Select; TargetCell=CellAddress; FormState=KeyName; SharedVariable=VariableName; DisplayCell=CellAddress; ValueColumn=ColumnName; DescriptionColumn=ColumnName; SortColumn=ColumnName; DisplayFormat=Text; Searchable=True/False; Placeholder=Message; MultiSelect=True/False; Filter=FilterStatement; ReadOnly=True/False; AutoSubmit=Enabled/Disabled/Grid; Tooltip=Text; ColumnStyle=StyleName; Columns=Number;]
Parameters can be listed in any order after the Select tag. Optional parameters can be omitted.
(missing or bad snippet)When using the Data Source Wizard / Tag Editor, you must specify the List Items Source as Table in order to configure the tag to use a table column. This selection is used to show the correct parameters for this configuration.
| Parameter | Description |
|---|---|
TargetCell | The cell to place the selected value. You can specify the cell using one of the following options: (missing or bad snippet)The target cell cannot be the same cell that contains the Select tag. The target cell can be anywhere in the spreadsheet and does not need to be visible within the formatted grid. If there is content in the target cell, that content will be displayed as the selected value for the combo box (unless a DisplayCell is specified). If you want to display a previously selected value that was saved to the database (such as when the form is subsequently opened and a value is queried back in), then you can use a formula in the target cell to bring in this value. (missing or bad snippet) |
FormState | (missing or bad snippet) |
| SharedVariable | (missing or bad snippet) |
ValueColumn | (missing or bad snippet)(missing or bad snippet) |
DescriptionColumn | (missing or bad snippet) |
Filter | (missing or bad snippet) |
SortColumn | (missing or bad snippet) |
DisplayCell | (missing or bad snippet) |
DisplayFormat | (missing or bad snippet)(missing or bad snippet) Additional columns included in the display format are searchable within the list. |
AutoSubmit | (missing or bad snippet) |
Placeholder | (missing or bad snippet) |
| Tooltip | (missing or bad snippet) |
ReadOnly | (missing or bad snippet) |
Searchable | Optional. Specifies whether the list is searchable (True/False). By default, this is True, which means the list is searchable by typing values into the combo box. If you want the list to be a static drop-down list instead, indicate False. If the list has more than 100 items, then the list must be searchable or else users will not be able to select all items in the list. Only the first 100 items are displayed in the drop-down list, but all items can be found by searching. NOTE: If MultiSelect is True, then this parameter does not apply. The dialog box where users can select multiple values always has a search box to filter the list. It is recommended to disable this parameter so that users cannot attempt to type inside the combo box (which will just cause the multi-select dialog to open). |
MultiSelect | Optional. Specifies whether users can select multiple values in the list (True/False). By default this is False, which means that users can only select a single value. If True, then users can select multiple values in the list. When the user clicks on the combo box, a dialog opens instead of a drop-down list. The user can select check boxes for the values they want to select. When the user clicks OK to close the dialog, the selected items are written back to the target cell using a comma-separated list. If the items are from a string column, they are automatically wrapped in single quotation marks so that they can be used in a filter using an IN operator. The combo box in the form displays the same list, unless a display format cell is being used to change the display. For more information on how users interact with the multi-select dialog, see Multi-select dialog behavior. NOTE: If multi-select is enabled, it is recommended to define placeholder text because that text will display as the title of the multi-select dialog. |
Columns | (missing or bad snippet) |
ColumnStyle | (missing or bad snippet) |
Tag examples
[Select; TargetCell=K; ValueColumn=Acct.Acct; Searchable=False; Placeholder=Select Account; Filter=Acct.Category='Revenue']
This example allows the user to select from a list of revenue accounts. The cell will display the text "Select Account" until an account is selected. The selected value will be placed in column K on the current row (for example if the tag is defined on row 24, then the target cell is K24). The optional Searchable parameter is set to False, so users will not be able to filter this list. There are probably only a handful of revenue accounts so a static drop-down list is appropriate.
[Select; FormState=Location; ValueColumn=Loc.Loc]
This example allows the user to select from a list of defined locations. The selected location will be stored in form state memory for the Axiom form, under the key name Location. When the Axiom form is used as a dialog or a task pane, this location value can be passed to the currently active spreadsheet file.
[Select; SharedVariable=Location; ValueColumn=Loc.Loc]
This example is the same as the previous example, except that it is using a shared variable instead of form state. The selected location will be stored in the list of variables for the shared form instance, as the value for the variable Location. For example, you might do this so that the user can select a location in a parent form, and then that location can be referenced in child forms displayed using the Embedded Form component.
[Select; TargetCell=K; DisplayCell=L; ValueColumn=Acct.Acct; DescriptionColumn=Acct.FullDescription; Placeholder=Select Account]
In this example, the selection will be placed in column K within the current row. Additionally, the display cell parameter is used so that when a user selects an account from the list, the Select cell will display the contents of cell L24 instead of the account code placed in K24. The DescriptionColumn parameter is used to explicitly indicate a description column (perhaps in this case the table has two description columns).
[Select; TargetCell=B10; ValueColumn=Dept.Dept; DisplayFormat={Dept.Dept} ({Dept.Description}) - {Dept.Company}; Placeholder=Select Department]
In this example, a specific cell is indicated as the target cell instead of assuming the current row. The DisplayFormat parameter is used to define an alternate display for the items in the list. The additional column listed in the display format is also searchable.
[Select; TargetCell=K; ValueColumn=Acct.Acct; Placeholder=Select Account; Columns=2; ColumnStyle=center]
In this example, the Columns parameter is used to span the combo box across two columns, and the ColumnStyle parameter is used to apply the center style to this cell, regardless of which style is currently being applied to the column.
[Select; TargetCell=K; ValueColumn=Dept.Dept; Placeholder=Select Departments; MultiSelect=True]
In this example, the MultiSelect parameter is used to enable selection of multiple values. Values are displayed in a dialog so that the user can select multiple values using check boxes. The search box at the top can be used to filter the list and search for specific values.
Displaying starting values in the Select cell
The Placeholder parameter can be used to display text such as "Select a department" when no item has been selected yet. However, once the user has selected an item, and that item has been saved to the database, you likely want that item to be displayed in the cell the next time the file has opened. You can do this as follows:
- Use a formula in the target cell that returns the saved item in the database if applicable, otherwise the cell is blank.
- If the target cell contains a value, that value is displayed in the cell with the drop-down list. If the target cell does not yet contain a value, then the placeholder text is used.
- If the user selects a new value from the list, that value will overwrite the formula in the target cell. When the save-to-database is performed, that new value will replace the old value in the database. However, because the file itself is not saved, the formula is preserved the next time the file is opened, and it will now return the new value in the database.
If you are using a display cell as well, then that cell should also use a formula so that it displays the desired value when the target cell contains a value, otherwise it returns blank (so that the Placeholder text can be used).
This discussion does not apply when using form state or a shared variable. In that case, you can use either the GetFormState function or the GetSharedVariable function to set a starting value, which will then display as the selected value for the list. The functions can be located anywhere in the file.
(missing or bad snippet)