AX1393

StringList refresh variable

StringList refresh variables prompt users to make a selection from a predefined list. This list is manually defined within the current file—either in the RefreshVariables data source itself, or in a range of cells that are then referenced in the data source.

Variable behavior

In the Desktop Client, the variable displays as a drop-down list. The user must use the drop-down to select a value.

Desktop Client: Example StringList variable

In the Web Client, the variable displays as a drop-down list with a searchable entry box. The user can scroll the list and select the value directly, or type into the box to find a particular value.

Web Client: Example StringList variable

Variable properties

This section explains how to complete a variable row in the RefreshVariables data source when defining a StringList variable. Some data source columns do not apply in this case and are not discussed here. If any inapplicable columns are present in the data source, they should be left blank on rows that define StringList variable types. If you are using the Data Source Assistant to complete the variable properties, then only the applicable columns will be shown in the task pane.

For more information on the RefreshVariables data source in general, see Defining refresh variables.

General variable properties

All refresh variables use a common set of general properties such as the variable name, display name, and whether the variable is enabled or required. Any special considerations for StringList variables are noted.

Column Tag	Description
[Name]	The name of the variable. This name identifies the variable row in the data source, and is also used as the variable display name to users if a separate display name is not defined in the `[DisplayName]` column. The name should not contain any non-alphanumeric characters such as question marks or periods. If you want the variable name that displays to users to include non-alphanumeric characters, use the display name. The name cannot be dynamic; it must remain static because it is used to identify the variable. If you are configuring a dependent variable and you need the name to change based on the selection of the parent variable, then you must make the display name dynamic instead of the name.
[DisplayName]	Optional. The display name of the variable. If defined, the display name will be used instead of the name when the variable displays to users.
[VariableType]	Specifies the variable type. Enter `StringList` to allow the user to select from a predefined list.
[IsEnabled]	Specifies whether the variable is enabled (True/False). If `True`, then the variable will be included in the refresh dialog or filter panel. If blank or `False`, then the variable will not be included in the refresh dialog or filter panel. This evaluation is determined when the refresh dialog or filter panel is opened. If the variable is flagged as dependent using the `[DependsOn]` column, then the evaluation will be performed again after a value has been selected for the parent variable.
[SelectedValue]	The user's selected value for the variable will be placed in this cell. When setting up the file to use the variable value, point your formulas to this cell. If you want to define a default value for the variable, use the `[DefaultValueonOpen]` field rather than entering the default value here.
[IsRequired]	Optional. Specifies whether the user must enter a value for this variable (True/False). If `True`, then the user must specify a value for this variable in order to perform the refresh. If blank or `False`, then the user can leave the variable blank. The file should be configured so that it works as expected if the variable is left blank. The display of required and optional variables depends on the environment. In the Desktop Client, the text (optional) follows the name of optional variables. In the Web Client, required variables that do not yet have a selected value are indicated with a red bar along the side of the variable field.
[DependsOn]	Optional. Specifies that the variable is dependent on a "parent" variable. To make a variable dependent on another variable, enter the name of the parent variable. Some variable types require a parent variable, such as RelatedColumnValue variables. Other variable types can be made dependent as needed. Dependent variables can be updated dynamically in response to the selected value for the parent variable. For more information, see Using dependent refresh variables.
[ClearSelectedValueonSave]	Optional. Specifies whether the selected value is cleared when the file is saved (True/False). If `True`, then the selected value is cleared when the file is saved. You should set this to True if you want to ensure that the variable always starts off with no value after saving. If blank or `False`, then the selected value is left as is when the file is saved. You should set this to False if you want to be able to set a "default value" for the variable, or if you want the last-selected value to be retained after saving the file.
[ClearSelectedValueonOpen]	Optional. Specifies whether the selected value is cleared when the file is opened (True/False). If `True`, then the selected value is cleared when the file is opened. You should set this to True if you want the variable to start with no value when the file is opened. If blank or `False`, then the selected value is not cleared when the file is opened. You should set this to False if you want the last-saved value to be retained when opening the file. If you enable this option and also define a default value using `[DefaultValueonOpen]`, then the current selected value is first cleared, then the default value is copied to the `[SelectedValue]` field.
[DefaultValueonOpen]	Optional. Specifies a default value to be copied to the `[SelectedValue]` field on open. When the user opens the document and uses the refresh variables, the value specified here will be the initial selected value. This allows you to define a default value without needing to place the value directly in the `[SelectedValue]` field, where it could get overwritten by user selection and inadvertently saved. NOTE: If you need to use a formula to determine the default value, the formula may not get calculated before the value is copied to the `[SelectedValue]` field. In this case you must still define the value in the `[SelectedValue]` field directly. The default value is copied regardless of whether the variable is currently enabled or not. This allows you to set a default value for dependent variables that may not be initially visible, but will be visible based on the parent variable selection. The default value must be valid in the context of the variable type and configuration. If the default value is not a value that could be entered or selected for the variable, validation errors or refresh errors may occur.
[GroupName]	Optional. Defines a group name under which the variable will display. This option only applies to refresh variables used with Axiom forms; it will be ignored when using refresh variables with spreadsheet files in the Desktop Client. If a group name is specified, then the variable will be displayed within an expandable / collapsible grouping in the Web Client filter panel (or when the form is viewed as a web tab within the Desktop Client). For more information, see Defining refresh variables for Axiom forms.
[CollapseOnOpen]	Optional. Specifies whether the group that this variable belongs to should start out collapsed when the form is opened (True/False). By default, groups start out as expanded. This option only applies to refresh variables used with Axiom forms, and only if the variable has a defined group name. The option is ignored when using refresh variables with spreadsheet files in the Desktop Client. If one variable in the group is set to True, then the group is collapsed, regardless of whether other variables in the group may be set to False (or blank).

