With the disclaimer out of the way we’ll get down to business.  Our goal here is to produce a close confirmation popup when a user accidentally attempts to navigate away from our Flex app.  Examples of “navigating away from our Flex app” include: clicking the refresh, back or forward button, clicking a bookmark or favorite, or typing a new url in the address bar.  Additionally we’ll disable the prompt when the user intentionally navigates away from our Flex app; when logging out for example.  To accomplish this we’ll make use of the Javascript onbeforeunload event and Flex/Flash’s ExternalInterface package.

At this point I feel it’s important to note that doing what are about to implement is generally considered bad form for websites.  If I, as a user, want to leave a page I’d damn well better be able to with no hassle.  A Flex app is usually not a typical website however, rather it is an application running inside a web browser and when you close an application like Word with unsaved data you always get a confirmation dialog.

It’s my opinion that displaying a close confirmation for a Flex app is good form for two reasons.  The first is that RIAs are meant to be similar to desktop applications and any half decent desktop application is going to have you confirm closing the application if you have unsaved information.  The second is that, in being more like a desktop app, an RIA subverts the way users typically interact with web sites and web apps.  For most Flex apps the back and refresh buttons can cause havoc so throwing up a confirmation dialog when these buttons are clicked can enhance your application.

So we’ve made up our minds that we’re adding the close confirmation popup now lets get to it!

The Javascript

The first thing we need is some Javascript that will allow us to work with the onbeforeunload event.  Specifically we’ll need:

• A flag to indicate whether or not the popup should be displayed
• A variable to hold the text we want displayed in the popup
• A function to set the flag
• A function to set the prompt text

Here’s my Javascript object, FlexOnBeforeUnload that encapsulates all of this:

var FlexOnBeforeUnload = {

   /**
    * Flag indicating the user should be prompted each
    * time they attempt to navigate away from or refresh
    * the Admin HTML page.
    */
   prompt: true,

   promptText: "Refreshing or leaving this page will cause you "
             + "to lose any unsaved data.\n"
             + "Are you sure you want to leave?",

   /**
    * Sets the value of "prompt"
    */
   setPrompt: function (value) {
      if (value) {
         FlexOnBeforeUnload.prompt = true;
      } else if (!value) {
         FlexOnBeforeUnload.prompt = false;
      }
   }

   /**
    * Sets the value of "promptText"
    */
   setPromptText: function (value) {
      FlexOnBeforeUnload.promptText = value;
   }
};

Using Javascript we can access prompt and priompText directly however the ExternalInterface package in Flex only allows you to make calls to Javascript functions — you cannot use it to access variables directly. Besides accessor functions are good practice.

SetPrompt will take a boolean value and assign it to prompt. Setting prompt to true will cause the close confirmation to be displayed when a user attempts to navigate away from your Flex app. Setting prompt to false will allow users to navigate away without any nagging.

SetPromptText will allow you to change the text displayed in your confirmation dialog. Unfortunately you have very little control over the text displayed in the confirmation dialog. The dialog will always display “Are you sure you want to navigate away from this page?” and “Press OK to continue, or Cancel to stay on the current page.” along with the OK and Cancel buttons. The only thing you can customize is the text that appears between “Are you sure…” and “Press OK…”.

In the above pic you can see that “Refreshing or leaving this page will cause you to lose any unsaved data. Are you sure you want to leave?”, the default promptText, is displayed in the close dialog. Now that we have our Javascript object we’ll save it in a file called flex-onbeforeunload.js.

Now open up your HTML wrapper (the HTML page that loads your Flex app) and include flex-onbeforeunload.js in the head:

<!-- Assumes the JS file is located in the same folder as the wrapper. -->
<script src="flex-onbeforeunload.js" language="javascript">
</script>

After that you are ready to setup the onbeforeunload event handler.  In a script block beneath the include we just added add the following:

window.onbeforeunload = function(e) {
   if (FlexOnBeforeUnload.prompt) {
      return FlexOnBeforeUnload.promptText;
   }
}

