The GAE SWF Project

The GAE SWF Project: Knowledge and tools to help you build Flash and Flex apps on Google App Engine

Today I'm releasing The GAE SWF Project, a resource of Flash and Flex-related knowledge specifically aimed at getting you up and running quickly with Google App Engine. If you want to skip all the details and start playing with it, skip to the Getting Started section.

Everyone else, read on!

When Google announced Google App Engine last week, I couldn't believe what I was hearing. It was as if someone had said, "Hey, Aral, tell us what your perfect development environment is and we'll build it for you."

In recent weeks, I had started playing with Python and Django and experimenting to see whether I could use it to build the web application for the Singularity web conference that I'm organizing at the end of October. Turns out that I could not have picked a better time to invest in learning Django and brushing up my Python as Google App Engine is heavily influenced by (and supports) Django and is written in Python.

A framework for the Singularity Conference

Singularity is shaping up to be a really great conference. I'm honored to have a constantly-expanding stellar line-up of speakers and yet the sessions are just one very important aspect of the conference. I find that you get as much out of your social interactions with speakers and other attendees at conferences as you do from the sessions. And Singularity is no exception.

The Singularity conference application is not something you will login to on October 24th and never visit again beyond October 26th. On the contrary, I plan to launching the application as early as possible and add features as we go so that we can start building the community around the conference. This is essential for the organization of the local conference hubs, for building friendships months in advance of the conference, and so that you can influence what the conference ultimately becomes (you do not have to attend the conference to join the online community.)

When I initially announced the Singularity conference two months ago, I stated in the About page that Singularity would have a "focus on open source, the community, and on giving back."

Today, I'm taking the first step towards delivering on that promise by releasing the initial underpinnings of a framework that will eventually power the Singularity conference web application. I present to you The GAE SWF Project.

The GAE SWF Project

The GAE SWF Project (hey, Google chose the name, I only provide the juvenile attempts at humor) is a resource of Flash and Flex-related knowledge specifically aimed at getting you up and running quickly with Google App Engine. The initial release contains a proof-of-concept Flash 9 client showcasing a pre-alpha version of The GAE SWF Framework. The framework is a very light-weight combination of Python and ActionScript 3 that uses some of the best open source components available today on the Flash Platform and Python ecosystem. It is inspired at its core by best practices and a pragmatic approach to application development.

The proof of concept (and, indeed, the whole project) specifically targets Google App Engine. This is by design. The framework is not a generic one (although, by all means, feel free to get inspired and port it if you wish). The dedicated focus is part of the appeal. It means that we can make things simpler.

There will be no abstraction for the sake of abstraction and no premature abstraction; the framework will evolve by encountering real-world problems and solving them.

Finally, keep in mind that you are viewing the fruits of three days of work at the moment (this, in itself, should be testament enough to how easy -- and fun -- Google App Engine makes development). It is early days but I feel that we've made a good start. I hope to hear your thoughts and feedback in the comments.

The Proof of Concept

The proof of concept is built on Google App Engine using Google's webapp framework.

It showcases several fundamental architectural considerations, the most important of which I've outlined for you below.

HTML and Flash in a tree...

You use handlers in app.yaml to host a mix of Flash and HTML content, including the Flash Remoting gateway, in a single Google App Engine app.

Embed Flash content using SWFObject

SWFObject is the way to embed Flash and Flex applications in your HTML. Use it. 'Nuff said.

Deep links

You implement deep linking using a combination of server-side Python and SWFAddress so that both SWFAddress-style and regular URLs are supported. Regular URLs are translated to SWFAddress-style hash/anchor URLs on the server.

Thus, both of the following URLs are valid ways to reach your profile page on the proof of concept Flash 9 client:

Regular URL:

SWFAddress-style URL:

Flash content that obeys browser text-size changes

Users with poor eyesight or in environments with reduced-visibility (such as bright sunshine outdoors) may want to increase the size of the text displayed in the browser. By default, Flash and Flex content does not react to these text-size changes. However, it is possible to make Flash content obey browser text-size changes and the proof of concept implements one such method that does not involve any alterations to the Flash app.

(You can read more about similar issues -- and see some juicy Flash myths debunked -- in my review of the talk I gave at Highland Fling this month titled Bare-naked Flash: Dispelling myths and building bridges.)


PyAMF is a Flash Remoting implementation for Python. It has a dedicated and responsive group of passionate developers working on it, led by Thijs Triemstra, Nick Joyce, and Arnar Birgisson. On Tuesday, the team released PyAMF 0.3 with support for Google App Engine.

The GAE SWF Framework uses PyAMF as a core component to communicate with the server and the various Google App Engine APIs. It is currently running PyAMF 0.3.

The PyAMF gateway is setup as a regular mapping, and mapped to /gateway in app.yaml.

Users API

You use the Google App Engine Users API to login and out of the Flash application. The current Flash 9 proof of concept implements one of three possible ways of handling logins (see the note in my earlier blog post about the other two ways.)

Intelligent forwarding after login

When you hit a deep link in the application without logging in, you are automatically forwarded to the link after you login. This is a behavior that you are accustomed to seeing (and expect) in HTML-based applications but I have rarely seen it implemented in Flash and Flex applications.

DataStore API

