AX1603

Form session and update behavior for embedded forms

When using embedded forms, the parent and child forms are opened and maintained in a shared form instance. These form sessions are managed and updated using special behavior that is intended to keep all forms in the shared form instance simultaneously active and in sync.

Session behavior

When a user views a form with embedded forms, the parent form and all of its child forms are managed together by the Axiom Application Server as a related set of forms (the shared form instance). Once a child form has been opened within an Embedded Form component, the session for the child form remains active on the Axiom Application Server until the parent form is closed, even if the child form is not currently visible in the form web page.

For example, imagine a parent form with a Menu component and an Embedded Form component. When the user first opens the parent form, child form 1 is visible as the embedded form. Then the user chooses a different option in the menu, which causes child form 2 to be visible as the embedded form.

When the user switches from showing child form 1 to child form 2, the session for child form 1 is not closed. If child form 1 has unsubmitted values, the form update cycle is processed on the form and the end results of that update are persisted on the Axiom Application Server. If the user switches back to showing child form 1 as the embedded form, the results from the previous update are used to render the form. (The form may or may not be updated again before it is rendered, depending on whether force refresh is enabled for the target form in the Menu data source or in the Embedded Form component properties.) This behavior allows the form user to access multiple child forms within the shared form instance, and all of those forms will remain active as long as the session for the parent form remains active.

If the form user closes the parent form by any means—such as by closing the browser tab, or by using the browser refresh functionality to reload the form, or by navigating away from the parent form to show a different form within the browser tab—then all of the child form sessions that were related to that parent form are closed too.

Form update behavior when the parent form is initially opened

The following update behavior occurs when the parent form is initially opened:

  1. The normal "initial open" behavior occurs for both the parent form and the child form (including running Axiom queries set to refresh on open).

    • The parent form completes its update cycle before the child form begins its update cycle. This allows the child form to access any shared variable values that are set by the parent form.

    • When the child form is updated, the triggering component is logged as the reserved word $ParentForm. Normally, the "initial open" process does not have a triggering component, but it is logged in this case to indicate that the parent form caused the child form to open.

  2. If the Embedded Form component has Refresh Parent Form enabled, then the parent form is updated again after the child form completes its update cycle. This allows the parent form to access any shared variable values that are set by the child form. If this second update occurs, the triggering component for the parent form is logged as the Embedded Form component.

    If Refresh Parent Form is not enabled, then the parent form is not updated again. The previous response for the parent form is used to refresh the web page. If the parent form depends on any values set in the child form, it will not reflect those changes until another update occurs.

  3. Once all form updates are complete, the web page is refreshed to show the initial state of the parent and child forms.

This behavior also applies when the parent form is closed and reloaded, such as when using the browser's refresh feature.

Form update behavior when an update is triggered in the parent form

