AX1166

RadioButton calc method variable

RadioButton calc method variables prompt users to select a value from two or more radio buttons. There are three ways to define the list of values to be displayed as radio buttons. These are the same three options supported by ComboBox variables:

ComboBox data source
Table column
Axiom query

The RadioButton variable should only be used for small lists of values. Large lists are difficult for users to read in radio button format, and take up too much space in the Calc Method Variables dialog. If the list is too large to display effectively in radio button format, then you should use a different variable type, such as StringList, Grid, or ComboBox.

Unlike ComboBox variables, RadioButton variables do not support use of associated RelatedColumnValue variables. This is because the kind of data displayed as radio buttons typically does not have related column values that need to be brought into the spreadsheet. Although ComboBox variables and RadioButton variables use the same data options, the kind of data they use is very different.

Variable behavior

The variable displays as a vertical list of radio buttons. The user can select one of the radio buttons to use that value. The following example shows three different radio button variables.

Desktop Client: Example RadioButton variables

Web Client: Example RadioButton variables

If the variable is not required, the user can select (No Selection). This means that the selected value for the variable will be blank. The (No Selection) option is automatically added to the top of optional variables; you do not need to manually add this value to your list of values.

If the variable is required, then the user must select one of the radio buttons. The (No Selection) option is not available.

The radio button values are presented in the following order, depending on the source data:

ComboBox data source: Values are presented in the same order as the data source.
Table column: Values are sorted based on the display format if defined, otherwise based on the value column.
Axiom query: Values are sorted according to the Axiom query Data Sort setting.

Variable properties

This section explains how to complete a variable row in the CalcMethodVariables data source when defining a RadioButton 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 RadioButton variable types. For more information on the CalcMethodVariables data source in general, see Defining calc method variables using a CalcMethodVariables data source.

General variable properties

