AX2122

Using interactive components in an Axiom form

You can use interactive components in an Axiom form to collect inputs from users and then perform an action based on those inputs. For example, you can save the user's inputs and other data to the database, or you can change the contents of the form based on the user's inputs.

NOTE: If the only purpose of a user input is to change the data shown in the form, then you can use refresh variables as an alternative to setting up interactive components. See the following discussion Using interactive components versus refresh variables for more information.

Interactive components allow form users to change the state of the component in some way. The user may be able to select a value from a list, or type text into a text box, or simply toggle the component as selected or not selected. After the user interacts with the component to change its state, this state change is submitted back to the form source file. The form can then trigger an action and/or change in some way based on the user's interaction with the component.

How interactive components work

All interactive components have a dedicated property that reflects the current state of the component. For example, the CheckBox component has the property Is Checked on the Form Control Sheet. When a user first opens an Axiom form with a CheckBox component, the check box displays using the state of the Is Checked property as saved in the source file. For example, if the source file for the Axiom form has Is Checked set to Off, then the check box is not checked when the user opens the form.

The user can then interact with the check box to change it from unchecked to checked. This state change is submitted back to the source file, and the Is Checked property is changed from Off to On as a result of the user's interaction. The source file is then refreshed, and the form is updated.

In order for the content of the Axiom form to change based on this user interaction, a second component must reference the state of the interactive component and then change in some way based on that state. For example, a series tag for a column chart could reference the check box state to determine if the series is visible or not. The key point is that the Axiom form interactivity is completely dependent on the file setup. If no other components in the Axiom form reference the state of the interactive component, then no change will occur in the form (other than the check box being checked). It is up to the Axiom form designer to set up the interactivity as desired.

By default, most interactive components are configured to automatically update the Axiom form when their state changes. For example, when a user selects or clears a check box, the changed state is automatically written back to the source file, a refresh occurs, and then the form is updated. If desired, you can change this configuration so that the Axiom form will not update until the user manually initiates an update by using a Button component. You may want to do this if your Axiom form has multiple interactive components—for example, if you have multiple combo boxes, and you want all of the user's selections to be sent back to the source file at one time, rather than as each one is selected. To disable the automatic update for an interactive component, clear the Auto Submit setting for the component.

When a user interacts with a component to change its state, the state change that is submitted back to the source file is never persisted past the current session. This is because Axiom forms are always open as read-only. Although you can trigger a save-to-database from an Axiom form, you cannot save the file itself. The next time the form is opened, the component state will revert to its original state as saved in the source file. If you do need to persist the state change of a component, then you would have to save the component state to the database, and then query that saved state back into the source file (using a function or a refresh on open query) to set the initial state of the component.

Submit behavior

When a user opens an Axiom form, a copy of the source file for that form is opened on the Axiom Application Server. The form is rendered based on the settings in that source file. As the user interacts with the form, their changes are submitted back to the source file on the application server. The source file is calculated and refreshed, and then the user's form is then updated based on the current state of the source file. For more information, see How Axiom forms are rendered to users and Update and save behavior for Axiom forms.

It is important to understand that whenever an update is triggered, the current states of all interactive components may be written back to the source file, not just the state of the component configured to Auto Submit. There is no way to ensure that just one particular component will be submitted. In most cases only changed components will be submitted for performance reasons, but certain conditions may require the form to send the state of all interactive components, to ensure that the file copy on the application server remains in sync with the rendered form that the user is interacting with.

This behavior means that if you use a formula in an interactive property, you can only count on using the formula to set the initial state of the component. If the user interacts with the component, or if the form detects that it needs to submit the current state of all interactive components, then that formula will be overwritten with the current state of the component.

For example, if you use a formula to set the Is Checked property of a check box, the check box will start off using the result of that formula. Once the user interacts with the check box, the current state is submitted to the source file and the formula is overwritten with either True or False. Additionally, even if a user never interacts with the check box, the current state of the check box may be submitted anyway when other interactive components are changed and submitted, to ensure that the form and source file remain in sync.

