AX1519

Defining refresh variables for Axiom forms

Refresh variables can be used in form-enabled files, to filter the data shown in an Axiom form. Users can select values for these variables and trigger a data refresh. The data displayed in the form can then change based on the user's selections for the refresh variables.

In Axiom forms, users interact with refresh variables using the Filters panel. The Filters panel is available by clicking the filter icon in the Task BarThe gray bar that displays across the top of browser-based Axiom files, as well as various feature pages of the Web Client. The Task Bar provides access to various tasks that are specific to the current area, page, or document.. The refresh variables defined in the form source file automatically display in the panel.

Example Filters panel

Refresh variables provide a "built-in" option to allow users to change the data coming into an Axiom form. Instead of needing to manually create form components to gather user inputs, you can define refresh variables just like you would for a spreadsheet Axiom file.

The basic operation of refresh variables in the Web Client works as follows:

  • You create a form that displays data in some way, such as in a data grid, formatted grid, or a chart.
  • You define refresh variables in the form source file, and configure the data queries in the file so that they change depending on the user's inputs for those variables. For example, you might prompt users to select a business region, and then filter the data queries so that they return data for the selected region.
  • When users view the form, they can use the built-in Filters panel to complete the inputs for the refresh variables and trigger a data refresh.
  • The form is then updated to show the latest data based on their refresh variable selections.

NOTE: The Web Client Container must be enabled for a form in order to display the task bar and use refresh variables. The container is enabled by default for all new forms.

This topic provides information on how to set up an Axiom form to use refresh variables, including details on what occurs during the data refresh. For more information on how users interact with the Filters panel, see Filtering data in Axiom forms.

Defining the refresh variables

To define refresh variables for use in a form, add a RefreshVariables data source to the form-enabled source file. The process to add the data source and define the individual variables is exactly the same as for use with a spreadsheet Axiom file. For more information, see Defining refresh variables.

Axiom forms support all of the refresh variable types and options, with the following exceptions:

  • Grid variables should only be used when multi-select is enabled for the variable. If multi-select is not enabled for the variable, then the Grid variable will display and behave like a ComboBox variable, so it is recommended to use a ComboBox variable instead.

    NOTE: The web version of the grid dialog does not display using separate columns, so the list is not sortable by column.

  • The Refresh Forms Run Behavior setting on the Control Sheet does not apply to Axiom forms. There is no way to force the user to select values when the form is first opened.

Axiom forms also support an additional refresh variable option, which is the ability to group variables for display in the Filters panel. For more information, see the following section on Grouping refresh variables.

The Filters panel is automatically available if the form has at least one enabled refresh variable. The RefreshVariables data source does not have to be linked to anything on the form canvas. However, if a form does not have a RefreshVariables data source or if no variables are enabled, then the filter icon does not display in the task bar and the Filters panel is not available.

Grouping refresh variables

When using refresh variables with Axiom forms, you can optionally use the [GroupName] column in the RefreshVariables data source to group variables within the Filters panel. Grouped variables display within an expandable / collapsible section, using the group name as the section header.

Groups display in the order they are found in the RefreshVariables data source. All variables belonging to that group name will display in that group, in the order the variables are listed in the data source. Therefore, when using groups, a variable that is lower in the list may display before variables above it, depending on its group assignment.

When using groups, it is recommended to assign all variables to a group. Any variables without a group assignment will display after the grouped variables.

The following example data source shows several variables belonging to groups:

When a user views this file as a form and opens the Filters panel, the variables display as follows:

You can also use the [CollapseOnOpen] column (True/False) to specify that a group starts out as collapsed. By default, groups are expanded, but you can use this option to collapse groups as needed. If one variable in a group is set to True, then the group starts out as collapsed.

Filters panel behavior

When a user opens the Filters panel, all enabled refresh variables are rendered in the panel. If no groups are used, variables are presented in the order they are defined in the data source. If using groups, see the previous section for information on how variables are ordered.

The variables start at the top of the Filters panel and display vertically downward. If the number of variables exceeds the height of the panel, a vertical scroll bar is present.

