A Real-World Scenario

Recently, I developd a PureMVC-based Flash game for a client. The application had to be multi-lingual and had to provide an auto-login option. After registration via an HTML form, the user is redirected to the page with the embedded SWF file. The locale information and the credentials are handed over to the game page as GET variables (with the password encrypted). A PHP script then generates the appropriate JavaScript code for SWFObject:

With the help of SWFObject the parameters are injected into the Flash file.

The Document Class

The Flash Main.as document class isn’t much different from a usual PureMVC document class except for extracting the flashVars object from the root.loaderInfo object’s parameters property and passing it to the ApplicationFacade’s startup() method as the second parameter:

Main.as

The ApplicationFacade

Now, what to do with the flashVars inside the ApplicationFacade? I prefer using multiple fine-granulated proxy classes for managing different portions of my application’s data model. Therefore I created two proxies, one for holding the locale information, the other one for keeping track of the login parameters. Both proxies are registered by PureMVC commands that are invoked inside the startup() method.

To get the big picture first, let’s take a look at the ApplicationFacade class before exploring the proxies and commands:

ApplicationFacade.as

Lines 27-28: The InitLocaleProxyCommand and the InitLoginProxyCommand are registered. These commands are responsible for populating the proxies. We will take a look at them shortly.

Lines 34-38: So far we haven’t checked if the flashVars object’s locale property is set at all. If it is empty the locale variable holds an empty string.

Line 40: LoginVO is a value object class that is used as the inner data structure of the LoginProxy. We will take a closer look at this helper class, too.

Lines 41-45: Similar to checking the flashVars object’s locale property, we examine the username and password properties.

Lines 47-48: The InitLocaleProxyCommand and the InitLoginProxyCommand are triggered by sending the notifications they were registered with.

Line 49: The application flow is continued with the usual PureMVC StartupCommand that takes care of registering the stage mediator, etc.

The Proxy Classes

In order to understand what the commands do with their payload, we need to look at the proxy classes first. The LocaleProxy’s data object is a string that simply contains the locale (e.g. “en_GB”):

LocaleProxy.as

The LoginProxy class is a little more complex. Not only is the inner data structure defined by a value object class (LoginVO), the proxy also provides a getter method that inspects the data object in order to decide if the application should try an auto-login.

LoginProxy.as

Lines 16-18: If the credentials have been passed to Flash via SWFObject the application is supposed to try an auto-login. If tryAutoLogin is false the user will be redirected to a login view inside the Flash movie.

The LoginVO class contains setter and getter methods for username and password.

LoginVO.as

Lines 36-39: The static method register() is supposed to be used in an AMF remoting environment. Since this post describes a pure AS3 approach we can’t rely on the RemoteClass meta tag which is only available in Flex. (Maybe I will blog on PureMVC and AMFPHP in another post.)

The Commands

Finally, here are the commands that process the FlashVars information and register the proxies.

InitLocaleProxyCommand.as

Lines 15-27: The locale is checked against a list of valid locales. If no valid value is found a default value is set.

There’s nothing special about the InitLoginProxyCommand, I post it here just for the sake of completeness:

InitLoginProxyCommand.as

After the LocaleProxy and the LoginProxy have been registered the StartupCommand (which I do not post here) takes control over the application flow by registering the StageMediator and so on.

I hope you found this post useful. Do share your thoughts and comments. Thanks for your time.

Part 1

1. Preparing the Project Space
2. The Resource Files: styles.css and data.xml

Part 2

1. The StartupMonitorProxy
2. The StartupResourceProxy
3. “Loaded” and “Failed” Notifications
4. Updating the Project Space
5. The ApplicationFacade
6. The StartupCommand
7. The Resource Proxies

Part 3

1. Preparing the View
2. The StageMediator
3. Testing the Demo
4. Conclusion

I closed the comments sections of the three tutorial parts. If you want to discuss the tutorial please add your comments to this introductory post. You can download the sample files from here (the ZIP archive includes a FlashDevelop project file).

And now let’s get started…

We are almost there. In the final step of this tutorial we will be creating a very simple view:

1. Create a file with the name StageMediator.as in the view folder.
2. Create a new folder inside the view folder and call it components.
3. Create two files in the components folder and name them SectionView.as and TitleView.as.

Here’s an updated screenshot of the project panel:

Both view components are not PureMVC-specific. Their only purpose is to display the CSS-formatted content from the XML file. The code of the view components is shown here without any comments.

TitleView

SectionView

The StageMediator

An instance of the StageMediator class has already been created and registered with the application inside the StartupCommand (see part 2):

The role of the StageMediator is to initialize the view once all resources have been loaded successfully. In a real-world project you would probably want to display some state information on the loading progress before creating the main view. To simplify things, we will be sending this information to the output panel using trace().

In our sample project the StageMediator not only declares an interest in the “Loaded” and “Failed” notifications for each resource, it also listens to various other notifications that are automatically sent by the monitor.

Lines 29-34: These notifications are generated by the monitor. For more details please refer to the StartupMonitorProxy API documentation.