There are ways to work around this behavior if you need to use a formula to change the state of a component during an already active session. For example, you can use indirect cell references with most components so that the interactive value is read from and written to a cell in another sheet rather than the property cell on the Form Control Sheet. To continue the check box example, you would enter something like [Values!F5] in the Is Checked property, to "redirect" the interactive value to that cell. You could then use action codes on the Values sheet to copy the result of a formula to that designated cell.

NOTE: When you are working on a source file in the Desktop Client and you preview the form, remember that the form is using a copy of the source file on the application server, not the copy that you have open in the Desktop Client. If you change interactive components in the preview, you will not see those changes reflected in the file that you have open in the Desktop Client.

Interactive components

The following components can be used as interactive components to change the Axiom form in some way:

  • Area / Bar / Column / Line / Waterfall Charts: The selected item in these charts can be sent back to the source file.
  • Button: Button components support several types of interactivity: 1) The currently selected button in a button group can be sent back to the source file (like a radio button), 2) The button can be used to launch a multi-select dialog and send the selections back to the source file, and 3) The button can be used to trigger an update of the form (including running specified commands).
  • Check Box: The state of the check box (checked or unchecked) can be sent back to the source file.
  • Combo Box: The selected item in the combo box can be sent back to the source file.
  • Data Grid: The selected row in the grid can be sent back to the source file. Additionally, icons can optionally be used in the grid to execute commands, which can trigger an update of the form.
  • Date Picker: The selected date can be sent back to the source file.
  • Fixed Report: The selected row in the report can be sent back to the source file. Additionally, icons can optionally be used in the report to execute commands, which can trigger an update of the form.
  • Formatted Grid: Formatted grids support several types of interactivity: 1) The selected row in the grid can be sent back to the source file, 2) The changed value in an editable cell can be sent back to the source file, and 3) Various content tags can be used to display interactive controls in the grid and send information back to the source file.
  • Hierarchy Chart: The selected node in the hierarchy can be sent back to the source file.
  • KPI Panel: The selected KPI in the panel can be sent back to the source file. Additionally, each KPI can optionally be associated with one or more commands, which can trigger an update of the form.
  • Map View: The selected pin, circle, or feature can be sent back to the source file.
  • Menu: The selected ID in the menu can be sent back to the source file.
  • Pie Chart: The selected slice in the pie chart can be sent back to the source file.
  • Radio Button: The currently selected button in a button group can be sent back to the source file.
  • Scatter / Scatter Line / Bubble: The selected item in these charts can be sent back to the source file.
  • Slider: The selected value on the slider can be sent back to the source file.
  • Text Box: The text entered into the text box can be sent back to the source file.
  • Wizard Panel: The value for the current step can be sent back to the source file, to drive the content for the current step.

Most interactive components store their current state in a designated property on the Form Control Sheet. However, some interactive features use different approaches, such as the target cell for interactive controls in a formatted grid. For more information on each component and how its current state is written back to the form source file, see Axiom form components.

Using interactive components versus refresh variables

Refresh variables can also be used in form-enabled files to provide interactivity. Form users can use the Filters panel to make selections for those variables and send the values back to the source file. The queries in the file are then refreshed. Assuming the queries reference the variable values in some way, the data shown in the form can then change based on the user's selections for the refresh variables. For more information, see Defining refresh variables for Axiom forms.

Refresh variables are intended to impact the data shown in a form. They are best suited to provide interactivity for web-enabled reports, to impact the data refresh. Refresh variables are not suited for other interactive uses, such as to collect data inputs from the user to save to the database.

When deciding whether to use refresh variables or interactive components to affect the data refresh of a form, keep in mind the following differences:

  • Interactive components are displayed directly on the form, along with any data shown. Refresh variables are displayed "on demand" when the user chooses to open and use the Filters panel.

  • Interactive components always trigger a full update cycle for the Axiom form when their values are changed. Refresh variables do not trigger a full update cycle. The only updates performed are to submit the refresh variable values back to the source file and then refresh the data in the source file.