The Google App Engine DataStore is a massively scalable database based on Google's Bigtable (the same distributed database that powers their search and services like Google Earth).

The proof of concept has a profile section where you can fill in your name and a URL (the Users API currently does not provide your GAE app with the user's name, just their email address). This data is saved via PyAMF and the DataStore API.

(All server-side services are in the /services package.)

Client-side and server-side validation

The Profile Screen shows you how to implement two different types of validation: simple client-side validation and server-side validation.

The Name field performs simple client-side validation that stops the user from submitting the form without entering a name.

The URL field, on the other hand, actually hits the server and asks the DataStore to verify that the URL is valid. When you think about it, it makes sense to use server-side validation code to validate more complex data types using the exact same code that the DataStore API uses.

The user experience is managed via visual cues that are carefully scripted using the excellent KitchenSync AS3 sequencing library by Mims Wright. (Mims just added me as a project member so I can contribute a small update I blogged about earlier.)

(I'm still working on tweaking the timing of the type wait duration for firing the server-side validation code to make it as seamless as possible.)

As the framework develops, I know that the KitchenSync library is going to be an essential, core element, and I look forward to contributing back as much as I can to the project.

Mail API

The proof of concept also makes use of the Google App Engine Mail API to send email confirmations to your Google Accounts email address after you update your profile.

When initially working with this, I was searching for a simple way to monitor the mail that was being sent from the app. Although the Development Web Server allows you to specify an SMTP server when you start it, I couldn't get it to work with either GMail or my web host's mail server. And setting up sendmail or postfix was a pile of worms I didn't want to sample.

Instead, I found a simple, open source SMTP server written in Python that's perfect when developing locally with the Development Web Server. It's in The GAE SWF Project app that you can download. To start it, simply change to your The GAE SWF Project folder and type:


You will see all email sent from your application in the Terminal window. (Note: I run on a Mac and all the commands in this article are meant to be run in Terminal on OS X. You may need to tweak them slightly for your operating system of choice.)

CSS, etc.

I may introduce myself as a Flash Developer but that doesn't mean that I don't care about the rest of the web. With good friends like Andy Budd, Richard Rutter, Paul Annette, and Jeremy Keith living almost a baseball-bat-wave away from me, I'd be scared silly implementing a new site with anything less than pristine markup. So that's what I've strived for here and I hope I've at least come close. (I did use one <br/> tag, for which I feel very dirty indeed!)

Nearly all of the credit for the CSS goes to the excellent YUI Grids CSS library that Rob Knight clued me into via Twitter last week when I was battling with altering the K2 theme on Singularity to make it into a cross-browser three-column fluid layout.

(The scale9-esque fluid download cell is courtesy of the even more rounded corners with CSS technique.)

The HTML content is structured using several Django templates, which are supported by Google's webapp framework.

Finally, the Flash client uses the TabBar component from the open source Yahoo Astra Flash components and Uza's AS3 Global Object to implement several global convenience properties (like the current SWF's URL).

Getting Started

Getting started with The GAE SWF Project couldn't be easier.

1. Download and unzip

First off, download the Google App Engine SDK (includes the local Development Web Server and webapp framework.)

Next, download the latest release of the The GAE SWF Project and unzip it.

(Or, you can check out the unstable, bleeding-edge version from The GAE SWF Project Subversion repository's trunk on OSFlash.)

2. Start the server

Open up Terminal and navigate to the folder you unzipped The GAE SWF Project to. To start the Development Web Server type:


This is a convenience script that I made that starts the Development Web Server and sets the mail server as localhost:5000. You can change these in the script of just use . to start it up without mail support.

If you want to monitor the email that gets sent, open up a separate Terminal window and, in The GAE SWF Project folder, type:


3. View the app and start hacking!

Now that the app is running, view it in the browser by hitting http://localhost:8080.

You can now open up the source folder and start exploring!

Trace you, trace me, trace it for always...

Wow, did I just paraphrase Lionel Richie?

Anyway, I find it useful to tail the Flash trace log (especially to see trace results in the browser and online). Here's how you do it:

Before you start, you need to enable logging by creating a file called mm.cfg in /Library/Application Support/Macromedia.

In it, enter:


You only need to do this once. After that, whenever you want to tail the log, open up a new Terminal window and type the following, replacing USER with your home folder:

tail -f /Users/USER/Library/Preferences/Macromedia/Flash\ Player/Logs/flashlog.txt

Play, enjoy, share, have fun!

As I state on The GAE SWF Project site, I hope that this open source effort will help you to get started quickly with building Flash and Flex application on Google App Engine. In the past few days, I have had more fun developing this than I can remember in a long while. I love Python, I love Django, I love Google App Engine, and I love Flash and Flex. To have them all together... well, that's a dream toolset, right there!

And, there's something to be said about writing your app and then letting Google handle the rest. Personally, I can live with that.

(Oh yes, and I do desperately need to talk to someone at Google about hosting the Singularity conference web application on Google App Engine with regards to the quotas -- if you know whom I should contact, please either let me know directly at or leave a comment below -- thanks!)

The GAE SWF Project is currently a proof-of-concept; it's a three-day old baby that I hope will blossom into a useful resource.

I hope you you enjoy it and I hope that it makes your life a little easier or at least gives you food for thought.

Play with it and let me know what you think in the comments.