Track Variables to Detect Unsaved Changes

You can track changes in a variable's state as a way to detect unsaved changes in your App UI. Tracking a variable marks it as "dirty" any time its value changes, that is, when its current value differs from its initial value. You can then build an action chain to query for dirty variables and trigger a suitable response.

Suppose you want to notify users of unsaved changes before they leave a page, here's what you might do: set a page variable for tracking, then build an action chain as follows:

• Use the Get Dirty Data Status action to query for dirty variables in the action's current scope as well as in any containers within
• Take some action if dirty variables exist, for example, use the Fire Notification action to display a message. Note that a variable whose value was updated but changed back to its initial value is not considered dirty.

To enable a variable for tracking:

1. Open the Variables tab and access the variable whose state you want to track.
   You can track changes in a variable's state for all types of variables—except SDP variables and constants—in an app, flow, page, fragment, and layout.
2. In the variable's Properties pane, select Track from the Dirty Data Behavior list. The default is None, indicating that the variable's state is not tracked.
   
   
   Description of the illustration variable-dirty-data-appui.png
   
   
3. With the variable enabled for tracking, use the Get Dirty Data Status action to query changes in variable state and take appropriate action.

   Because the Get Dirty Data Status action queries for dirty variables in its current scope as well as in any containers within, make sure the scope of its action chain is correct for your tracked variable. For example, when you want to check for unsaved changes on a page, the tracked variable and corresponding action chain can be defined at the page level. If the page contains fragments and/or layouts, those will be checked as well. Further, if the page and/or its fragments/layouts are extendable, tracked variables in those extensions will also be checked.

   See Add a Get Dirty Data Status Action for more information.

4. When you don't want a tracked variable's changes to be flagged as dirty, you can reset its dirty state using the Reset Dirty Data Status action. Here are a few scenarios when you might want to do this:
   • Say a variable's initial value is "0" and a REST call changes it to "1". When you don't want this change to be tracked as dirty, calling the Reset Dirty Data Status action resets the variable's dirty data state such that "1" is considered the new initial value.
   • Say you have a page that allows users to save or cancel their changes. If users click a Cancel button to not save their changes, you might want to reset the tracked variable's state, so the change is no longer considered dirty.

   Note:

   Be aware that when you add the Reset Dirty Data Status action to an action chain, it resets the dirty state on all tracked variables in the scope where the action chain is invoked as well as any containers within. For example, if your action chain is defined at the page level, all tracked variables at the page level will be reset. If the page contains fragments and/or layouts, tracked variables in those scopes will also be reset. Further, if the page and/or its fragments/layouts are extendable and include tracked variables, those variables will be reset as well.

   Make sure the scope you define for the action chain that contains the Reset Dirty Data Status action is appropriate for your use case.

   See Add a Reset Dirty Data Status Action for more information.