Track Variables to Detect Unsaved Changes

You can track changes in a variable's state as a way to detect unsaved changes in your application. 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.

Enable a Variable for Tracking

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.

1. Open the Variables tab and access the variable whose state you want to track.
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.jpg
   
   

Query Tracked Variables for Changed State

With variables enabled for tracking, you can use the Get Dirty Data Status action to query changes in variable state and take appropriate action.

1. Open the Action Chains tab in the scope appropriate for your tracked variable, then create an action chain or open an existing one.
   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.
2. From the Actions palette, double click the Get Dirty Data Status action or drag and drop it onto the canvas.
   
   
   Description of the illustration getdirtydatastatus-dragaction.jpg
   
   
3. Optional: In the action's Properties pane, give the action a unique ID that can be used for logging and action chain tests and add a description.
4. Update the Store Result In property to more clearly identify the auto-generated variable that will store the value returned by the Get Dirty Data Status action (for example, getDirtyDataStatusResultForNameInput).
5. Add one or more actions you want to trigger in response to the Get Dirty Data Status call. For example, you might add the If action to determine what action to take depending on the results of the Get Dirty Data Status action. The values that can be returned as results are either status: 'dirty' or status: 'notDirty'.
   • If the Get Dirty Data Status action returns a status: 'dirty', you might add a Fire Notification action to display a warning about unsaved changes, then follow it with a Return action to stop navigation by returning an object with the property "cancelled" set to "true" (as shown here):
     
     
     Description of the illustration dirty-data-actionchain-ifaction.png
     
     
   • If the Get Dirty Data Status action returns a status: 'notDirty', you might add another Return action, this time with the "cancelled" property set to "false", to allow users to navigate away from the page.
     
     
     Description of the illustration dirty-data-actionchain-returnaction.png
     
     

   For detailed steps on building this example action chain, see Add a Get Dirty Data Status Action.

Reset State for Tracked Variables

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:

• Let's 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.
• Let's say you have a page that allow 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.

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

To add the Reset Dirty Data Status action to an action chain:

1. Open the Action Chains tab for the action chain that queries your tracked variables.
2. From the Actions palette, double click the Reset Dirty Data Status action or drag and drop it onto the canvas.
   
   
   Description of the illustration dirty-data-actionchain-reset.png
   
   
   To add the action to follow another, drop it onto the bottom edge of the previous action. For example, when you have an Assign Variable action that assigns a default value to a variable, you might follow that action with the Reset Dirty Data Status action, so the assignment isn't considered dirty.
   

   
   Description of the illustration dirty-data-actionchain-reset-assignvar.png

   
   
3. Optional: In the action's Properties pane, enter a unique ID that can be used for logging and action chain tests and a description.
4. Optional: Add the action you want to trigger after the Reset Dirty Data Status call, for example, you might add a Navigate action to allows users to navigate to another page.