Introducing the Gateway Controller

Setting up a Zend AMF server inside a Zend controller is pretty easy:

Since we do not want to output any visible content we disable the view renderer (otherwise the action controller will look for a view script in a subdirectory named after the controller). The endpoint URI of our AMF server gateway is now something like http://www.mydomain.com/gateway/, and doesn’t interfere with our other controllers. By calling the addDirectory() method we tell the server where to look for the services. We only need to provide a base directory here. If we set up our remote objects in Flex with full namespaces the AMF server is able to resolve the dot syntax into the appropriate path.

For example, the dot syntax in the source attribute of this remote object

<mx:RemoteObject id="articlesRO" showBusyCursor="true" source="com.xeladon.cms.ArticlesService" destination="zend"/>

will be transformed into the path com/xeladon/cms/ArticlesService. Please note that in this setup there is no need for explicitly propagating each service class to the server with the setClass() method. For more information on the different approaches (addDirectory() vs. setClass()) please refer to Wade Arnold’s blog post on Lazy Loading Classes.

Organizing Value Objects with Namespaces

Now let’s take this one step further. As a long-time AMFPHP user, I have gotten in the habit of organizing my value objects with namespaces. I usually put my VOs in a folder below the service classes:

We can still do this with Zend but we have to make sure that Zend Loader is able to find the VO classes. I suggest adding the path to the include path in the index.php file:

Adding More Functionality

Based on the above setup, we can easily add more functionaliy to the bootstrap file without worrying about the AMF server gateway. We would probably want to make use of Zend_Config for configuring the application, and Zend_Db for managing database interactions. By adding a few more lines of code to the bootstrap file, these functions become automatically available to the AMF service classes.

Let’s assume we set up a database adapter in the bootstrap file. This allows us to write very clean code inside the service classes. The following code is just an example (where ArticleVO is a typical value object, and Articles is supposed to be a Zend model class that extends Zend_Db_Table):

Summary

What do we gain with all this?

1. We keep things organized and can rely on the same structures (packages, folders, namespaces) in both ActionScript and PHP.
2. We can use other powerful features of the Zend framework for the application’s server-side logic.
3. We have the flexibility of adding Flex/Flash and HTML interfaces to the same core application whenever and whereever needed.

I would like to introduce a Zend AMF server setup that makes use of some of Zend’s best practices like configuration files, database adapters and models. If you are a Flash/Flex developer coming from an AMFPHP background and have never worked with the Zend framework before, you may easily feel overwhelmed by the framework’s complexity. This article is not meant to present a thourough overview of all Zend features you could possibly utilize in your Flex/Flash development work, but it might motivate you to dive deeper into the framework’s features.

The Folder Structure

First of all, even if I only need the AMF server from the Zend framework I set up my server directories like I would do with any other Zend/PHP application. If you already have some experience with the Zend framework this folder structure probably looks familiar to you:

This is a rudimentary folder structure, of course, because a typical Zend application with an HTML frontend has additional folders for controllers, views, layouts, forms, plugins, helpers, etc. But the basic setup is the same: We have an application and a library folder that are outside the web server’s root directory (public). The Zend framework packages are inside the library folder, and below the application folder there are a config and a models folder. For the special purpose of the AMF gateway, I added a services folder which is supposed to contain all service class files.

The Database and the Configuration File

Let’s assume we are working on an application that needs to manage user accounts. A very basic table would look like this:

The database credentials are stored in an INI file (app.ini). In this example there are configuration data for both a production system and a development system. Because the development system configuration data are very similar to those for production, the development section inherits from the production section:

This configuration file also allows you to easily change the database adapter (if needed).

The Bootstrap File

Let’s take a look at the bootstrap file (index.php):

This bootstrap file is very similar to the standard bootstrap files you find in other tutorials or in the Zend Reference Guide. It adds some include paths, initializes the Zend autoload feature for classes, and sets up the AMF server.

The Service Classes

Utilizing the Zend_Config and Zend_Db packages, we set up the database connection in a base service class that the actual service classes inherit from. In line 7 in the listing below we provide a default database adapter for all subsequent instances of Zend_Db_Table objects in our application (for more information, please refer to the Zend_Db chapter in the Reference Guide). This way we keep the logic of creating a database connection in one central place.

The only real service class in our example is UsersService which extends BaseService and invokes the parent class’s constructor by calling parent::__construct();. For the sake of simplicity it contains only one method (getUsers()):

You may wonder what the Users class does (line 12 in the above code listing). Here’s the answer: It’s a model class.

The Model Class

Models are another important concept of the Zend framework. Although the classical MVC pattern doesn’t apply in the context of the Zend AMF server, I stick to this concept here because it may come in handy sometimes. Imagine an application that is supposed to support both a Flash and an HTML interface. By following the framework’s MVC guidelines, we are able to build an application engine that uses the same model classes for both the AMF server gateway and the MVC-based HTML frontend.

The class Users is located in the models folder. It extends Zend_Db_Table and holds the name of the corresponding database table:

Remember that we provided an application-wide database adapter for all Zend_Db_Table objects (see line 7 in the BaseService class). By creating an instance of Users (which inherits all methods from Zend_Db_Table) we are able to use fetchAll() to retrieve all rows from the table users.

The Value Object Class

The class User (see line 17 in the UsersService code listing) is a helper class that allows us to send an array of typed objects to the Flash player. This is especially useful in Flex-based applications where you want to use value objects for data-binding, for example. By the way, the class User doesn’t look any different than a VO class in an AMFPHP context.

By calling $server->setClassMap('UserVO','User'); inside the bootstrap file, the User objects are mapped to UserVO.

I skip the Flex/Flash part here because this topic is well covered in other tutorials. But I hope you caught a glimpse of how you can leverage the power of other components inside the Zend framework – even if you are only interested in the Zend AMF server. There are more scenarios where the Zend framework may come in handy for a Flash/Flex developer (for example, think of generating PDF files on the fly by using Zend_Pdf).

Let’s say you want to load a PNG file from “my.domain.com” into a SWF file on “your.domain.com”. Let’s also assume you have provided a “crossdomain.xml” file on “my.domain.com” that grants access to “your.domain.com”. As long as you only add an instance of the flash.display.Loader class to the display list everything is fine. But what if you, for example, want to access the bitmap data inside the loader object? In my case, I just wanted to set the smoothing property of the Bitmap object to true before resizing the image. So I tried this:

This works fine inside the Flash CS3 IDE (or whatever IDE you use). I deployed the SWF file to a web server – and it failed. Why? Probably because I have missed to read this article, this blog post, and this blog post. And yes, I admittedly have never paid attention to the existence of the flash.system.LoaderContext class. But this class is all what we need here (forget all the PHP proxy hacks, folks!).

Create a LoaderContext object with checkPolicyFile set to true and add it to the flash.display.Loader‘s load() method!

It’s easy when you know it.

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.

The method makeBoolean() accepts any type of data and converts it into a string. The string value is then compared to a list of words which represent the Boolean status true. If no match is found false is returned.

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.