AX1604

Saving data for embedded forms

When using embedded formsBy using an Embedded Form component, a parent form can display one or more child forms within the same form instance. These forms can share values and leverage other special update and save behaviors., there are several options to handle saving data to the database. The method that you choose depends on the flow of data in your forms and on the desired user experience:

Automatic Save: Data is automatically saved from the currently visible child form as the user switches between child forms.
Manual Save from Parent: The user decides when data is saved, by clicking a designated save button in the parent form.
Manual Save from Child: The user decides when data is saved, by clicking a designated save button in each individual child form.

In most cases, data is saved from the child forms only. The parent form is typically just a "frame" that contains the Menu and Embedded Form components. Usually, data is not manipulated or saved from the parent form, though it can be if desired.

NOTE: The save locking feature can be used with embedded forms, but only at the parent form level. If the parent form has a defined data context, it will control saving data for the parent as well as all child embedded forms. Data contexts cannot be defined at the child form level.

Saving data automatically for embedded forms

You can configure embedded forms so that data is automatically saved in the currently visible child form whenever the parent form is updated. The intended use case for this approach causes the data to be saved as the user switches between forms by using a Menu component. The general user experience is as follows:

The user makes changes in the currently visible child form (Form 1).
The user clicks on the Menu component to switch to a different child form (Form 2).
As part of the update process associated with changing the child form shown in the Embedded Form component, a save-to-database is automatically performed in Form 1 before switching over to Form 2.

This approach ensures that all user changes are saved to the database, and those changes are immediately available to the parent form and other child forms. It is intended for embedded form designs that depend on querying changed data from the database, as opposed to sharing unsaved data via shared variables.

One disadvantage of this approach is that users cannot experiment with different data entries and see the effects of their changes without committing them to the database. Also, it may not be clear to users that their inputs are being saved in the absence of an explicit save action.

To set up an automatic save for embedded forms:

In the parent form, enable Save on Parent Submit for the Embedded Form component.
In the child forms, set up the save-to-database processes as needed. Note the following:
- It is required to disable Save Data Confirmation in all of the child forms (even if no save-to-database is enabled in a particular child form). The confirmation dialog is not supported when using this configuration, due to the frequency of saving and the timing of showing the confirmation. To disable this setting, click Edit Form Properties in the Form Assistant task pane or Form Designer dialog. (Note that the setting is disabled by default in new forms, so you only have to do this if it was previously enabled.)
- It is not necessary to configure a component in the child forms with Save on Submit, unless you want to also allow users to trigger a save from within each individual child form. For example, you might want to place a save button on the child forms so that users can save data without needing to switch forms, at which point the automatic save is more like a safety net in case the user forgets to manually save.

When Save on Parent Submit is enabled for the parent form, the update behavior works as follows whenever an update is triggered for the parent form (using any component):

If the currently visible child form has unsubmitted changes, or previously submitted but unsaved changes, the child form performs a full form update that includes executing a save-to-database. (If the child form has no changes, then no action is taken on the child form, and the process skips to updating the parent form.)
If no save-to-database process is currently enabled in the child form, the save-to-database portion of the update is skipped. No error occurs, and the rest of the form update occurs as normal. Remember that Axiom queries set to "refresh after save data" do not execute if the save-to-database is skipped.
If an error occurs during the save-to-database process, the child form will complete its update cycle and display the save error, but the parent form will not be updated. This means that if the update is triggered by the user attempting to switch to another child form via the Menu component, the new target form will not load and the Embedded Form component will continue to display the current form. The user cannot move to another child form until the save error is resolved in the current child form.
If the child save-to-database completes successfully, then the child form update completes. The update process for the parent begins as normal. Other child and parent updates may occur, depending on various settings and whether the target of the Embedded Form component changes. For more information on the embedded form update process when the update is triggered by the parent, see Form session and update behavior for embedded forms.

