AX2147

Radio Button component for Axiom forms

The Radio Button component allows the user to select one option from a group of options. The Axiom form can change in some way based on the user's selection.

Radio Button components are only valid in the context of a button group. You must have at least two Radio Button components on your form that belong to the same button group. Only one radio button in a group can be selected at any one time.

Component properties

You can define the following properties for a Radio Button component.

Component properties can be configured using the Form Assistant task pane or the Form Designer unless otherwise noted. All properties can also be defined on the Form Control Sheet directly if desired. For example, if you want a property to be dynamic depending on the result of a formula, you can define that formula in the control sheet. To access the control sheet settings for the component, double-click any property name to go to that property in the Form Control Sheet.

Component behavior properties

The following properties control the display and behavior of this particular component type.

Item	Description
Text	The display text for the button. Remember that the button text should make sense in the context of the other buttons in the group. It should be clear that the selections are mutually exclusive (only one button in the group can be selected at a time) and what each button will do if selected. You may also want to use a separate Label component to provide an overall title and/or explanatory text for the button group.
Tooltip	Optional. The tooltip text for the component. When a user hovers the cursor over the component, the text displays in a tooltip.
Button Group	The button group for the component. Radio buttons must belong to a button group. You can define a new button group name by typing the name into the box, or you can select from any previously defined group name. When the Axiom form is rendered, users can select one of the buttons within a particular button group at any one time.
Is Selected	The current state of the button in the button group, selected or not selected. This setting serves two purposes: It specifies which button is selected within the button group initially, when the user first opens the Axiom form. By default, this is disabled, which means the button is not selected. If you want this button to be selected initially, enable this setting. When a user views the Axiom form and selects the button (or selects another button in the group, thereby causing this button to become not selected), the change in the selected status 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 current status of this button. Only one button within a button group can be selected at any one time.
Auto Submit	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 a radio button. 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 radio button 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.
Save on Submit	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.
Enabled	Specifies whether the component is enabled. By default this is set to On, which means that the component displays normally and users can interact with it (if applicable). This setting can be used to dynamically enable or disable the component using a formula. If set to Off, then the component displays as grayed out. If the component is normally interactive, users cannot interact with the component while it is disabled. Disabled components cannot trigger update events for the form. NOTE: This setting is only available on the Form Control Sheet; it cannot be set in the Form Assistant or in the Form Designer.

General properties

The following general properties are available for all components:

Item	Description
Component Name	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".
Visible	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.
Layer	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.
Parent	The parent component that this component is assigned to. If blank, then the component does not have an assigned parent. Currently, only Panel components can be designated as parents. If a component has an assigned parent, then that component is positioned within the parent instead of within the canvas at large. If the parent is hidden, all "child" components of that parent are also hidden. The parent assignment is automatically completed when a component is dragged into a panel in the Form Designer, and automatically cleared when a component is dragged out of a panel. In most cases, you should not need to manually assign a parent.

Style and formatting properties

To define the component formatting, you can assign one or more styles to the component. Styles can impact formatting properties such as fonts, borders, and colors.

If you do not want to apply a style to this component, or if you want to override one or more formatting properties in an assigned style, click the Show Advanced Settings link underneath the Style box to display the individual formatting properties. For more information on defining individual formatting properties for a component, see Formatting overrides for Axiom form components.

Currently, the Axiom Software platform does not provide any styles specifically designed for Radio Button components. Only the generic styles are available. Most radio button styling is controlled by the form-level skin.

Item	Description
Style	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.
Component Theme	(Deprecated.) The theme to use for the component instead of the form-level theme. If left blank, the component uses the form-level theme. This setting should be left blank unless you need to override the form theme. Generally speaking, themes should be set at the form level and only overridden at the component level when necessary. This setting is available in the advanced component properties (click Show Advanced Settings under the Style box). On the Form Control Sheet, the setting displays using the name Theme Override. NOTE: This setting only applies if your form uses a legacy skin (any skin except the default Axiom2018). The Axiom2018 skin does not use themes.