All calc method 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 RadioButton 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 `RadioButton` to allow the user to select a value from two or more radio buttons.
[RelativeLocation]	The location to place the variable value when the calc method is inserted, relative within the calc method. The location is specified as follows: `<ColumnLetter><CalcMethodRow>`. For example: If the value should be placed in column B of the calc method, within the first row of the calc method, enter the following: `B1`. If the calc method is a single-row calc method, the calc method row is always 1. If the value should be placed in column B of the calc method, but within the third row of the calc method, enter the following: `B3`. The entry for the calc method row must be valid within the context of the current calc method. For example, if the current calc method is a three-row calc method, then the only valid entries for the row are 1, 2, and 3. If you attempt to specify B4 for the three-row calc method, the entry is invalid.
[IsEnabled]	Specifies whether the variable is enabled (True/False). If `True`, then the variable will be included in the Calc Method Variables dialog. If blank or `False`, then the variable will not be included in the Calc Method Variables dialog. This evaluation is determined when the Calc Method Variables dialog is opened. If the variable is flagged as dependent using the `[DependsOn]` column, and the current context is a spreadsheet file in the Desktop Client, then the evaluation will be performed again after a value has been selected for the parent variable.
[SelectedValue]	For calc method variables, the `[SelectedValue]` column is only used for dependent variables. When the calc method is inserted and the user selects a value for the parent variable, the selected value is written back to this field temporarily, in the background. This means you can write formulas that change something about the dependent variable based on the selected value of the parent variable. For more information, see Using dependent calc method variables. This field cannot be used to set a default value for the variable. Calc method variables do not support the ability to define a default value.
[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 insert the calc method. If blank or `False`, then the user can leave the variable blank. The calc method 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 calc method variables.
[InsertOnly]	Specifies when the variable should be displayed: If `True`, then the variable is only displayed when a user inserts the calc method. It is excluded from the dialog during all other operations, including change (overwrite) and double-click. If all variables for the calc method are set to Insert Only, then the dialog only displays when inserting. If blank or `False`, then the variable is displayed in all cases.

The remaining columns depend on whether you are using a ComboBox data source, a table column, or an Axiom query. Because RadioButton variables use small lists of values, the most common way to define the list of values is to use a ComboBox data source. If you use a table column or an Axiom query to define the list of values, you must ensure that the returned list of values is small.

Variable-specific properties (ComboBox data source)

The following additional properties apply to RadioButton variable types, when using a ComboBox data source:

Column Tag Description

Column Tag	Description
[DataSourceName]	The name of the ComboBox data source to provide the list of values for the variable. You must define a ComboBox data source within the file in order to use this option. The name of the data source is defined within the ComboBox tag. For example, if the tag is `[ComboBox;MyName]`, then you would enter `MyName` as the data source name. The ComboBox data source has two property columns: `[Label]` and `[Value]`. The labels define the list of values that display to users. When a user selects a label, the corresponding value is placed in the calc method location. For more information, see Creating a ComboBox data source for the variable.
[AutoQuoteString]	Optional. Specifies whether the string value is placed in single quotation marks when it is written to the calc method location (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'`. This option is not commonly used in calc method variables. NOTE: The values in the ComboBox data source are always considered to be strings and will be quoted if this option is enabled.

[DataSourceName]

The name of the ComboBox data source to provide the list of values for the variable. You must define a ComboBox data source within the file in order to use this option.

The name of the data source is defined within the ComboBox tag. For example, if the tag is [ComboBox;MyName], then you would enter MyName as the data source name.

The ComboBox data source has two property columns: [Label] and [Value]. The labels define the list of values that display to users. When a user selects a label, the corresponding value is placed in the calc method location.

For more information, see Creating a ComboBox data source for the variable.

[AutoQuoteString]

Optional. Specifies whether the string value is placed in single quotation marks when it is written to the calc method location (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'. This option is not commonly used in calc method variables.

NOTE: The values in the ComboBox data source are always considered to be strings and will be quoted if this option is enabled.

The following properties do not apply to RadioButton variables when using a ComboBox data source: PlaceHolderText, ListChoices, ColumnName, AdditionalColumns, ColumnFilter, AllowMultiSelect, DisplayFormat, Hierarchies, MinDate, MaxDate, TooltipColumn, PrimaryTable, LimitColumn, MinValue, MaxValue, StepFrequency.

Variable-specific properties (table column)

The following additional properties apply to RadioButton variable types, when using a table column:

Column Tag	Description
[ColumnName]	The column to provide the list of values for the variable. Enter a fully-qualified Table.Column name such as `Acct.Acct`. Multi-level lookups can be used. You can specify any column from any client table in your system. System tables such as Axiom.Aliases are not supported for use with refresh variables and cannot be used. When using columns with lookups (including multi-level lookups), the final lookup table is considered the primary table. For example, if you specify `GL2020.Dept`, this is the same as specifying `GL2020.Dept.Dept`, so the Dept table is the primary table. Any columns listed in filters and as additional columns must be resolvable from the primary table, or must contain a fully qualified path from the starting table (GL2020 in this example). When using columns with lookups, the starting table impacts the list of items to be returned from the value column. For example, `GL2020.Dept` returns only the departments used in the GL2020 table, whereas `Dept.Dept` returns the full list of departments defined in the Dept table. If the value column is a key column or a validated column, then the corresponding descriptions automatically display with the column values in the drop-down list, unless a display format is defined.
[ColumnFilter]	Optional. A filter criteria statement to limit the list of values displayed to the user. You can type in the filter statement manually, or right-click the cell and use Axiom Wizards > Filter Wizard. If the value column uses a lookup, then the column in the filter criteria statement must be resolvable from the primary table, or must use a fully qualified path from the starting table.
[DisplayFormat]	Optional. Defines a display format for the items in the list, and specifies additional columns to display. By default, items in the list are displayed as: KeyColumn - DescriptionColumn If you want to specify a different format and/or use additional columns, then you can indicate the display format here. Use fully qualified Table.Column syntax and place column references in curly brackets. For example, you could indicate something like: {Acct.Acct} - {Acct.Description} ({Acct.Category}) This would display account items in the following format: 8000 - Facilities (Overhead) Any columns listed should use fully qualified Table.Column syntax. If the value column uses a lookup, then any additional columns must be resolvable from the primary table, or must use a fully qualified path from the starting table. If a display format is defined, the items in the list are sorted based on the display format instead of the value column.
[AutoQuoteString]	Optional. Specifies whether the string value is placed in single quotation marks when it is written to the calc method location (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'`. This option is not commonly used in calc method variables. NOTE: This option only applies if the value column is a string column.

The following properties do not apply to ComboBox variables when using a table column: PlaceHolderText, ListChoices, AdditionalColumns, ColumnFilter, AllowMultiSelect, DataSourceName, DisplayFormat, Hierarchies, MinDate, MaxDate, TooltipColumn, AutoQuoteString, PrimaryTable, LimitColumn, MinValue, MaxValue, StepFrequency.

Variable-specific properties (Axiom query)

The following additional properties apply to RadioButton variable types, when using an Axiom query:

Column Tag	Description
[DataSourceName]	The name of the Axiom query to provide the list of values for the variable. The sheet where the query is defined must also be specified, for example: `Sheet2!AQList` For more information on how to set up this query for use with a calc method variable, see Setting up an Axiom query for the variable.
[ColumnFilter]	Optional. A filter criteria statement to limit the list of values displayed to the user. You can type in the filter statement manually, or right-click the cell and use Axiom Wizards > Filter Wizard. This property can be used in addition to (or instead of) the Data Filter on the Axiom query itself.
[DisplayFormat]	Optional. Defines a display format for the items in the list, and specifies additional columns to display. By default, items in the list are displayed as: KeyColumn - DescriptionColumn If you want to specify a different format and/or use additional columns, then you can indicate the display format here. Use fully qualified Table.Column syntax and place column references in curly brackets. For example, you could indicate something like: {Acct.Acct} - {Acct.Description} ({Acct.Category}) This would display account items in the following format: 8000 - Facilities (Overhead) Any additional columns included here must also be in the field definition of the Axiom query.
[AutoQuoteString]	Optional. Specifies whether the string value is placed in single quotation marks when it is written to the calc method location (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'`. This option is not commonly used in calc method variables. NOTE: This option only applies if the value column of the Axiom query (the first column in the field definition) is a string column.

The following properties do not apply to Radio Button variables when using an Axiom query: PlaceHolderText, ListChoices, ColumnName, AdditionalColumns, AllowMultiSelect, Hierarchies, MinDate, MaxDate, TooltipColumn, PrimaryTable, LimitColumn, MinValue, MaxValue, StepFrequency.

Example data source

The following screenshot shows examples of RadioButton variables, one of each type (data source, Axiom query, and column value).

Creating a ComboBox data source for the variable

If you are defining calc method variables for use in a form-enabled file, then you can use the data source wizard to add the ComboBox data source. Right-click in the cell where you want to start the data source, then select Create Axiom Form Data Source > Combo Box.

If you are defining calc method variables for use in a spreadsheet Axiom file, then you must manually create the data source.

The tags for the Combo Box data source are as follows:

Primary tag

[ComboBox;DataSourceName]

The DataSourceName identifies this data source. Data source names must be unique within a file and must start with a letter. Names can only contain letters, numbers, and underscores. Names are validated when the file is saved; an invalid name will prevent the save.

The placement of this primary tag defines the control column and the control row for the data source.

All column tags must be placed in this row, to the right of the tag.
All row tags must be placed in this column, below the tag.

Row tags

[ComboItem]: Each row flagged with this tag defines an item to display in the combo box.

Column tags

[Label]

The display name for each item in the list. Labels should be unique. If multiple rows have the same label, then the first value with that label is used.

[Value]

The corresponding value for each label. This can be the same value as the label, or a different value.

For example, in a list of colors, both the label and the value can be the text Blue. Or, the label text can be Blue while the value is a numeric color code. Separating the label from the value allows you to display "friendly" text to end users but use any value as the selected value.

NOTES:

The primary tag must be placed in the first 500 rows of the sheet.
Formulas can be used to create the tags, as long as the initial bracket and identifying keyword are whole within the formula. For more information, see Using formulas with Axiom feature tags.

The following example shows how a ComboBox data source might look in a file:

In this example, if the user selects the radio button labeled "Consolidated", then the value "All" will be placed in the [SelectedValue] column.

Setting up an Axiom query for the variable

When the RadioButton variable is rendered in the Calc Method Variables dialog, the specified Axiom query is run in memory only (meaning, no values are populated within the sheet where the query is configured). The results of the query are used to generate the list of radio buttons.

The Axiom query should be set up as follows:

The first column in the field definition is the value column for the variable—meaning the values to be placed in the calc method location. If the value column is a key column, then the second column in the field definition is the description column for the key values.
The field definition of the query must also contain any additional columns used in the [DisplayFormat] property. These columns must be placed after the key and description columns. All columns in the field definition must be contiguous (no blank cells in between).
It is recommended to use fully qualified Table.Column names in the field definition for the Axiom query. If you define a display format for the variable, the display format must use fully qualified columns, and they must match the field definition entries exactly.
The Axiom query data filter can be used to filter the list of values. If desired, you can also (or alternatively) use the [ColumnFilter] property of the CalcMethodVariables data source.
All refresh behavior options for the Axiom query should be set to Off (such as Refresh on file open, Refresh on manual refresh, etc.), unless you also want the query to run at those times for reasons other than the refresh variable.
No Axiom query settings that impact the display in the sheet will apply to the variable. This includes spreadsheet sorting (use data sort instead), in-sheet calc method formatting or formulas, and data range filters. The only Axiom query settings read from the sheet are the field definition entries. One way to think of it is that the values for the drop-down list are basically the same values that you see when using the Preview Axiom Query Data button on the Sheet Assistant.