Remember that although this method is intended to be used in conjunction with a Menu component, the child update and save-to-database will occur regardless of which component triggers the update in the parent form. For example, if the parent form contains a "refresh" button, or a combo box that is set to auto-submit, then clicking either of these interactive components will also cause the child form to update and save.

Saving data manually from the parent form

You can configure embedded forms so that users can save data in the currently visible child form by triggering a save-to-database in the parent form. The typical user experience is as follows:

The user makes changes in the currently visible child form (Form 1).
The user clicks on the Menu component to switch to a different child form (Form 2). The user can then start making changes in Form 2. The changes made to Form 1 are retained on the server but have not yet been saved to the database.
If a child form has unsaved changes, an asterisk displays on the menu item relating to that form. The asterisk remains until a save-to-database is executed on the child form.
At any time, the user can trigger a save in the parent form to update the currently visible child form and execute a save-to-database. In this example, the user would have to navigate back to Form 1 and click the save button in the parent form, in order to save data for Form 1.

This approach is intended for cases where data should only be saved to the database when the user explicitly decides to do so. If the data in one form depends on changes made to another form, and the user needs to be able to see the impact of these changes before saving data, then this data should be passed between forms by use of shared variables. Generally, this is only feasible if a small handful of data points need to be shared. If large amounts of data need to be referenced between forms, it is likely easier to use the automatic save approach instead, so that each form can query the necessary data from the database.

To set up a manual save for embedded forms:

The parent form must contain a way to trigger a save-to-database. This can be one of the following:
- Show Task Bar Save Icon can be enabled in the form properties of the parent form, in order to display the save icon in the task bar. This is enabled by default for newly created forms.
- You can add a Button component to the parent form and configure it to Save on Submit. (It is also possible to use a different kind of interactive component—such as a CheckBox or a ComboBox—and configure it to both Save on Submit and Auto-Submit, but this is a less common approach.)
In the parent form, set up a save-to-database process. Assuming that you do not need to save data in the parent form itself, this is a "dummy" save-to-database process that only serves the purpose of enabling the save icon in the task bar (or the component configured as Save on Submit). At least one sheet in the file must have Save Type 1 Enabled set to On in the main Control Sheet (an enabled Save Type 4 process also qualifies).

If you do also need to save data in the parent form, then you can set up a real save-to-database process in the parent form. In this case, when the user triggers the save-to-database, a save will occur in both the parent and the currently visible child.

It is required to disable Save Data Confirmation in the parent form. If enabled, confusing confirmation messages may result when the save is actually occurring in the child form. To disable this setting, click Edit Form Properties in the Form Assistant task pane or Form Designer dialog. (Note that the setting is disabled by default in new forms, so you only have to do this if it was previously enabled.)
In the child forms, set up the save-to-database processes as needed. Note the following:
- It is recommended to disable Save Data Confirmation in the child forms (even if no save-to-database is enabled in a particular child form), but not required.
- It is not necessary to enable the save icon in the child forms or configure a component with Save on Submit.
  
  If you want users to be able to save data from the child form directly, in addition to saving from the parent, then you can choose to add a Save on Submit component to the child form. However, it may be confusing to end users to have two different ways to trigger a save. Additionally, if you want to use a data context with the form in order to prevent concurrent saves, then the save button can only be present in the parent form. If a save button is present in a child form, it will not be controlled by the save locking behavior.

When a user clicks save icon in the task bar (or the Save On Submit component in the parent form), the update behavior is as follows:

If the currently visible child form has unsubmitted changes, or previously submitted but unsaved changes, the child form performs a full form update that includes executing a save-to-database. (If the child form has no changes, then no action is taken on the child form, and the process skips to updating the parent form.)
If no save-to-database process is currently enabled in the child form, the save-to-database portion of the update is skipped. No error occurs, and the rest of the form update occurs as normal. Remember that Axiom queries set to "refresh after save data" do not execute if the save-to-database is skipped.
If an error occurs during the save-to-database process, the child form will complete its update cycle and display the save error, but the parent form will not be updated. Note that when using this method, it is possible for a user to switch to another child form via the Menu component, make changes in that other child form, and save the other child form without error.
If the child save-to-database completes successfully, then the child form update completes. The update process for the parent begins as normal. For more information on the embedded form update process when the update is triggered by the parent, see Form session and update behavior for embedded forms.

