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.

import fl.motion.easing.*;

you should be able to replace it with

import mx.effects.easing.*;

and get the same functionality.

This tutorial may serve as a beginner exercise in AS3 coding. But before starting, let’s take a quick look at what we will be creating:

The spinning preloader animation is an all-time classic. Our implementation will be highly configurable. You will be able to set the number, size, color and fade-out duration of the rectangular segments, as well as the radius and the spinning speed.

Prerequisites

Since this is a pure AS3 project, you can choose whatever IDE you like. I use the open-source AS3 IDE FlashDevelop along with the free Flex 3 SDK. The only other thing we need is the AS3 animation kit TweenLite. This lightweight tweening engine is contained in a single class file. You can eiher copy and paste it into your project space, or you can store it somewhere else and add the path to your project’s classpaths settings.

I call the preloader class SpinningPreloader and use com.log2e.utils as package definition. So my FlashDevelop project panel looks like this:

The SpinningPreloader Class

Here’s the full class code (I will explain it below):

The Constructor

The constructor receives a list of parameters:

• target: The display object you want to attach the preloader animation to. The type is DisplayObjectContainer so the target can be any object that inherits from this class (for example Stage, MovieClip, Sprite).
• centerX: The x position of the preloader’s center point.
• centerY: The y position of the preloader’s center point.
• radius: The radius of the preloader. Please note that this is not the outer radius of the resulting animation but the distance between the center point and the registration point of the rectangular segments.
• steps: The number of rectangles that are created in one full turn.
• rectWidth: The width of a single rectangular segment.
• rectHeight: The height of a single rectangular segment.
• color: The color of the rectangles.
• timerInterval (in ms): This parameter controls the speed of the rotation by setting the time interval after which a new rectangle is drawn.
• fadeOutInterval (in s): This parameter specifies the duration of the alpha tween that fades out it each segment.

The start() and stop() Methods

These two methods are the only interface between the SpinningPreloader class and the outside world.

The start() method creates a container for the animation and positions it on the target display object. It also initializes the _count property and starts the timer which repeatedly calls the drawRectangle() method.

The stop() method fades out the container sprite. Once the alpha value is 0 the timer is stopped and the container is removed from the display list. If you prefer to remove the animation immediately just replace the line of code that starts the tween with the two lines from the onContainerFadeOutComplete() event handler method.

The “Fading” Event Handlers

The method onContainerFadeOutComplete() is called after the container’s alpha value has reached 0.

The method onRectFadeOutComplete() is called whenever a single rectangle has finished its life cycle. As soon as the rectangle’s alpha value is 0 it is removed from the display list. This way we limit the maximum number of rectangles that are child objects of the container sprite at the same time.

Drawing the Rectangles

The angle that defines the position of each rectangle is calculated with the help of a counter variable (_count) which is incremented each time a rectangle is drawn. If the counter value is equal to the number of steps _count is reset to zero. The result from 360 divided by the number of steps muliplied with _count gives us the angle in degrees. This value is stored in the local variable rot.

In order to calculate the exact x and y coordinates we need a little trigonometry.

(Just on a side note, we use the three o’clock position as starting point because that’s where the 0 degree angle is situated in Flash.) The sine and cosine in the above diagram are calculated by sin(A) = y/r and cos(A) = x/r. This trigonometric relation is used in the drawRectangle() method:

rect.x = _radius * Math.cos(rot * Math.PI/180);
rect.y = _radius * Math.sin(rot * Math.PI/180);

Please note that the Math.sin() and Math.cos() functions expect the angle to be in radians, that’s why we have to multiply rot with Math.PI/180.

The rectangles themselves are created in the filledRectangle() method which receives the width, height and color as parameters. The sprite instance is returned to drawRectangle() where the x, y and rotation values are set and the rectangle is added to the display list. As soon as the rectangle is visible it starts to fade out. Invoking e.updateAfterEvent() causes the Flash Player to update the screen immediately after a rectangle has been added (instead of relying on the next scheduled screen update that is governed by the frame rate).

Using the SpinningPreloader Class

The animations shown on this page were created by instantiating three preloader objects with different parameters:

Room for Improvement

Where to go from here? There are several options for improving the class. For example, you could add a text field at the center of the preloader and an update function that receives the loading progress value. Or you could use a circle or a small bitmap instead of the rectangle. I will leave this as an exercise to you.

If you have any questions or suggestions leave a comment or drop me a message.

This tutorial will guide you through the steps of creating a simple ActionScript component and compilling it into a SWC file.

Installing the SWC Export Plugin

The plugin installation is a piece of cake. Download the plugin from here, unzip the ExportSWC.dll file and place it in FlashDevelop’s Plugin folder. (If you don’t know where to find this folder go to the “Tools” menu and click on “Application Files…”.) After restarting FlashDevelop you should see a new icon in the toolbar:

Sample Project: A Status Component

You will be creating a simple status component as a sample project. It displays different icons according to the status set. As for the icons, I’m using two icons from the free “Silk” icon set which can be found on www.famfamfam.com:

The first icon is supposed to represent an “OK” status, and the other one signals an “Error” status. (For example, you could use this component as an item renderer in a Flex DataGrid for displaying the status of the listed items.)

Setting up the FlashDevelop Project

Create a new project in FlashDevelop and select “ActionScript 3 / Default Project” as template. Call the project “StatusComponent” and save it. If you look at the project panel you will notice that FlashDevelop has already created two folders (bin and src) and a class file (Main.as) for you. Please make sure that the src folder is the only folder in your classpaths settings:

Now follow these steps:

1. Create a third folder on the same level as the bin and src folders and call it assets.
2. Copy the two icon files into this new folder.
3. Under the src directory create a hierarchy of three sub directories: com/log2e/components. (I’m using my domain name here, you can name them whatever you like, of course. But it’s considered good practice to organize your class packages with the help of unique names such as domain names.)
4. Finally, move the class file Main.as into the components folder and rename the file to StatusComponent.as.

Your project panel should look like this now:

Now open the StatusComponet.as file.

The ActionScript Code

I’m posting the complete class code first, and then I will go through the code step by step.

Line 1: The package definition reflects the directory structure we created below the src folder.

Lines 3-4: We only need Sprite and Bitmap as display objects.

Line 6: Since we are creating a visual component the StatusComponent class extends Sprite.

Lines 8-10: The three constants hold the status definitions as strings. They are accessible from outside the component (for example, StatusComponent.STATUS_OK).

Lines 12-15: The two [Embed] metadata tags include the two icons in the SWF and SWC files at compile-time. Instances of the embedded assets can be created by the standard new syntax.

Lines 17-18: The two private variables hold the current status information and the displayed icon.

Lines 20-22: When a new instance of the component is created the constructor sets the initial status to unset.

Lines 25-28: The getter method for the status property.

Lines 30-50: The setter method for the status property. This method not only updates the private _status property, but also removes the currently displayed icon from the display list and instantiates a new icon according to the status set.

Exporting the SWC File

All the hard work is done. The SWC file is only a mouse click away. Of course, you can test the component first by hitting F5. In this case you should modify the constructor and set the initial value to STATUS_OK or STATUS_ERROR, otherwise you will only see a blank canvas when you publish the movie. For the release version of the component set the initial value back to STATUS_UNSET. Now click on the new “Export SWC” icon and the magic happens right in front of your eyes…

If everything went ok, you will see a new file in your bin folder:

If you tested the component (like I did) you also have the SWF file in the bin folder. Actually you can delete the StatusComponent.swf file now, it’s no longer needed.

Using the StatusComponent

For a quick test of the component create a new default ActionScript 3 project in FlashDevelop, call it “StatusComponentTest”, and make the StatusComponent.swc file accessible to your project by adding its path to the new project’s classpaths. The project panel should look like this:

Now this is important: Right-click on the StatusComponent.swc file and select “Add To Library”. Otherwise the class(es) in your SWC file will not be recognized.

Here’s a simple test class (StatusComponentTest.as) that instantiates the component and sets the status to STATUS_OK. The trace() statement sends the string value of the current status to the output panel.

I hope you enjoyed the tutorial.