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.

http://tinyurl.com/api-create.php?url=http://blog.log2e.com/

Here’s a little Flex demo that demonstrates its use.

View source.

The result of this tutorial can be seen here (”View Source” is enabled).

Twitter’s Public Timeline

Twitter’s public timeline returns the 20 most recent statuses from non-protected users. The result is offered in four different formats (XML, JSON, RSS, Atom). The structure of the data can best be explored when we look at the XML representation of the “tweets” (Twitter speak for messages). Here’s a simplified view where the child nodes inside the status nodes have been removed:

A single status node looks like this:

As you can see, the status node contains a user node which itself has several child nodes.

corelib’s JSON Class

Of course, you could use ActionScript’s XML capabilities to manipulate and further process the XML data. In this tutorial though, we want to make use of the JSON class which is part of the ActionScript 3 corelib library and which facilitates both serialization and deserialization of JSON data.

Download the corelib library and make the corelib.swc file available to your Flex project. The JSON class is inside the com.adobe.serialization.json package. The class provides two static methods, encode() and decode(). The decode() method reads a JSON string and returns a native object as specified by the input string.

Creating the Demo Application

Our demo displays the public timeline in a datagrid. Here’s the code with some explanations below:

Lines 14-15: Twitter’s public timeline data is converted into an ArrayCollection which in turn serves as a bindable dataprovider that is used to populate the datagrid.

Lines 22-25: The loadPublicTimeline() method invokes the send() method on the HTTPService object twitterService.

Lines 27-32: The payload of the result event contains the JSON string that has been returned by the Twitter API. The decode() method converts it into an array of generic objects. The array itself is wrapped into an ArrayCollection.

Lines 39-44: This is a helper function that formats the date/time value of the created_at field.

Lines 46-49: This is another helper function that retrieves the screen_name value from the Twitter user. Please note that the user object is nested inside the status object (see the XML code above). The user object can be accessed with the usual dot syntax.

Lines 54-60: The HTTPService instance that retrieves the public timeline from Twitter’s official API URL (for more details please refer to the Twitter API documentation).

View the demo application.

Security Restrictions

If you recreate this demo application in FlexBuilder, everything should be working fine as long as you run it from your local machine. If you put the files on your server though, you will be experiencing the “Security error accessing url” error. The reason is Twitter’s cross-domain policy. If you look at Twitter’s crossdomain.xml file, you notice that it allows access only from a very few domains.

Here’s what you have to do to get around this restriction: Replace the URL in line 56

http://twitter.com/statuses/public_timeline.json

with a URL that points to a PHP proxy file on your server:

The PHP script simply reads the data from Twitter and writes it to the output buffer (the file header settings and microtime() are used to prevent caching).

I hope you enjoyed the tutorial. If you have any thoughts or suggestions, feel free to leave a comment below.

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