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.

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.