This code will be executed prior to the page being unloaded (onbeforeunload even). If FlexOnBeforeUnload.prompt is true the close confirmation will be displayed with our promptText. If FlexOnBeforeUnload.prompt is false the function returns nothing and no confirmation will be shown.

The Actionscript

Since the default for FlexOnBeforeUnload.prompt is true the close confirmation dialog will always be shown unless we take some action to prevent it. Enter ExternalInterface, a class used to facilitate communication between Actionscript and Flash Player and the HTML wrapper. In other words, ExternalInterface allows Actionscript to talk with Javascript and vice versa, though in our situation we’ll only being going from Actionscript to Javascript.

For our purposes we are interested in two parts of ExternalInterface, the call method and the available property.  ExternalInterface.available “[i]ndicates whether this player is in a container that offers an external interface.”  In English, if ExternalInterface.available is true we can use ExternalInterface.  ExternalInterface.call allows us to call Javascript functions in the wrapper.  To use ExternalInterface.call you pass in the name of the Javascript function as a string and then any parameters the Javascript function takes as a comma-separated list.

Earlier I gave the example of logout as a situation where you would probably not want to show a close confirmation popup.  Using ExternalInterface you can disable the confirmation for situations such as this.  To disable the confirmation popup add the following to your logout code in Flex Builder:

// Make sure ExternalInterface is available
if (ExternalInterface.available)
{
   // Set prompt to false, disabling the close confirmation
   ExternalInterface.call("FlexOnBeforeUnload.setPrompt", false);
}
else
{
   // Optionally handle the situation where ExternalInterface
   // is not available.
}

This will set the value of FlexOnBeforeUnload.prompt to false, disabling the close confirmation. Similarly you can change the prompt text:

// Make sure ExternalInterface is available
if (ExternalInterface.available)
{
   // Set prompt to false, disabling the close confirmation
   ExternalInterface.call("FlexOnBeforeUnload.setPromptText",
                                "Different prompt text.");
}
else
{
   // Optionally handle the situation where ExternalInterface
   // is not available.
}

Beer Near Here Desktop makes use of three libraries, all of which are freely available:

1. as3corelib for hashing methods
2. Alex Uhlmann’s Distortion Effects for distortion effects
3. My own Flex Library, available here.

Now there are a number of ways to link these libraries into the BNHD project, but it all pretty much boils down to two methods.  Either I link the project into BNHD’s build path or I copy the SWC that the library produces into BNHD’s build path.  My experience has been that neither of these methods is really better than the other and using one over the other largely depends on the nature of the library itself.

Often when people distribute their Flex code it is in the form of a SWC, so there will be plenty of cases where you’ll simply have to use this method.  In the case of as3corelib, I downloaded the source so that I could disable the packages I didn’t need, but once I compiled a SWC for the project I included that into BNHD’s build path rather than the as3corelib project itself.  As3corelib isn’t going to change beyond my initial modifications and once the SWC is exported I just copy and pasted into into BNHD’s libs folder.  This allows the BNHD project to be more self-contained as it now no longer relies on the separate as3corelib project.  I then repeated all of this for the distortion effects library.

My own personal Flex library is another matter.  It’s very immature with few components and effects so as I work on projects like Beer Near Here Desktop I typically pull out a few of the more useful components and put them into my library.  All this is to say, my library changes fairly frequently.  In this case I’ve found simply adding the project rather than the SWC it produces to be a faster solution.  The downside is that the BNHD project now relies on an external project, so both will have to be present and accounted for in Flex Builder in order to work with BNHD.  Doing this also alleviates the need to continually rebuild my library project during development.

To summarize so far, external libraries, like those listed above should be placed into their own Flex Library Projects.  Any library project that will remain static throughout development should be compiled into a SWC and copied into the main project’s lib folder.  Any library project that will change frequently should be linked into the main project’s build path.  Doing all this will prevent you from spending many minutes (or hours) watching your Flex projects compile all while keeping things nicely organized.  I believe this is called a “win-win”.

