Add a Get Dirty Data Status Action

Use a Get Dirty Data Status action to check if any of the values have changed for the tracked variables within a particular scope (application, flow, page, fragment, layout), within any contained flows, pages, fragments, and layouts, and within any extensions of them. Tracked variables outside of the scope for which the check is done aren't considered. For example, in this image, both variables defined at the page level (their scope), have their Dirty Data Behavior property set to Track:

Description of the illustration jsac-variable-dirty-data.png

Whenever the value for any of these tracked variables changes, the dirty data status for their scope (referred to as context in code) is automatically changed from 'notDirty' to 'dirty'. And, if any tracked variables are defined for a layout, fragment, or extension of this page, and one of those variables changes, the page's dirty data status is also automatically set to 'dirty'. To reset the scope's dirty data status back to 'notDirty', use the Reset Dirty Status action.

When checking the dirty data status of a particular scope and its subscopes, it’s the scope from which the action chain is called that matters, not the scope in which the action chain is defined. For instance, if a page event initiates a flow or a page action chain with a Get Dirty Data Status action, the Get Dirty Data Status action returns that page's dirty data status, because the action chain is called from the page.

This functionality works with all data types except Service Data Providers (SDPs). You'll have to handle tracking value changes for SDPs manually, if needed.

For information about this action in the Oracle Visual Builder Page Model Reference, see Get Dirty Data Status.

Get Dirty Data Status Action vs Dirty Data Status Property

The Get Dirty Data Status action is used to check the dirty data status of a scope's tracked variables, so you can do things like implement a Save button that checks if a page actually has dirty data before posting its data to a database. The action doesn't take into consideration the consequences of navigating away from the page. If you want to check if navigating away from a page will result in the tracked variables losing their data, use the page's vbBeforeExit event listener. This event listener is triggered by navigating away from the page, and it starts an associated action chain that's passed an event parameter with a dirtyDataStatus property. Here's an example of an action chain that's started by a page's vbBeforeExit event listener, which doesn't allow navigating away from the page if the tracked variables will lose their data:

Description of the illustration jsac-dirty-data-exit-event-action-chain.png

The event.dirtyDataStatus property, unlike the Get Dirty Data Status action, does consider the effect that navigating away from the page would have on the tracked variables. The property is set to 'dirty' if navigating away from the page will cause the tracked variables to lose their data, otherwise, it's set to 'notDirty'. Variables within a scope retain their values as long as the destination of the user's navigation is within the scope or its subscopes. For instance, variables defined for a flow retain their values when a user navigates to a different page in the same flow, but not when a user navigates to a page in a different flow. Variables defined for a page do not retain their values when a user navigates to a different page in the same or a different flow.

Example:

This example shows an Add Employee page for adding a new employee's information. The page has two fields, one for a name and one for a birthdate, and their dirty data status needs to be tracked. The page also has a Save, Cancel, and Go to Home Page button. When the Save button is clicked, the employee's information is posted to storage.

Description of the illustration jsac-personal-info-form.png

The name and birthdate components are bound to page variables to hold their values:

Description of the illustration jsac-dirty-data-bind-component.png

To add dirty data functionality to this example:

1. Set the page variables' Dirty Data Behavior property to "Track".
2. For the Save button's action chain, add a Get Dirty Data Status action to check if the page actually has dirty data (unsaved changes) before posting the new employee's information to storage.
3. To warn users of unsaved changes due to navigating away from the page, add a vbBeforeExit event listener and use the event parameter's dirtyDataStatus property to check if navigation away from the page will result in the tracked page variables losing their data.
4. For the Cancel button's action chain, which navigates to the home page, add a Reset Dirty Data Status action to reset the page's dirty data status. This is needed for the vbBeforeExit event listener's action chain to allow the navigation to the home page when there is dirty data.

To begin:

1. Go to the page's Variables tab and set the page variables' Dirty Data Behavior property to Track:
   
   
   Description of the illustration jsac-dirty-data-info-change-variables.png
   
   
2. To add the dirty data functionality to the Save button's action chain, to check if there's actually dirty data before posting:
   1. Go the Save button's action chain. Here's an example, which passes a new employee's information to an action chain that posts the data to storage:
      
      
      Description of the illustration jsac-dirtydata-action-chain.png
      
      
   2. Add a Get Dirty Data Status action to the top of the action chain.
   3. Wrap the code for posting the new employee's data in an If action to check if there's dirty data to post. If there's no dirty data, do nothing.
   4. At the end of the If action's code, add a Reset Dirty Data Status action to reset the dirty data status back to 'notDirty'.

   Here's the action chain with the added dirty data functionality:
   
   Description of the illustration jsac-dirtydata-action-check.png
   

3. Next, we need to create a vbBeforeExit event listener to listen for when a user tries to navigate away from the page, which includes using the browser's Back and Forward buttons. If there are unsaved changes, a notification will warn the user of the unsaved changes and prevent the navigation. The event listener's action chain will be automatically passed an event object with a dirtyDataStatus property to check if the navigation away from the page will result in the tracked page variables losing their data.

   To begin:

   1. Open the Event Listeners tab and click the + Event Listener button to create a new event listener.
   2. Select vbBeforeExit, which starts its associated action chain whenever a user tries to navigate away from the page. Click Next:
      
      
      Description of the illustration jsac-dirty-data-exit-event.png
      
      

      We now need to create the action chain that's started by this event listener.

   3. On the Select Action Chain step of the Create Event Listener wizard, select the Create Page Action Chain option, under Page Action Chains. Click Finish.
      
      
      Description of the illustration jsac-dirty-data-exit-listener-action.png
      
      
   4. Back on the Event Listeners tab, hover over the new event listener that you just created and click the Go to Action Chain link that appears:
      
      
      Description of the illustration jsac-dirty-data-exit-event-action-link.png
      
      

      You're taken to the Action Chain editor to create the action chain that warns the user of unsaved changes.

   5. Add an If action to check if the navigation away from the page results in the tracked variables losing their data.

      Use the event parameter that was passed to the action chain, which has a dirtyDataStatus property. The property is set to 'dirty' if there will be lost tracked data, otherwise it's set to 'notDirty'.

   6. To handle the case in which the navigation results in a lose of tracked data, within the If action, add a Fire Notification action to notify the user of unsaved changes. To prevent the navigation away from the page, add a Return action to return the return object with its cancelled property set to true.
   7. To handle the case in which there is no dirty data, return the return object with its cancelled property set to false.

      Here's the completed action chain:
      
      Description of the illustration jsac-dirty-data-exit-event-action-chain.png
      

4. Finally, go to the Cancel button's action chain, which navigates to the home page. Add a Reset Dirty Data Status action to reset the page's dirty data status back to 'notDirty'. This is needed in case there's dirty data, which would prevent the vbBeforeExit event listener's action chain from allowing the navigation to the home page.
   
   
   Description of the illustration jsac-dirtydata-cancel-button.png