Once the user has made selections for all required variables and any optional variables, the user can click the Apply button to submit the variable values to the form source file and trigger the data refresh. This process works as follows:

  • The Triggering Component for the form is set to Axiom.RefreshPanel. This is a reserved name that identifies the Filters panel as the source of the refresh. You can use this information to dynamically enable Axiom queries to execute as part of the refresh.

  • The user's selected values for the refresh variables are placed in the [SelectedValue] column of the data source.

  • Axiom queries that are active and set to Refresh on Manual Refresh are run. The file is calculated before and after the query refresh. Data lookups will be run as normal (unnamed data sources are always executed after the Axiom queries as part of the manual refresh, and named data sources are executed after the Axiom queries if configured to do so).

    Just like when using refresh variables in spreadsheet Axiom files, it is up to the form designer to set up the data queries so that they change based on the user's selected values. For example, the data filter of an Axiom query may change depending on the user's selected value for a variable.

  • The following specialty components are updated as follows:

    • If the form contains a Data Grid component, the data query for the grid is refreshed using the current state of all component and data source settings. Any user changes made to the grid in the form—such as filtering columns, sorting columns, selecting rows—are all reset due to the refreshed data.

    • If the form contains a KPI Panel component that uses a KPI table, the data query for the panel is refreshed using the current state of all component settings.

    Again, it is up to the form designer to set up these components to change based on the user's selected values.

  • The form is refreshed in the browser to reflect the current state of all components.

IMPORTANT: The Filters panel is intended to impact data queries only. The Filters panel does not trigger the full form update cycle. For example, interactive values for components are not submitted back to the source file, and save-to-database cannot be triggered. Any component changes that have not yet been submitted to the source file will be lost after the refresh, and the component will be reverted to its current state in the source file.

The variables and their current settings are read from the source file when the form is first opened, and after that, every time the variable values are submitted using Apply.

Dependent variables behave the same way that they do in the Desktop Client. If a user changes the value of a variable that another variable is dependent on, the selected value of the parent variable is sent to the source file and the file is calculated. Any changes to the dependent variable will then be reflected in the Filters panel, including showing or hiding variables based on the [IsEnabled] column as appropriate. This process only updates the refresh variables in the panel; the form itself is not updated.

If the RefreshVariables data source changes due to an update triggered by an interactive component in the form, the Filters panel will not update for these changes until the variable values are submitted using Apply. For example, imagine that you have a variable that uses a formula to determine whether the variable is enabled or not, and that formula looks to the selected value of a ComboBox component. If the user changes the value of the ComboBox component and this change causes the variable to become enabled, the Filters panel will not immediately update for this change. However, when the user clicks Apply to submit the refresh variables, the panel will be updated after the data refresh, and at that point the new variable would show up. Therefore, it is not currently possible to adjust the RefreshVariables data source using form components, as the change will not be recognized in the Filters panel as part of the form update triggered by the component.

Filters panel behavior for embedded forms

If you are using a form with one or more Embedded Form components, the Filters panel shows refresh variables for the parent form and the currently visible child embedded forms. When the variables are applied, they are applied to their respective parent or child forms and the forms are refreshed as described in the previous section. Note the following:

  • Variables from the parent form are displayed first, followed by variables from the currently visible child forms. It may be helpful to use groups to organize the variables if there are many variables or if you need to distinguish between the parent and child variables. However, keep in mind that variables cannot be grouped across forms. For example, if the parent form has a group called Time Period and the child form has a group called Time Period, the variables will not display in the same group. Instead, the Filters panel will display duplicate group names.

  • Variables in one form cannot depend on variables in other forms. For example, you cannot use the selected value of a variable in the parent form to filter the list for a variable in the child form. It is possible to use shared variables to pass the selected value of one form's variable to another form, but the value cannot be used to impact a refresh variable in the other form.

  • When refresh variables are applied, the parent form is refreshed first, followed by the child form (assuming both forms have refresh variables). If only one form has refresh variables, then only that form will be refreshed by the Filters panel. The other form will not be updated unless you force it to do so by using an option such as Refresh Parent Form or Force Refresh.

  • As noted in the previous section, any unsubmitted changes in the parent or child form will be lost when refresh variables are applied to that form. However, if the parent or child form does not have refresh variables and is not otherwise being forced to update, then the form will be left as is, including its unsubmitted changes. If the parent or child form does not have refresh variables but is being forced to update by the other form, then changes will be submitted as normal during that update.

Availability of Filters panel

The task bar and the filter icon are available when the form is opened in any Axiom Software client. However, the initial visibility of the Filters panel differs depending on the environment where the Axiom form is viewed:

NOTE: If a form is opened in the Desktop Client as a dialog or a task pane, then refresh variables are ignored and the Filters task pane will not be present.