AX2133

Update and save behavior for Axiom forms

This section explains the update and save-to-database behavior that occurs when a user views a file as an Axiom form. Axiom form designers should understand this behavior to set up their forms appropriately for user interaction.

NOTE: When using embedded forms, special behavior applies to the form update cycle, as both the parent and child forms may be updated. For more information, see Form session and update behavior for embedded forms.

Update behavior

The data displayed in an Axiom form is determined by the data queries set up in the source file. When a user views an Axiom form, the data in the form is updated as follows:

• When the user first opens the Axiom form, a calculation is performed and data is refreshed in two stages:

  • First, Axiom queries that are set to refresh on open are refreshed.
  • Then, the equivalent of a "manual" refresh occurs. This means all Axiom queries set to Refresh on Manual Refresh are refreshed.

  This determines the initial state of the Axiom form.

• If a user changes an interactive component on the Axiom form (such as a combo box or a check box), and the interactive component is configured to Auto Submit, then the current state of all interactive components is written back to the source file. A calculation is performed and all active Axiom queries that are configured to run on manual refresh are refreshed. The Axiom form is updated after this refresh is complete.

  NOTE: The changed state of the component is not saved within the source file, it is a temporary value for the current session. When the Axiom form is next opened, it starts with the default component values.

  If the interactive component is not configured to Auto Submit, then the changed values are not submitted until the user triggers a form update by using a Button component, or by using a different interactive component that is configured to Auto Submit.

• If a user triggers an update of the Axiom form by using the Button component, then the current state of all interactive components is written back to the source file. A calculation is performed and all active Axiom queries that are configured to run on manual refresh are refreshed. The Axiom form is updated after this refresh is complete.

The user's security filters apply to the data queries, just as if the user had opened the source file directly and refreshed. All data displayed in the Axiom form will be specific to the current user (unless a component is displaying hard-coded data, or data left over from an inactive query).

If data lookups are used in the form-enabled file, they will be executed using the normal execution behavior for data lookups—such as executing on open, or executing after a particular Axiom query is run. Unnamed data lookups will be executed after Axiom queries whenever a form update occurs.

NOTE: If a user refreshes the web page for the Axiom form by using the browser refresh / reload functionality instead of using the Button component, this is interpreted as the user closing and reopening the file. The "file open" refresh behavior applies, and the Axiom form will revert to its initial state.

Save behavior

Forms can process two different methods of save-to-database:

• Saves that are executed from the spreadsheet source file of the form, using Save Type 1 or Save Type 4 ("spreadsheet save")
• Saves that are executed from a Data Grid or Fixed Report component within the form ("component save")

If the form contains either of these save-to-database methods, then users can trigger a save-to-database from the Axiom form. The following actions can trigger a save-to-database:

• When a user clicks the save icon in the Task Bar The 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..
• When a user changes an interactive component, and the component is configured to both Auto Submit and Save on Submit.
• When a user clicks a Button component, and the component is configured to Save on Submit.

When the form update includes a save-to-database, the basic process is as follows:

• If the form contains a component save, then this save is processed before any of the update behavior described in the previous section begins.

• Once the component save is complete, or if the form does not have an active component save, then the normal form update behavior occurs—meaning, the current state of interactive components is sent to the source file, and the file is calculated and refreshed.

• If the source file contains a spreadsheet save, this save is processed after the data refresh is complete. When the spreadsheet save is complete, the source file is calculated again, and any Axiom queries that are set to Refresh after save data are run.

• The Axiom form is updated, and an optional confirmation dialog informs the user that the save completed successfully.

The user must have the Allow Save Data security permission for the file in order to perform the save-to-database. The user's security filters apply to the data save as normal.

NOTE: The source file itself is not saved when a save is triggered from an Axiom form, only a save-to-database occurs.