Saving
Overview
The FormStation is responsible for providing features that allow data editing. It attempts to perform the save operation - provided that there are changes - on the following user actions:
-
Navigating away from the station
When the user tries to navigate away from the station, the FormStation will pause the navigation and perform a save operation. If the save operation is successful, the navigation will continue. If the save operation fails, the navigation will be aborted and an error message will be displayed. The user will not be able to navigate away from the station unless the form is in a valid state.
-
Interacting with the Action Panel
When the user clicks on an action in the Action Panel, the FormStation will perform a save operation. If the save operation is successful, the action will be executed. If the save operation fails, an error message will be displayed and the action will not be executed.
-
Interacting with the Save Indicator/Button
When the user clicks the Save Indicator in the Header, the FormStation will perform a save operation. If the save operation is successful, the save indicator will be updated to reflect the new state of the form. If the save operation fails, an error message will be displayed.
During a save operation, the FormStation will perform a validation using the validationSchema prop. If the validation is successful, the saveData prop will be called with the current values, initial data of the form and helpers from Formik. If the validation fails, the FormStation will display an error message and the save operation will be aborted.
|
Note
|
validationSchema is an optional prop. If it is not provided, the FormStation will not perform a validation before saving.
|
If an error is thrown during the save operation, the FormStation will display an error as a Station Message.
|
Tip
|
You can customize the error message by throwing an object of the StationError type.
|
Once the save operation is complete, the FormStation will show a notification to the user.
Understanding when Form’s data is changed (and needs saving)
Formik Context
The FormStation uses Formik as its state management library. This creates a context that is used to manage the state of the form. The Formik context is used to provide the state of the form to the components that need it. The helpers from Formik are used to determine the dirty state of the form and provide features such as validation, undo and saving.
Dirty State
A form is considered dirty when the current data in the form is different from the data provided to the initialData prop of the FormStation component. The dirty state is used to determine if the form has unsaved changes.
Undo
An undo operation is available when the form is dirty. It is displayed as an action in the FormStation Header. The undo action will reset the values in the FormStation to the values provided in the initialData prop.
Save Indicator
The Mosaic layout provides a Save Indicator in the Header which is used to display the state of the form. The state of the form can be one of the following:
-
Inactive - the form is not dirty and there are no unsaved changes.
-
Dirty - the form is dirty and there are unsaved changes. In this state, the Save Indicator can be clicked to perform a save operation.
-
Saving - the form is being saved.
Title Indication
The title in the FormStation Header and Browser Tab will be updated to reflect the dirty state of the form. The title will be updated to include an asterisk (*) when the form is dirty.
