Home >

AX2135

Saving data from an Axiom form

You can save data to the Axiom Software database from an Axiom form. For example, you might want to allow users to save comments about the data in the form, or use the form as a data input tool.

Only data saves are supported in Axiom forms. It is not possible to save the source file when it is being viewed as an Axiom form.

Configuring an Axiom form to save data

To set up an Axiom form to save data, you must do the following:

• Configure the source file for the Axiom form to save to the database. This is the same setup that you would use for any Axiom spreadsheet file—for example, to enable Save Type 1 for a report or for a plan file template. However, note that you may not want to enable Zero on Save in this environment, since data from previous saves are not persistent in the file.

• Configure the Axiom form with interactive components to collect user input, such as a combo box or a text box, or a formatted grid with one or more editable cells. The save-to-database process and the interactive component must interact in some way in the source file, so that when the user changes the interactive component in the Axiom form and the updated state is submitted back to the source file, the data to be saved to the database updates in response.

• Configure the Axiom form to trigger a save-to-database when updated data is submitted to the source file. You can do this in two different ways, depending on how you want the data to be collected and saved.

  • If the save should occur after a particular component is changed, then that component should be configured to Auto-Submit and to Save on Submit. For example, if you want the save to occur after the user has input text into a particular text box.

  • If the save should only occur when the user decides that they are ready to save, then you should use a Button component that is configured to Save on Submit. For example, if you are using a formatted grid where the user is entering inputs into multiple cells, you probably don't want to trigger a save after each input—instead you want to wait until the user has completed all of their inputs, and then the user can click the button to save their changes.

  When Save on Submit is enabled, the save-to-database always occurs after values are submitted back to the source file and a full data refresh is performed (including running Axiom queries). For more information on the order of the process, see Update and save behavior for Axiom forms.

IMPORTANT: The source file for the Axiom form is not saved when a save-to-database is triggered from the Axiom form—only data can be saved when using this environment. Therefore if the data saved by the user is expected to be displayed in the Axiom form, then you must configure the form so that any saved data will be queried back into the sheet via Axiom queries or GetData functions.

If an Axiom query in the file would be impacted by the save-to-database, you can use the refresh option Refresh after save data to automatically refresh the query after the save occurs. For example, if the save-to-database adds or updates a record in a particular table, and you are using an Axiom query to display the contents of that table in the Axiom form, you would want to enable this option so that the user does not have to manually refresh the form to see the changed data. Axiom functions such as GetData are automatically calculated after a save-to-database and do not need any special settings to display the changed data.

Save-to-database example

The Axiom form contains a text box where a user can type in a comment about the data in the form. To enable this to save to the database, it could be set up as follows:

• Set up Save Type 1 in the source file to save the comment to the appropriate place in the database. You may be able to assume the necessary keys for the save within the file, or the user may need to specify the appropriate keys in the Axiom form—for example, using other text boxes or, more likely, combo boxes that present the appropriate choices of department and account (or whatever the keys are in this scenario).

• Set up a Text Box component within the Axiom form, where the user will enter their comment. You may also want to define placeholder text for the Text property; in this case, something like "Enter a comment..."

• Set up a Button component within the Axiom form, and enable Save on Submit for the button. You may want to change the text of the button to something like "Save" or "Update." (Optionally you could configure the text box to Auto-Submit and Save on Submit instead, but only if it is a single-line text box.)

• In the source file, in the cell that is configured to save the comment to the database, enter a cell reference to the Text property of the component.

  Alternatively, you can use an indirect cell reference in the Text property of the component, so that it points to the desired cell—such as [Sheet1!C15]. When using an indirect cell reference, the Text Box component displays the text from the designated cell, and writes the updated text to the designated cell (instead of reading and writing to the Text property field directly).

When the user views the Axiom form, they will see the text box with the placeholder text "Enter a comment...". They can choose to type a comment into the text box. When they click the button to submit, then the comment will be written back to the Text cell of the text box settings (or to the designated cell in the file if an indirect cell reference is used). The file is refreshed and then a save-to-database is performed. The comment is now saved to the database.

It is important to keep in mind that the source file is not saved; only the data is saved. The next time this user opened the same Axiom form, they would see the default "Enter a comment..." again. To work around this, you could query the previously saved value into the form, and then use a formula to display that value in the text box by default.

Component enablement and saving data

If Save on Submit is enabled for a component, then that component will only be interactive in the form if a save-to-database process is enabled in the source file on the Control Sheet (and if the user has Allow Save Data security permissions to the file). If a save-to-database is not enabled (or if the user does not have permission to save data), then the component is disabled in the form because it cannot do what it is configured to do (save data). You can dynamically enable or disable the save-to-database based on some condition (for example, checking that all required fields have inputs) to enable the component and therefore allow the user to save.

If a save-to-database process is enabled in the source file, and if changed values have been submitted to the form but no save has yet occurred, then a warning message will display to the user if they attempt to close the form. This warning message informs the user that they have made changes in the form that will not be saved. The user can choose to return to the form to complete their save, or continue closing the form.

NOTE: This "unsaved changes" warning will occur even if no components currently have Save on Submit enabled, or if a component does have Save on Submit enabled but the component itself is not currently enabled. The only way to avoid the warning is to disable the save-to-database process up until the point when the save would be valid, and the user should be warned about losing their data.

User messaging when saving data

There are several layers of user messaging available when saving data to the database from an Axiom form. Some of these layers can be modified at the Axiom form level.

Messaging	Description
Prompt the user before saving	If you want to prompt the user to confirm that they want to perform the save, then you can define a Confirmation Message for the Button component. When the user clicks the button, the defined message will display and the user will have the option to continue or cancel. If canceled, then the form is not refreshed and no save-to-database occurs. This option is only available when using a Button component to perform the save. If you are using an interactive component with Auto-Submit and Save on Submit, then there is no opportunity to prompt the user before saving; the refresh and save will occur automatically.
Display confirmation of successful save	By default, if the save-to-database is successful, no confirmation dialog displays to the user. The user's only indication of the save-to-database is the yellow status message that displays in the lower left-hand corner of the form while the save is processing. If desired, you can configure the form so that an explicit confirmation message does display after a successful save. In the Form Assistant task pane or the Form Designer dialog, click Edit Form Properties to open the Form Properties dialog, and then select the check box for Save Data Confirmation. (Alternatively, this setting can be enabled or disabled on the Form Control Sheet using the Show Save Data Confirmation property.) If this setting is enabled, then a save-to-database confirmation message displays to the user in a dialog. This message simply informs the user that the save completed successfully; it does not contain any details about records saved. The user must dismiss the dialog to return to the form.
Display error messages from the save	If any errors occur during the save process, these error messages display to the user in a dialog. The error messages are similar to those displayed in the Excel Client and the Windows Client, however, the specific cell addresses are not displayed because they would not be meaningful to the Axiom form user.
Display warning message for unsaved changes	If changes have been made in the Axiom form but no save has occurred, a warning message displays to the user if they attempt to close the Axiom form. The user can choose to continue closing the form or return to the form. This warning only occurs if both of the following are true: The form source file has a save-to-database enabled on the control sheet. Changed values have been submitted back to the source file but no save has been performed (in other words, the source file has unsaved changes). If changes have been made in the Axiom form but none of those changes have been submitted back to the source file, then no warning message will display because Axiom Software is not aware of any changes.