Lines 35-40: These notifications are generated inside the resource proxies.

Line 71: The main view is only initialized if all resources have been loaded.

And, finally, here’s the class that starts it all (Main.as):

Testing the Demo

If you run our sample app, you should see three textfields that display the content from the XML file, all nicely formatted:

The output panel should display the following lines (don’t be confused by the fact that the “Site Data Loaded” message is spit out after the “>>> Loading Complete” message):

Loading StyleSheet...
Loading Progress: 50%
Loading Site Data...
StyleSheet Loaded
Loading Progress: 100%
>>> Loading Complete
Site Data Loaded


Now, in order to test that the Startup Manager is working properly, you can, for example, rename one of the resource files (styles.css, data.xml). In either case the utility should display a “Loading Finished Incomplete” message.

Conclusion

I hope this three-parts tutorial helped you to use the PureMVC Startup Manager in your own PureMVC projects. This utility is an excellent addition to the PureMVC framework, it’s very flexible and can greatly support you to organize the loading of resources and to correctly handle errors that might occur during startup.

A PureMVC-based application typically has a startup command that instantiates some basic proxies and mediators. In our sample project we want to load a CSS stylesheet and an XML file with content before allowing any user interaction (see part 1). The important thing here is to make sure that everything gets loaded in the proper order and is fully loaded before it is accessed. Here is where the StartupMonitorProxy steps in. This class is at the core of the Startup Manager utility.

The StartupMonitorProxy takes care of how the resource loading should be sequenced so that dependent resources are loaded in correct order. It also keeps track of the progress of the resource loading, and it knows when the resource loading is complete. The way you use the StartupMonitorProxy is pretty straightforward:

1. A single instance of the StartupMonitorProxy is registered which is usually referred to as the monitor.
2. Each startup resource is registered with the monitor, using the addResource() method.
3. The loading process is started by calling the monitor’s loadResources() method.

(For a more detailed description please refer to the excellent API documentation.)

Now let’s take a quick look at the other actors that are needed to make the startup utility work.

The StartupResourceProxy

For each startup resource the application must instantiate a StartupResourceProxy object. These objects are required only by the utility and must not be confused with the normal resource proxies that represent the data carrier objects of the model. The regular proxies are instantiated and registered with the application first. After that the StartupResourceProxy objects are instantiated, receiving the resource proxy instance and a separate startup resource name. The two proxy types are like twins, but they live in different worlds. We will shortly see what this looks like in code.

“Loaded” and “Failed” Notifications

In order to inform the monitor that a resource has been loaded successfully or that the resource load has failed, the application must register the utility commands StartupResourceLoadedCommand and StartupResourceFailedCommand. These commands are responsible for sending “Loaded” and “Failed” notifications to the monitor whereby the notification body identifies the particular resource.

Updating the Project Space

Before we continue with the actual ActionScript code, let’s create some more class files in our project space.

1. Create a file with the name StartupCommand.as in the controller folder.
2. Create three new files in the model folder and name them EntityProxy.as, SiteDataProxy.as, StyleSheetProxy.as.
3. Create a new folder vo under the model folder.
4. Create a file with the name SectionVO in the vo folder.

Your project panel should look like this now:

The ApplicationFacade

We are starting with the ApplicationFacade class (if you followed part 1 of this tutorial you can paste the code below into the already existing empty ApplicationFacade.as file). It pretty much looks like a typical PureMVC facade:

Lines 12-17: Three notification names are defined for each of both resources, the stylesheet (STYLE_SHEET_LOADING, STYLE_SHEET_LOADED, STYLE_SHEET_FAILED) and the site data (SITE_DATA_LOADING, SITE_DATA_LOADED, SITE_DATA_FAILED). Please note that the ..._LOADING notifications are not necessarily required by the Startup Manager utility, they are just sent as additional information, using the regular PureMVC sendNotification() method every time a load attempt is made.

Lines 33-37: The before mentioned utility commands are registered. It’s important that the commands are registered separately with the “Loaded” and “Failed” notification names for every single startup resource.

The StartupCommand

The StartupCommand is the place where we define the proxies and instantiate the StartupMonitorProxy object:

Lines 23-24: An instance of the StartupMonitorProxy class is created and registered with the application. The proxy is assigned to the private property _monitor.

Line 25: A default timeout is set. You can set individual timeout values for each startup resource. If you do not set timeouts on the resource level the monitor’s default timeout is used. (For more information on the use of timeouts take a look at the StartupResourceProxy API documentation.)

Lines 27-28: The proxies for the stylesheet and the site data are instantiated. Please note that they are typed as IStartupProxy because the proxies are supposed to implement the IStartupProxy interface in addition to the usual PureMVC IProxy interface. We will return to this topic when we look at the implementation of the proxies.

Lines 30-31: Like any other PureMVC proxy the styleSheetProxy and the siteDataProxy are registered with the application.

