Imagine this scenario:  You've developed and deployed a beautiful Valence-based customer order entry app to replace your company's former green screen program.  Your customer service users can now easily launch the app to initiate new orders, quickly fill out the mandatory header fields and enter item details for the order.  All is well! But then one day, while in the middle of entering an exceptionally large order, one of your users gets distracted and inadvertently closes the order entry app before hitting Save.  Poof!  All their data entry work is gone and they have to start over.  

D'oh! Fortunately you can easily add logic to your Valence apps to trap unintended exits from apps like this prior to saving. Here's how... The key is to use the Valence Portal's setPromptBeforeClose utility method to trap unexpected exits from your app. When your app places the user into an "edit" mode, i.e. when adding a new record or editing an existing one, your app's controller can call this method to activate the trap as follows:

var key = Ext.getUrlParam('key');

Ext.getUrlParam is a Valence-supplied method for accessing the url parameters, with "key" representing a unique identifier to the app tab.  This key value is passed as the first parameter to setPromptBeforeClose, followed by a boolean value of "true" to activate the trap logic.  From that point on, any attempt to close the app would cause the following default message to appear:


You can refine the message contents by replacing the "true" param with an object containing a replacement title and message, like this:

var key = Ext.getUrlParam('key');
Valence.util.App.setPromptBeforeClose(key, {
  title: 'Are you crazy?',
  msg: 'Leaving this app means all your hard work will be lost.  
        Are you sure you want to lose your changes?'

You can also have the portal place a visual "unsaved changes" indicator into the app tab by including "visualIndicator: true" in the object. Once the user has actually saved their changes, or cancelled out of the changes, you should deactivate the trap by passing "false" as the second parm:

var key = Ext.getUrlParam('key');

Just another way to help save your users from themselves!