The actual Beer Near Here Desktop project organization is very simple.  In the project’s source folder I have three files: main.mxml, main-app.xml and style.css.  The first two are the files that define any AIR app and style.css is the master stylesheet for the entire application.  In the source folder I also have an images folder that contains all of the apps images and net.beernearhere folder that contains all the classes and components and whatnots specific to Beer Near Here Desktop.

I really cannot stress enough how much more efficient Flex Builder became once I started shunting things off into libraries and strongly recommend you do the same if you’re not already.  As for how those projects should be organized, I leave that up to you.  I showed how the BNHD project is setup because I’ll reference it later, but it’s pretty standard and really to each his (or her) own.

Read Part 4.

The two prongs are rather simple: move your Actionscript classes and MXML components to a library project, and set Flex Builder to only compile the module or modules you are currently working with rather than all modules for the project.  I know it sounds really simple but it took me about five hours to dig around Adobe’s documentation and piece everything together.  The payoff has definitely been worth is though with compile times down to about twenty seconds, or about 10% of the previous time.  In the hope of saving others a few gray hairs I’ve put together a handy little guide.

I started by creating a separate library project for all my classes and reusable components.  The official Adobe docs on this are here (for Flex 3).  There are a lot of benefits to doing this besides decreased compile times.  Having all your Actionscript classes and MXML components in a library project allows you to easily reuse them in multiple projects.  Taking this a step further you can also add other libraries to a library project.  So rather than link multiple libraries into your Flex project you could set up a library to do this and link that single library into your project.  In the end library projects are quite useful for many things.  Use them.

But how, you ask?  The process is pretty much identical to creating a standard Flex project, just select File > New > Flex Library Project and follow along through the wizard.  Once you have your project setup just add your code and compile it into a .swc file (if you have Build Automatically checked Flex Builder will do this for you automagically).  You then link this swc into your main project’s build path. To add the swc to your project’s build path:

1. Right-click your project in the Flex Navigator, choose Properties.
2. In the Properties window select Flex Build Path.
3. Click the Library Path tab.
4. Click the Add SWC… button.
5. Browse and find your library’s swc.  By default this is in the bin folder of your library project.

You can now import your classes and components just as if they were physically in the project.  Using a seprate library project decreases compile time because now your classes and components are only being recompiled when you make changes to the library project.

One thing to consider when adding your library to the Build Path of your project is the library’s Link Type (you can see this by clicking the rollout tab next to you library in the list of build path libraries).  There are three options; I went with Runtime Shared Library (RSL).  As far as I could tell there was no substantial difference in compile times with the three link types, but RSL has the advantage of seriously reducing module file size.  I went from having an average module weigh in around 230KB to around 70KB.  The catch is that the library is exported as a separate swf that needs to be uploaded along with your application and module swfs.  The library swf is then loaded in by the application at start up, making the initial application start up a tad slower but drastically increasing load speeds for modules.

Employing runtime shared libraries offered a nice performance boost both for my application’s compile times and load times but selectively compiling my app’s modules is what really decimated compile times.  To select which modules to compile:

1. Right-click your project in the Flex Navigator, choose Properties.
2. In the Properties window select Flex Modules.
3. You should see a list of all the modules in your application.  Select the ones you aren’t working with and click the Remove button.

When you need to add a module to compile click the Add… button in the Flex Modules window and browse for it.  Any new modules you add should automatically be added to the list to compile.  There are two downsides to this.  The first is that anytime you make a change to the list of modules Flex has to rebuild your project’s workspace which can take some time.  The second is that it’s a complete pain in the ass to add modules back into the compile list since you can only add one at a time and you have to browse through a few windows to do so.  In practice though, you’re not likely to be constantly adding and removing all your modules so this second point is probably moot.

And that’s it.  As I said at the top I saw a 90% decrease in compile times just by doing these two things.  I’ve also been far more productive as a result since I don’t have an interminable wait while debugging.

The component has a robust feature set providing multiple move options and customization for nearly everything.  I’ve created a project page for this component here.  There you can find a demo and download the source for use in your own projects.