When an update is triggered in the parent form, the following occurs:

  1. Before the parent form's update cycle begins, Axiom Software evaluates whether the child form must be updated first. The full form update cycle is processed in the currently visible child form if either of the following apply:

    • The child form has unsubmitted changes.
    • The child form has previously submitted but unsaved changes, and a save-to-database is enabled in the child form.

    Note the following special behavior for this update cycle:

    • The triggering component in the child form is logged as the reserved word $ParentForm. This indicates that the update was triggered by the parent form and not by a component in the child form. You can reference this value to enable or disable certain things based on whether the update is triggered by the parent form (such as to enable a save-to-database process or an Axiom query).

    • Axiom Software attempts to execute a save-to-database at the normal part of the child form update cycle if either of the following are true:

      • Save on Parent Submit is enabled for the Embedded Form component
      • Save on Submit is enabled for the triggering component in the parent, or the triggering component is the save icon (Axiom.FormSave).

      For more information, see Saving data for embedded forms.

    • The end response that updates the child form is fully prepared at the end of the process, but the page itself is not actually refreshed until the parent form has completed its update—at which point the child form may not be visible anymore, such as when the update was triggered by the user clicking on a different item in the Menu component. If so, the response is stored so that it can be used the next time the user switches back to the child form.

  2. The full form update cycle is now processed in the parent form. The triggering component for the parent form is logged as normal.

    If the child form was processed first, the parent form now has access to any shared variable values that were set by the child form, and to any data saved by the child form.

  3. If the parent form contains a Menu component that determines what is shown in an Embedded Form component, then any additional child form updates depend on the current target of the Embedded Form component (as determined after the parent form update):

    • If the current target is a new child form that is being opened for the first time in the current session, then the normal "initial open" behavior occurs for the child form (including running Axiom queries set to refresh on open).

    • If the current target is the same child form or a previously opened child form, whether the child form is updated again depends on the [ForceRefresh] setting in the Menu data source:

      • If True, then the full form update cycle is processed for that child form, allowing it to update for any changes made in the parent form or in other child forms.

      • If False, then the end response that was stored from the child form's last update is used to render the child form.

    Also, if Force Refresh is enabled for the Embedded Form component, then the full form update cycle is processed for the child form. This applies in cases when the parent form does not contain a Menu component, or when the component-level setting is used instead of the setting in the Menu data source.

    In all cases, if the child form is updated, the triggering component is logged as $ParentForm.

  4. If the Embedded Form component has Refresh Parent Form enabled, and a child form update was processed in step 3, then the full form update cycle is processed again for the parent form. This allows the parent form to access any shared variable values that are set by the new child form.

    If this second parent form update occurs, the triggering component for the update is logged as the Embedded Form component. Keep in mind this means that the triggering component for the second update is different than the triggering component of the first update.

  5. Once all form updates are complete, the web page is refreshed to show the current state of the parent and child form.

For example, imagine that the user has made changes in the current child form, but those changes have not yet been submitted. The user then uses the Menu component in the parent form to switch to a different child form. Depending on the refresh settings configured on the Embedded Form component and in the Menu data source, the full update process could be as follows:

  • The current child form is updated to preserve its unsubmitted changes before switching to the other child form.
  • The parent form is updated to reflect the newly selected menu item (as well as for any other changes to the parent, or for any shared variables set by the current child form).
  • The new child form is updated, either for the first time (if initially opened), or to reflect any changed shared variables or new data (if previously opened).
  • The parent form is updated again to reflect any shared variables set by the new child form.
  • The web page is refreshed to show the current state of the parent form and the new child form.

NOTE: The behavior described here applies when an update is triggered by using a Button component or an interactive component that is set to auto-submit. The Filters panel has special behavior that does not trigger a full form update. For more information, see Defining refresh variables for Axiom forms.

Form update behavior when an update is triggered in the child form

When an update is triggered in the child form, the following occurs:

  1. The full form update cycle is processed in the child form. The triggering component for the child form is logged as normal.

  2. If the Embedded Form component has Refresh Parent Form enabled, then the full form update cycle is processed in the parent form. This allows the parent form to access any shared variable values that are set by the child form, as well as any data saved by the child form. The triggering component for the parent form is the Embedded Form component. Note the following:

    • The child form is not updated again as part of this process, even if Save on Parent Submit is enabled for the Embedded Form component. Because the update process was triggered by the child form instead of the parent form, Save on Parent Submit does not apply in this case. If you want the child form to save data to the database as part of this update, the triggering component in the child form must be configured to Save on Submit.

    • Because the child form was updated first, if the child form depends on any values set in the parent form, it will not reflect those changes until another update is triggered.

  3. Once all form updates are complete, the web page is refreshed to show the current state of the parent and child form.

Design considerations

If two or more of the files in the shared form instance have GetData queries with the exact same parameters, and sheet filters are not defined for the relevant sheets, then the GetData queries should be configured to ignore sheet filters. This allows the files to leverage the shared GetData cache for the shared form instance, so that the requested data is only queried from the database once and then used by all requesting files. This applies to both GetData functions and data lookups.

If the sheets with the GetData queries have sheet filters and you want those sheet filters to apply to the GetData queries, then you should not ignore sheet filters, and those queries will be cached on a per sheet basis.