Item

Description

Style

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.

Component Theme

(Deprecated.) The theme to use for the component instead of the form-level theme. If left blank, the component uses the form-level theme.

This setting should be left blank unless you need to override the form theme. Generally speaking, themes should be set at the form level and only overridden at the component level when necessary.

This setting is available in the advanced component properties (click Show Advanced Settings under the Style box). On the Form Control Sheet, the setting displays using the name Theme Override.

NOTE: This setting only applies if your form uses a legacy skin (any skin except the default Axiom2018). The Axiom2018 skin does not use themes.

Position and size properties

You can view the position and size properties for a component by clicking the Show Advanced Settings link under the Style box. If necessary, you can edit these properties directly (instead of automatically modifying them by adjusting the component's position and size on the canvas). For more information on using these settings, see Controlling component position and size.

Item	Description
Reference Location	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.
X Position Y Position	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.
Width Height	The width and height determine the size of the component. The width and height can be set in pixels (default) or percentages. Size keywords are also available to support special behavior.
Rendering Order	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.
Lock Layout	If enabled, the component size and position are locked and cannot be changed by dragging and dropping on the canvas. This optional setting is intended to protect against accidentally moving or resizing a component while working on the canvas.

Interactive behavior

The Radio Button component allows the user to select an option from among all of the radio buttons in the button group. The current state of the radio buttons is submitted back to the source file, and written to the Is Selected setting on the Form Control Sheet (for each button in the button group). Only one of the radio buttons in the button group can be selected at any one time.

If you want the Axiom form to respond to the state of the radio buttons, then you must set up the file so that another component references the radio button state and changes based on it. For more information on setting up interactive components for an Axiom form, see Using interactive components in an Axiom form.

Example

An Axiom form could contain a group of radio buttons that determine what layer is currently visible in the form. When a user selects one of the radio buttons, that selection is written back to the source file to the Is Selected setting for all of the radio buttons in the group. The selected radio button would be set to On, and the other radio buttons would be set to Off.

The layer visibility settings could look to the radio button settings to determine when a particular layer would be visible or not. For example, the visibility setting for layer 1 could contain a formula such as:

=IF(Control_Form!D428="On","On","Off")

In this example, the Is Selected setting for the radio button is located on the Form Control Sheet in cell D428. If that radio button is selected, this layer is visible. If that radio button is not selected, this layer is hidden.

Button groups

Radio Button components can only be used as a group of buttons. For example, you might set up an Axiom form with three different radio buttons, asking the user to select which company they want to view in the form.

To do this, you would drag and drop three different Radio Button components onto the form canvas, and then in the component properties you would assign each to the same button group. It is also a good idea to add a Label component, for a title and/or explanatory text.

While setting up the radio buttons on the canvas, you may find it helpful to use Arrange > Align to align all of the buttons to one edge (in this example, the left edge), and then to distribute them equally (in this example, vertically).

The radio buttons would display as follows in the Axiom form. In this case, the ACME North America button is selected by default (due to enabling Is Selected in Group). The user can click on another radio button in this group to select that option and clear the ACME North America option.

What occurs when a user selects a radio button is entirely up to the form designer. In this example, each company could be set up on a different layer of the form. The layer visibility settings could look to the radio button settings to determine when a particular layer would be visible or not. For example, the visibility setting for layer 1 could contain a formula that says the layer is visible when Is Selected is On for the ACME North America radio button, and not visible when the setting is Off.

Design alternatives

Axiom forms often support several different ways of performing the same task, to provide a broad range of display options and user interface behavior. Depending on your form design, you may want to consider the following alternatives:

Button components can also be used in a group as selectors, as an alternative to Radio Button components. For more information and a discussion of the differences between the two options, see Using buttons as selectors (button groups).
If you want to present more than 3-4 options, a Menu component may be more user-friendly than a button group. Users can select items from the menu in order to impact the form in some way. For more information, see Menu component for Axiom forms.