Variable-specific properties

The following additional properties apply to StringList variable types:

Column Tag Description

Column Tag	Description
[ListChoices]	Defines the list of values for the variable. Enter one of the following: A comma-separated list of values to display in the list. For example: `Yellow, Red, Blue`. (Alternatively, semicolons can be used as the delimiter.) NOTE: This list can contain cell references in brackets. The value for the list will be read from the designated cell. For example, you can enter: `Yellow, [List!B5], Blue`. If List!B5 contains the value Red, then the list will be: Yellow, Red, Blue. If List!B5 contains a cell range, then the values within that range will be added to the list. A cell range, in brackets. For example: `[List!B10:B20]`. The list of values will be read from this range. When using a cell range, the range must be one dimensional—meaning either one column wide and several rows tall, or several columns wide and one row tall. If the range is a block, it is ignored.
[PlaceholderText]	Optional. Specifies placeholder text to display within the variable box until a value is selected. If blank, then the default text "Select..." is used. For StringList variables, this property is only supported for use in the Web Client. In the Desktop Client, the variable box is blank if no value has been selected.
[AutoQuoteString]	Optional. Specifies whether the string value is placed in single quotation marks when it is written to the `[SelectedValue]` column (True/False). If omitted or blank, the default setting is False, which means the string value is not quoted. This option is intended to make it easier to create filters based on the selected value, when the selected value is a string and therefore must be wrapped in single quotation marks. For example: `Dept.VP='Smith'`. NOTE: All values in the list are considered strings and will be quoted if this option is enabled, even if the list values are actually numbers.

[ListChoices]

Defines the list of values for the variable. Enter one of the following:

A comma-separated list of values to display in the list. For example: Yellow, Red, Blue. (Alternatively, semicolons can be used as the delimiter.)

NOTE: This list can contain cell references in brackets. The value for the list will be read from the designated cell. For example, you can enter: Yellow, [List!B5], Blue. If List!B5 contains the value Red, then the list will be: Yellow, Red, Blue. If List!B5 contains a cell range, then the values within that range will be added to the list.
A cell range, in brackets. For example: [List!B10:B20]. The list of values will be read from this range.

When using a cell range, the range must be one dimensional—meaning either one column wide and several rows tall, or several columns wide and one row tall. If the range is a block, it is ignored.

[PlaceholderText]

Optional. Specifies placeholder text to display within the variable box until a value is selected. If blank, then the default text "Select..." is used.

For StringList variables, this property is only supported for use in the Web Client. In the Desktop Client, the variable box is blank if no value has been selected.

[AutoQuoteString]

Optional. Specifies whether the string value is placed in single quotation marks when it is written to the [SelectedValue] column (True/False). If omitted or blank, the default setting is False, which means the string value is not quoted.

This option is intended to make it easier to create filters based on the selected value, when the selected value is a string and therefore must be wrapped in single quotation marks. For example: Dept.VP='Smith'.

NOTE: All values in the list are considered strings and will be quoted if this option is enabled, even if the list values are actually numbers.

The following properties do not apply to StringList variables: ColumnName, AdditionalColumns, ColumnFilter, AllowMultiSelect, DataSourceName, DisplayFormat, Hierarchies, UseAsQuickFilter, MinDate, MaxDate, TooltipColumn, PrimaryTable, LimitColumn, MinValue, MaxValue, StepFrequency.

Example data source

The following screenshot shows a couple of StringList refresh variable examples. The first example reads the list from a cell range, while the second example uses a comma-separated list.