Skip to main content

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 Action

    When the user clicks the Save Action in the Header, the FormStation will perform a save operation. 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.

save notification

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.

Actions​

The FormStation provides actions in the Header that can be used to interact with the form. The undo action will reset the values in the FormStation to the values provided in the initialData prop. The save action will save the current values in the FormStation.

actions

Save Indicator (deprecated)​

warning

This feature is deprecated. When using the latest versions of the UI library the FormStation component will add a save button to the header of the form station.

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.

indicator states

Title Indication​

The title in the 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.

dirty title