Lines 33-34: Whereas instances of the StyleSheetProxy and the SiteDataProxy are supposed to be used throughout the whole application, the rStyleSheetProxy and the rSiteDataProxy objects are only needed in the context of the startup utility.

Line 36: The dependency between the two resources is specified. The site data requires that the stylesheet must be loaded first.

Line 38: Calling loadResources() on the monitor instance triggers the loading of all startup resources.

Lines 41-47: This is a helper function that I borrowed from the Startup As Ordered demo. It creates and registers a StartupResourceProxy object and adds it to the monitor’s list of resources.

The Resource Proxies

Generally speaking, a proxy in a PureMVC-based application manages a piece of the data model. The same proxy might also be responsible for retrieving its data from a remote location during startup. The PureMVC Startup Manager utility supports this pattern by providing the IStartupProxy interface which strictly requires the implementation of a load() method. Any resource proxy that is part of the initial loading process monitored by the utility must implement this interface.

On the other hand, the proxies must work in the usual PureMVC environment where they are supposed to extend the framework’s Proxy class and to implement the IProxy interface. To make the resource proxies work in both contexts, the utitliy author uses an abstract class that facilitates the cooperation between the Startup Manager and the application. You can find this class in the Startup As Ordered demo, the class name is EntityProxy. It extends Proxy and implements IProxy like a normal PureMVC proxy. But this proxy class isn’t instantiated and registered with the application itself, it only serves as a helper class for the actual resource proxies. The resource proxies extend EntityProxy and implement IStartupProxy. This way they become part of both contexts.

Here’s the code of the EntityProxy class:

Lines 15-22: The sendLoadedNotification() method is a helper function that is used by the actual resource proxies to send “Loaded” or “Failed” notifications. These notifications are only sent if the Startup Manager hasn’t timed out the resource. In order to get the timeout information, the resource proxy’s “twin object” (srProxy) is retrieved. By the way, accessing this state information is the only reason why the StartupResourceProxy objects have been registered with the application in the StartupCommand class (see above, line 44: facade.registerProxy( r );). The utility itself does not require that they are registered with the PureMVC model.

The resource proxies finally implement the actual loading mechanisms. I hope you remember that the proxies in our sample project are responsible for loading an external CSS stylesheet and an XML file. Here’s the code of the two proxies.

StyleSheetProxy

Line 16: The SRNAME constant holds the name of the StartupResourceProxy twin.

Line 40, line 45: The helper method in the parent EntityProxy class is called to send “Loaded”/”Failed” notifications.

Lines 48-51: The getter method returns the internal data property as a typed StyleSheet object.

The SiteDataProxy class works in a similar fashion:

Lines 38-51: Please refer to the data.xml file described in part 1 of this tutorial.

Line 49: The SiteDataProxy class makes use of a simple value object class (SectionVO):

In the third and last part of this tutorial we will be creating a rudimentary view to test our efforts.

When I started to learn PureMVC (and I’m still learning), I was happy to discover that the AS3 version is accompanied by a Startup Manager. This utility isn’t part of the core PureMVC framework and has to be downloaded and installed separately, but it nicely integrates with the “PureMVC way of things”.

There’s a very well-documented sample project (Startup as Ordered) from the author of the utility, Philip Sexton. After exploring the source code of this project, I thought I give it a try and set up my own little startup sequence. Philip’s sample just simulates the asynchronous loading with the help of another utility he wrote (Asynchronous Stub), so I decided to take a more real-world scenario where an external stylesheet and an XML file are loaded before the user interface is created. Once you have understood the basic setup, it’s no big deal to extend the startup sequence by, for example, making asynchronous calls to remote services.

Preparing the Project Space

Loading a stylesheet and some initial data is a common task in both Flash and Flex projects. So my approach in this tutorial is to set up a pure AS3 project that can easily be adjusted to work in both worlds. This also means that you can use whatever IDE you prefer for ActionScript coding. I’m using FlashDevelop along with the Flex 3 SDK but the project space would look very similar in FlexBuilder.

If you haven’t already done so, download the PureMVC framework and the Startup Manager. Make sure that both libraries are available to your project. Either copy the SWC files in your project space or add their locations to the classpath. On the top level, your project should contain the three folders bin, lib and src. For my purposes, I placed copies of the SWC files in the lib folder so that I can provide a working FlashDevelop project for download that includes all resources.

Choose a package name (I’m going to use com.log2e.puremvcdemo) and create the usual model, view, controller folders. Also, in addtion to your document class (Main.as) create an empty file with the name ApplicationFacade.as in the puremvcdemo folder. You project panel should look similar to this now:

The Resource Files: styles.css and data.xml

Inside the bin folder create two text files with the names styles.css and data.xml. These are the resources that we will be loading during startup. The stylesheet is pretty simple:

The XML file contains some sample content:

Important note: Make sure that the HTML-coded content inside the CDATA block is only composed of HTML tags that can be interpreted by HTML-enabled textfields in Flash/Flex.

In the next part of this tutorial we will be taking a closer look at the inner working of the Startup Manager.