Combo Box component for Axiom forms

The data source for the combo box, to determine the list of items in the box. A data source must be tagged within the file as specified above, and then selected for the combo box.

NOTE: In the Form Control Sheet, the selected data source is written as SheetName!DataSourceName. The sheet name is the sheet where the selected data source is located.

If a data source is already specified and you want to locate it within the file, click the Show location button to the right of the drop-down list. This will move your cursor to the associated data source tag in the file.

The text to display on the button if the Selected Value is blank.

By default, this text is "Select..." to prompt the user to select a value from the drop-down list. If you want to use different text, enter that text into this field.

Blank initial text is not supported. If this setting and the Selected Value setting are both blank, then the combo box will display "Select..."

The appearance of the initial text depends on the skin assigned to the form, and on the browser used to view the form. In most environments the initial text displays in a lighter color than selected values, but not always.

Optional. The tooltip text for the component. When a user hovers the cursor over the component, the text displays in a tooltip.

The currently selected value for the combo box. This setting serves two purposes:

• It defines the initially selected value for the combo box, when the user first opens the form. By default this setting is blank, which means that no value is selected for the combo box, and instead the combo box will display the text defined for the Initial Text setting. Alternatively you can enter a value from the Values column of the data source, and the combo box will display that value to start.

• When a user views the form and selects an item from the drop-down list, this selected value will be submitted back to the source file and placed in this cell on the Form Control Sheet. Formulas can reference this cell in order to dynamically change the form based on the currently selected value for the combo box.

NOTES:  

• This setting supports indirect cell references. You can enter a cell reference in brackets, such as [Info!B3]. This causes the selected value to be read from and written to the specified cell reference instead of directly within the Selected Value cell.

• This setting supports use of the FormState tag and the SharedVariables tag, so that the selected value is stored in memory instead of written to the file, and therefore can be shared with other files. Form state can be used to share values between a form dialog and an active client spreadsheet, in the Desktop Client. Shared variables can be used to share values between multiple forms that are open in a shared form instance (embedded forms).

Specifies whether the combo box includes the ability to type in values to search the list.

By default this is disabled, which means that the user can only select values from the list. The user cannot type in a value to find a matching value.

If enabled, then the user can click into the box to start typing text. This filters the list for matching values, which the user can then select. Typically this setting is only enabled for longer lists where it would be inconvenient for the user to have to scroll to the value, or where the total list exceeds the number of items that can be shown (in this case the user can still search to select the value).

Specifies whether the Axiom form is automatically updated when a user changes the state of the component.

By default, this is enabled, which means that the form automatically updates when the user selects an item from the combo box. If this setting is disabled, then the user must use a Button component in order to update the form for the changed state.

For example, you might disable the auto-submit behavior if the combo box is one of several user selections that are intended to be submitted together at one time, instead of piecemeal as each one changes. In that situation the user can make all necessary changes for all related components, and then click a Button component to submit the changes at once and trigger an update.

Specifies whether a save-to-database occurs when a form update is triggered by this component.

• If disabled (default), then changing this component does not trigger a save-to-database.

• If enabled, then a save-to-database will occur as part of the form update process when this component triggers an update. The save occurs after editable values have been submitted to the source file and after data has been refreshed in the source file. A save-to-database process must be enabled and configured within the source file. For more information, see Saving data from an Axiom form.

This setting only applies if Auto Submit is enabled for the component. If you are not using the auto-submit behavior but you do want to save data to the database from the Axiom form, then you should instead enable Save on Submit for the Button component that you are using to trigger the update process.

The name of the component. This is for identification in the file; this name does not display on the Axiom form canvas.

The name of the component identifies the corresponding settings for the component on the Form Control Sheet. The component names are also useful if you have multiple types of the same component within an Axiom form, so that you can tell which component you are currently editing.

Component 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.

NOTE: Spaces are not allowed in component names and will be automatically removed by Axiom Software. For example, if you enter "My Component" as the component name, it will be automatically adjusted to "MyComponent".

Specifies whether the component is visible on the Axiom form (On/Off). By default this is set to On.

This setting can be used to dynamically show or hide the component using a formula. Keep in mind that if you have multiple components that you need to dynamically show or hide based on the same condition, then it is preferable to place those components on a dedicated layer and then show or hide the entire layer instead of the individual components.

NOTE: This setting is only available on the Form Control Sheet; it cannot be set in the Form Assistant or in the Form Designer.

The layer that the component belongs to on the Axiom form canvas. In the Form Assistant and the Form Designer, this displays as the layer name (for example: Layer 1). In the Form Control Sheet, this is recorded as the layer ID (for example: 1).