NOTE: Due to the "dummy" save-to-database process in the parent form, users may see invalid warnings about unsaved changes. For example, if a user opens the form and then uses the Menu component to switch to a child form, that will flag the parent form as having unsaved changes even though the only thing the user has done is use the menu. If the user attempts to close the form in this state, they will see a warning about unsaved changes.

Saving data manually from child forms

If desired, you can configure embedded forms so that each child form has its own Save On Submit component that triggers a save-to-database for that child form. The component is typically a Button component, though any component that supports Save On Submit can be used.

You can use this "direct save" approach as the only save method for the form, or you can do it in conjunction with the automatic save method discussed previously. It is not recommended to configure child forms to save independently when using the manual save method on the parent, because the dual save buttons may cause confusion.

When a user triggers an update of the child form using the Save On Submit component in the child form, the full form update cycle is performed on the child form, including a save-to-database. The parent form may or may not be updated as part of this process, depending on whether Refresh Parent Form is enabled for the Embedded Form component. If the parent form depends on data that may have been changed by the child form, Refresh Parent Form should be enabled.

If you use this approach, all child forms should be designed so that the Save On Submit component displays in the same place on each form. If different child forms have different configurations, this may be confusing and/or frustrating to the user.

Updating other child forms for saved data

If child forms depend on data that may be changed by saving data in other child forms, you should consider whether [ForceRefresh] should be enabled for the child forms. This consideration applies regardless of which save method is used to trigger the save-to-database in the child forms.

Imagine the following scenario:

When the form is opened, the initial child form is Form 1. Form 1 queries data that can be changed using Form 2.
The user switches to Form 2 via the Menu component, makes changes to Form 2, and triggers a save to database using any method.
The user switches back to Form 1 via the Menu component. By default, Form 1 is not updated when it is reloaded into the parent form as the current embedded form, because it has been previously opened and has an existing state. This means that the data in Form 1 may be out of date, if it was changed by the save-to-database in Form 2. If you want Form 1 to automatically update to display the changed data from Form 2, then Form 1 must have [ForceRefresh] set to True.

The [ForceRefresh] option is set in the Menu data source that is used to determine which form displays in the Embedded Form component.

Indicating that forms have unsaved changes

If a child form has unsaved changes, an asterisk displays on the Menu component next to the menu item associated with the child form. This is intended to let the form user know that they need to execute a save on that child form.

This display is necessary when using a manual save method, because users can switch from child form to child form without saving changes. The user must switch back to each unsaved child form and execute a save (either from the parent or the child, depending on how the forms are configured).

When using the automatic save method, only the currently visible child form can ever be flagged as having unsaved changes. It is not possible for the user to switch to another form without saving their changes in the current form first. If the save has errors, the user is prevented from moving to another child form.

Child forms are flagged as having unsaved changes when changes have been submitted back to the source file but no save-to-database has occurred. For example:

The user selects a value using a ComboBox component in a child form.
The ComboBox component is set to auto-submit, so the changed value is submitted back to the source file and a form update occurs.
Axiom Software now detects that the source file has been changed but a save-to-database has not occurred. Keep in mind that Axiom Software doesn't know whether the change actually affects the save-to-database. Any change to the source file will cause it to be flagged as having unsaved changes.
The menu item that corresponds to the child form now becomes flagged with an asterisk. The asterisk will remain until a save-to-database is executed on the child form.

Keep in mind that because the Menu component is in the parent form, the parent form must be updated in order for the asterisk to show on the menu. Therefore, if an update is triggered in the currently visible child form but Refresh Parent Form is not enabled for the Embedded Form component, the parent form will not update and no asterisk will show on the menu. Once the parent form is updated, the asterisk will show (assuming that the save-to-database still has not occurred).