If the canvas only has one layer, then the component is automatically assigned to that layer and cannot be changed. If the canvas has multiple layers, you can assign the component to any layer using the drop-down list. By default, the component will be assigned to whichever layer is selected in the Layers box when you initially drag the component onto the canvas. For more information on layers, see Using multiple layers on the canvas.

If desired, you can jump to the applicable layer settings on the Form Control Sheet by clicking the binoculars icon next to the drop-down list.

Optional. The styles used to determine the formatting of the component. You can assign one or more styles.

Click the Select component styles button [...] to open the Choose Style dialog. Using this dialog, you can select one or more styles to apply to the component. The available styles depend on the component type and the skin assigned to the form. For more information, see Using component styles.

Some components have several styles that are specifically designed for that component type, while other components may only have the "generic" styles that are available to all components. When using a generic style, keep in mind that they may not be useful for all components. You can view a description of each style and view the effective formatting applied by the selected styles within the Choose Style dialog.

The reference location determines how the x-position and y-position of a component are evaluated. By default the reference location is UpperLeft.

NOTE: This setting is not exposed in the advanced component settings. It can be changed on the canvas by double-clicking the corner selection handles of a component, or you can edit the setting on the Form Control Sheet directly.

The x-position determines the component's position along the horizontal axis, and the y-position determines the component's position along the vertical axis. Both are evaluated relative to the reference location. Positions can be set in pixels (default) or percentages.

The order in which the component is rendered in the layer. A component with a larger order number will display above a component with a smaller order number.

For components that support tab navigation (tabbing to the next editable component), the rendering order also determines the tabbing order.

NOTE: On the Form Control Sheet, this setting is labeled as Z-Index.

The column to provide the list of values for the combo box. 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-defined 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 GL2019.Dept, this is the same as specifying GL2019.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 (GL2019 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, GL2019.Dept returns only the departments used in the GL2019 table, whereas Dept.Dept returns the full list of departments defined in the Dept table.

Optional. The column that contains descriptions for the value column, specified using a fully qualified Table.Column name or an alias name. For example: Acct.Description. This property only applies if the value column is a key column or a validated column.

By default, the primary table's first description column will be displayed in the list if no alternate description column is specified in the tag. You only need to complete the DescriptionColumn parameter if the table has more than one description column and you want to specify a different description column.

However, if you are using the DisplayFormat parameter to define a custom display format, then the DescriptionColumn parameter does not apply. Instead, you should include the description column in the custom display format as desired.

Optional. The column by which to sort the list of values.

By default, the list is sorted by the display format if defined, and by the value column if no display format is defined. You can use this property to override the default sort and instead specify a different column to sort by. If the value column uses a lookup, then the column must be resolvable from the primary table, or must use a fully qualified path from the starting table.

Optional. The cell that contains content that you want to display in the combo box other than the selected value. Specify either a cell reference (A22) or a column letter (A). If only a column letter is specified, the current row is assumed.

For example, if the purpose of the combo box is to select an account, and the account list displays items as Account - Description, then you may want the selected value to also display as Account - Description instead of just Account. You could have a formula in the designated display cell that creates this alternate display based on the selected value.

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:

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:

This would display account items in the following format:

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.

Additional columns included in the display format are searchable within the list.

The name of the Axiom query to use as the source of the list. This parameter uses the following syntax: SheetName!AQName. For example: Sheet2!AQList.

The setup requirements for the Axiom query are the same requirements used by the Select tag for Formatted Grid components. For more information, see Axiom query setup for use in a Select tag.

Optional. The column that contains the list of values, specified using a fully qualified Table.Column name or an alias name. For example: Acct.Acct.

By default, the first column in the Axiom query field definition is assumed as the value column. You only need to specify the value column in the tag if it is not the first entry in the field definition.

Optional. The column that contains descriptions for the value column, specified using a fully qualified Table.Column name or an alias name. For example: Acct.Description.

By default, the second column in the Axiom query field definition is assumed as the description column. You only need to specify the description column in the tag if it is not the second entry in the field definition and if you are not using the DisplayFormat parameter to define a custom display format.

However, if you are using the DisplayFormat parameter to define a custom display format, then the DescriptionColumn parameter does not apply. Instead, you should include the description column in the custom display format as desired.

Optional. The cell that contains content that you want to display in the combo box other than the selected value. Specify either a cell reference (A22) or a column letter (A). If only a column letter is specified, the current row is assumed.

For example, if the purpose of the combo box is to select an account, and the account list displays items as Account - Description, then you may want the selected value to also display as Account - Description instead of just Account. You could have a formula in the designated display cell that creates this alternate display based on the selected value.

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:

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:

This would display account items in the following format:

Any column used in the display format must also be included in the field definition of the Axiom query.