Step 1: What is Single SWF Preloading?

The idea of single SWF preloading is that you have a Flash object which preloads itself. That means that the preloader, with its associated functionality and assets, is embedded together in the same SWF file as the whole Flash movie or application.

We’ll start off this tutorial with some theory and finish it off with creating an FLA together with a preloader class that you can use in future projects. During the course of the tutorial we’ll discuss common pitfalls and important considerations.

Also, now that Activetuts+ has started focusing on document classes and generally keeping things in class files as much as possible, we’ll do just that in the practical part of this tutorial. Check out the Quick Tip: How to Use a Document Class in Flash if you need to learn the basics.

Make sure you have an updated version of either Flash CS3 or Flash CS4. I know for certain that a later CS4 update has changed the way classes are loaded and that can make all the difference here!

I’ll admit right away that this tutorial is quite lengthy for this narrow subject, but it contains all you need to know, so buckle up and let’s get to it!

Step 2: Why Single SWF Preloading?

The idea of a preloader is quite obvious: you want to make sure the user gets visual feedback indicating that the Flash object is loading. Embedding a large Flash file that takes 10 seconds to load could mean the difference between users staying or leaving the website, should it not be for the preloader telling the user to hold on.

The process of creating "self preloading" Flash files presents some issues and problems. There are other preloading techniques that are really easy to put together, such as one SWF file preloading another and adding it to the stage once loaded.

So why bother? Well, there are situations where you have no choice.

For example, you might want to create Flash games which you hope to spread to as many Flash gaming portals as possible. Most of these portals only support games in form of a single SWF file which leaves you with no choice but to make sure that your game preloads nicely from within itself.

Aside from such obvious examples, there’s the argument of having a completed product in only one file which makes for easy managing.

Step 3: How SWF files are Loaded

When your browser stumbles upon a Flash object and starts loading it, it starts from the beginning of the timeline. It loads the frames one after another. As soon as the first frame is loaded, it can be displayed.

Our approach here is to put a preloader on the first frame so the user sees something happening, while the browser continues to load the rest of the file. We write code to check the overall progress and when it’s completed we continue on to the main content of the file.

The challenge is to keep the size of the first frame to a minimum. If you let code and sounds pile up in the first frame you might have a preloader that’s not visible until after you’ve loaded maybe 60% of the movie.

A great tip when it comes to using a percentage counter that displays numbers is to use a font that is small in byte size. But this only takes you so far. Unfortunately we have to work quite a bit harder to have things our way!

It’s been said many times before and it’s worth saying again:

Preloaders, the hardest of the simplest tasks in Flash..

Step 4: The Defining Variables

There are a number of things that will affect what will be put in which frame, such as:

• Where on the timeline you put assets.
• Which frame you choose as the “class export frame” (see Step 11).
• Whether you put assets before or after the class export frame.
• In Flash CS4 – choosing whether or not to export the asset in the class export frame (in the symbol properties dialog).
• In Flash CS3 – choosing whether or not to export the asset in first frame (in the symbol properties dialog).
• Whether you use sounds.

Step 5: The Problems

The main problem we face is controlling what ends up on frame one, because, as mentioned above, everything on frame one has to be loaded before the preloader can be displayed.

Other than that, there are differences between how Flash CS3 and CS4 work. In the next step I’ll make a number of thoroughly researched statements that you can refer back to if need be. It should be a great resource if you quickly want to troubleshoot your preloading, to figure out why it’s not behaving the way you expect.

I’ll try to make the statements a bit more tangible by referring to TweenLite, a great tweening library by Jack Doyle over at greensock.com. We’ll be using TweenLite in the hands-on part of this tutorial so this will make the most sense.

Step 6: The Statements

These statements hold true for both Flash CS3 and CS4 unless stated otherwise. "Importing TweenLite" basically means "importing and using TweenLite" – the results may differ if you don’t actually use the code as the Flash compiler disregards unused imports. Simply typing an import statement does not equal using the code.

• If you import TweenLite on any frame in the main timeline, TweenLite will be loaded in the first frame of the movie.
• If you have a MovieClip that imports TweenLite in its internal timeline and place this MovieClip after the class export frame, TweenLite will be loaded in the class export frame.
• If you have a MovieClip that imports TweenLite in its internal timeline and place this MovieClip before the class export frame, TweenLite will be loaded in the first frame of the movie.

The next three statements refer to the scenario where you have a MovieClip which is exported for ActionScript, using an external class file, which in turn imports TweenLite in the class file.

• Placing the MovieClip after the class export frame will make TweenLite load on the class export frame. There is no difference whether or not you check the "Export in frame X" ("Export in first frame" for CS3) regarding imported classes such as TweenLite. However, the checkbox affects whether or not the assets (shapes, bitmaps) of the MovieClip will be loaded in the export frame or not. In the case of CS3, you can of course only choose wheter or not to load it in the first frame.
• In Flash CS4 placing the MovieClip before the class export frame will make TweenLite load on the first frame. There is no difference whether or not you check the "Export in frame X". The non-code assets of the MovieClip will also load on the first frame.
• In Flash CS3 if you place the MovieClip before the class export frame, then regardless of whether you’ve checked "Export in first frame", you will get a silent fail! Meaning: the MovieClip you put on stage that should be using an external class file will just appear as a normal MovieClip, not giving you any indication whatsoever. You can still, however, affect whether the shape/bitmap contents of the MovieClip should be loaded in the first frame or not. This doesn’t really help though as you are equally screwed with the class loading.

The next three statements refer to the scenario where you have a MovieClip that is exported for ActionScript as "CustomClass", either using an external class file or not, which is instantiated and added to stage from a MovieClip that is placed on the timeline (just like the MovieClip from the previous three statements.) This CustomClass is only instantiated and does not previously exist on the main timeline.

• In Flash CS4 with the "Export in frame X" box checked, CustomClass is loaded in frame X and will display correctly. With the box unchecked it is still loaded in frame X and is displayed correctly.
• In Flash CS3 with the "Export in first frame" box checked, CustomClass is loaded in the first frame and will display correctly. With the box unchecked you will get a 1046 Type error, as the class cannot be found.

With all these restrictions, let’s at least consider this positive statement:

• If you place a MovieClip that only contains shapes/bitmaps, it will only load right before the frame it is needed. Unless you choose to export it earlier, that is!

Here’s a really interesting one:

• In Flash CS3 you cannot export a sound on anything other than the first frame. In Flash CS4 you can, on the class export frame.

Yes, you read that right. I guess it’s fair to assume that Adobe wants people to upgrade to CS4. So what to do if you’re stuck with CS3 and the grass is greener on the other side? I’ll tell you in the next step.

Step 7: Loading Assets in Flash CS3

This whole step is just for those of you using Flash CS3.

If you read through all the statements in the previous step then you’ll realise the problem of having lots of MovieClips exported for ActionScript. These will all have to be loaded in frame one, or be unavailable. Luckily, those statements were under the assumption that those assets were never placed on the main timeline, which happens to be our solution! (This is also the only way to load sounds other than in frame one..)

This is how it’s done:

1. Go into the properties of all the MovieClip/Sprite/Sound assets you want to export and uncheck "Export in first frame".
2. In the second frame of the main timeline, create an empty MovieClip called AssetHolder.
3. In this AssetHolder MovieClip, create an actions layer that has a stop(); call on the first frame.
4. Still in the AssetHolder, create a layer for each sound you want to use and drag those sounds out to the second frame of its own layer. They do not need to be longer than one frame, luckily. For all other Sprites and MovieClips you can place these in a single layer or multiple for easier organizing. Put these on the second frame as well and leave the first frame empty.

This will make all your assets load in the second frame. The solution is a bit tacky, but it’s not as rough as having to go and buy new software for this one particular issue.

(Kudos to 8bitrocket for this trick!)

Step 8: Bandwidth Profiler & Size Report

One thing I should mention before we start working is the bandwidth profiler. This is an essential tool in sorting out your preloading problems. When you preview a movie you can go up to view, then choose bandwidth profiler. Or just hit Ctrl+B.

Here you can switch between frame-by-frame graphs and streaming graphs. You can also simulate downloading the movie at a connection speed of your choice by either choosing it from the View menu or hitting Ctrl+Enter once again (change the simulated download speed using the View > Download Settings sub-menu). This is essential in finding out how your preloader will look, without going through the hassle of uploading it and capping your bandwidth. For that specific case though, I can recommend Firefox Throttle.

Besides the very useful tool that is the bandwidth profiler there is the option to generate a size report. Hit Ctrl+Shift+F12 to open up the Publish Settings dialog box.

Go to the Flash tab, and in the Advanced section there is a checkbox labeled "Generate size report". When this box is checked, previewing or publishing your movie will generate a text file in the same folder as your FLA file that contains useful information on what parts that make up the total size of the movie.

Step 9: End of Theory

Finally we can start making a Flash movie with a nice self-contained preloader!

We’ll be employing a "three frame preloading" technique. On the first frame we’ll put a preloader MovieClip that has its own class "Preloader". On the second frame we load all the classes and on the third frame we load and display the content. We’ll put the content in a MovieClip named Application with an associated class "Application". This is where the meat of the application goes.

Step 10: Create New Document

Start by creating a new AS3 document. I’m making it 600×400px, dark gray background, 24 FPS. These settings don’t matter though.

Set the document class to Main and hit OK.

Step 11: Set the Class Export Frame

Go to File > Publish Settings, the Flash tab, then the ActionScript 3.0 settings. Type in “frame 2″ in the "Export classes in frame" field.

Step 12: Design a Preloader

Obviously the design of a preloader won’t affect the function. I’ll give step by step instructions, but feel free to skip these parts and take your own approach if you so wish. Just make sure you note what parts I refer to in the code later on.

Draw a rectangle with rounded corners and give it a blue gradient. Then turn it into a MovieClip symbol, call it Preloader. Choose to export it for ActionScript and call the class Preloader.

Within this new MovieClip, draw a new rounded corner rectangle with a gray gradient, turn it into another MovieClip and give it an instance name of progressArea.

Go ahead and match up the layer layout I’ve got going on in the picture above. Next, make a duplicate of the last shape and place it in the Progress bar layer on top of the Progress area one. Give it a light blue gradient, turn it into a MovieClip and give it an instance name of progressBar. Enable guides for 9-slice scaling and make sure you keep the left and right round edges outside.

Lastly, make a dynamic text field with an instance name of percentageText. Make the text right-aligned. That way, the percentage sign will never move, only the numbers (which change anyway). Go into character embedding and make sure you embed numerals and the percentage sign (%). To make a really small preloader I’m using a small pixelfont called Pixel Mix from dafont.com. I’m also giving it a blue glow just because I can.

Step 13: Back to the Stage

Make sure the whole preloader MovieClip is placed in the first frame and given an instance name of preloader. Create a new layer called "AS" and put a stop(); in the first frame. Keep the preloader in its own layer, "Preloader". Make another layer called "Application". This is where we will keep the main content in the end.

Step 14: Create the Main Class

Create a new ActionScript file and save it in the same directory as your FLA file. Name it Main.as:

package
{
	import flash.display.MovieClip;
	import flash.events.Event;

	public class Main extends MovieClip
	{
		public function Main()
		{
			preloader.addEventListener(Event.COMPLETE, onPreloaderComplete);
			preloader.setLoaderInfo(loaderInfo);
		}

		private function onPreloaderComplete(e:Event):void
		{
			gotoAndStop(3);
		}
	}
}

Step 15: Create the Preloader Class

Create a new ActionScript file and save it in the same directory as Preloader.as:

package
{
	import flash.display.LoaderInfo;
	import flash.display.MovieClip;
	import flash.events.Event;
	import flash.events.ProgressEvent;

	public class Preloader extends MovieClip
	{
		public function Preloader()
		{
		}

		public function setLoaderInfo(ldrInf:LoaderInfo):void
		{
			ldrInf.addEventListener(ProgressEvent.PROGRESS, onProgress);
			ldrInf.addEventListener(Event.COMPLETE, onComplete);
		}

		private function onProgress(e:ProgressEvent):void
		{
			var percent:int = Math.round(e.bytesLoaded / e.bytesTotal * 100);
			progressBar.width = percent / 100 * progressArea.width;
			percentageText.text = percent + "%";
		}

		private function onComplete(e:Event):void
		{
			dispatchEvent(e);
		}
	}
}

Step 16: Grasping Main and Preloader

So what do these two classes do?

In Main’s constructor, we call the custom setLoaderInfo() method of our preloader and pass along the LoaderInfo object that is associated with Main.

Preloader receives this object and adds two event listeners to it. The ProgressEvent triggers the onProgress function, in which we calculate the percentage of the bytes loaded compared to the total bytes to be loaded. The percentage is used to set the width of the progress bar and the text of our text field.

The complete event is simply dispatched back down to Main which in turn jumps the main timeline to frame three when receiving the event.

Step 17: Adding Some Content

To have something to clearly show the preloader working, I’m adding a nice macro photo of a cat called Runa taken by a friend of mine. You can find the image in the source files provided with this tutorial. I’ve imported the bitmap and I turn it into a MovieClip called “Cat”.

Feel free to use whatever image you find suitable. Give the clip an instance name of "cat".

Step 18: Creating the Application MovieClip

As you can see on the screenshot above I’ve placed the Cat MovieClip on frame three in the Application layer. Take whatever MovieClip you made, cat or no cat, and hit F8 once again to nest it inside a new MovieClip which you call Application. Export this for ActionScript as Application.

Step 19: The Application Class

Create the Application class by starting a new AS file and saving it as “Application.as”. Have the Application class look like this:

package
{
	import com.greensock.TweenLite;
	import com.greensock.easing.Sine;
	import flash.display.MovieClip;

	public class Application extends MovieClip
	{

		public function Application()
		{
			TweenLite.to(cat, 7, {
						 scaleX:4,
						 scaleY:4,
						 onComplete:tweenBack,
						 ease:Sine.easeInOut});
		}

		private function tweenBack():void
		{
			TweenLite.to(cat, 3, {
						 scaleX:1,
						 scaleY:1,
						 onComplete:reTween,
						 ease:Sine.easeInOut } );
		}
		private function reTween():void
		{
			TweenLite.to(cat, 7, {
						 scaleX:4,
						 scaleY:4,
						 onComplete:tweenBack,
						 ease:Sine.easeInOut } );
		}
	}
}

This will animate the cat in and out indefinitely so you will forever remember the detail of her nose fur. How this class works isn’t important, what is important is that we’re importing TweenLite and using it, thereby making sure that it will be a part of the SWF file once exported.

Step 20: CS3 and CS4 Issues

Let’s go back to the school bench again for just a minute.

This movie compiles fine in CS4. The Application MovieClip is set to export on frame 2 unless you’ve changed it. If you’ve changed it you might notice something strange. More on this in the next step.

If you’re on CS3 this setting really matters. You’ll have to go and make sure you uncheck the "Export in first frame" checkbox in the Properties of the Application MovieClip, otherwise it will all load in the first frame!

That’s not the only problem. If you try to compile you will get a 1046 Type error, saying that you don’t have the type TextField available. So as you can guess, CS3 does things a bit different. What’s happening? Well, you are trying to use a TextField inside the Preloader MovieClip but you don’t have it imported. In CS4 this is handled automatically for you, but not in CS3.

Fortunately the solution is simple, just add:

import flash.text.TextField;

to your Preloader class, and you’re all set.

Some of you might have thought already that I should’ve extended Sprite for my Preloader class instead of MovieClip. Well, this is the reason I didn’t do that; I wanted to wait until this point to bring it up. Since the Preloader symbol contains both the "ProgressArea" and "ProgressBar", which both are MovieClips, you would’ve gotten the same 1046 Type error.

The same solution is possible here too of course. In fact, you should now change the Preloader to extend Sprite instead of MovieClip, and if you’re using CS3 make sure you import the Sprite class inside the Preloader class as well.

Step 21: Yet Another Issue

I mentioned a strange occurrence in the last step. If you uncheck the "Export in frame 2" of Application and run a simulated download, you’ll see the preloader disappear, unless you’ve extended the preloader’s keyframe to cover the second frame as well.

So what’s really happening? Simply put, the first stop(); statement doesn’t count. How’s that for obvious work flow planning? Note that if you put a trace statement in the first frame after the stop(); call, it does trace out. Important: note that this problem only shows itself when we’re simulating download!

The lesson learned here is don’t trust the simulated download! It won’t show you accurately how things will load and function. You can just keep the stop(); and preloader in the first frame and you’ll be fine when it comes to deployment. However it can be a pain to preview unless you have Application set to export on frame 2. And that’s just for this specific scenario.

In CS3 you have to uncheck the export box on the Application MovieClip otherwise you’ll end up with it loading in the first frame. But if you do that, you’ll run into this issue. So go ahead and extend the preloader to the second frame.

Step 22: Test the Movie

Go ahead and preview the movie. Run a simulated download on a low speed and enjoy the masterfully* crafted preloader (*masterfully only applies if you’ve followed my instructions to the letter).

If you look at the frame-by-frame graph, or a generated size report, you’ll see that the code is loaded in the second frame. The first frame is only 4kb and consists of the Preloader class and the embedded font glyphs. Now, 4kb is quite affordable as far as wait time before seeing the preloader is concerned, don’t you think?

You might see different sizes on CS3 and you will definitely see different sizes with different fonts. Or cats.

Step 23: Tweening the Preloader

You might have the idea that you would like to use TweenLite to fade away the preloader by tweening the alpha to 0 – but you don’t want to load TweenLite in the first frame since that adds another 8kb to the initial download.

There are several ways to accomplish this and we will solve it by having a MovieClip on the third frame that catches the preloader and tweens it. When completed, it will advance to the fourth frame, which we’ll have moved Application to.

The reason for putting it in the third frame is that we can’t put it in the second frame without having TweenLite being loaded in the first frame.

Now we’re moving away from the standard three frame preloading technique.

Step 24: Add a Layer and Stop(); Calls

Add a new layer called "Preloader catcher". Make sure you put stop(); calls on frames one, two and three. This is to prevent messed up previewing when simulating a download, as mentioned earlier.

Go ahead and move Application to the fourth frame as well as extending Preloader to the third frame.

Step 25: Create the Catcher

Make sure you have a keyframe on the third frame of the Preloader catcher layer. Go to this frame, draw a small shape and have the alpha of the fill color set to 0%. This is supposed to be an invisible MovieClip. Turn it into a MovieClip symbol called PreloaderCatcher or something similar.

Export the MovieClip as PreloaderCatcher. If you’re using CS4 it doesn’t matter if you export it for frame 2 or not, since it will be loaded in that frame no matter what. Well, it does change one thing, remember? Whether or not the shape is loaded on frame 2. In essence it doesn’t matter considering the near non-existent file size for this shape. You might as well uncheck it for good habit though.

Step 26: The PreloaderCatcher Class

Make a new class file called PreloaderCatcher.as:

package
{
	import com.greensock.TweenLite;
	import flash.display.MovieClip;
	import flash.display.Sprite;
	import flash.events.Event;
	import Preloader;

	public class PreloaderCatcher extends Sprite
	{
		public function PreloaderCatcher()
		{
			addEventListener(Event.ADDED_TO_STAGE, onAdded);
		}

		private function onAdded(e:Event):void
		{
			removeEventListener(Event.ADDED_TO_STAGE, onAdded);

			var preloader:Sprite = MovieClip(parent).getChildByName("preloader") as Sprite;

			TweenLite.to(preloader, 0.5, {
										alpha:0,
										onComplete:function():void
											{
												MovieClip(parent).nextFrame();
											}
										} );
		}
	}

As you can see, this class works by first obtaining the preloader by casting the parent as a Sprite and calling getChildByName("preloader"), where preloader is the instance name. The preloader is cast a Sprite as well, then TweenLite is used to fade it out.

When the tweening is complete, the onComplete function in TweenLite casts the parent as a MovieClip so it’s possible to call the nextFrame method.

Step 27: Why the Four Frames?

As I said before, we’ve now moved away from the three frame preloading technique. That in itself isn’t exactly blasphemy, but I’m sure some of you wonder why we did that. Instead, we could’ve handled the preloader tweening inside the Application clip..

In that case, you are perfectly right! The reason I used four frames here was to show you how to do it while keeping things separated. Tweening away the preloader; does that belong to the preloader part, or the Application part? Preloader definitely, but in this case we didn’t want it to load in the first frame. Therefore, we end up with this extra "catcher" class.

Just remember that this is all optional. Once you know how to do everything you can easily decide whatever your situation requires.

Step 28: Sounds and Extra Assets

In Step 7 I told you about the asset loading problems in CS3. Since this tutorial is aimed towards both users of CS3 and CS4 we will go with the lowest common denominator and use the AssetHolder approach. If you’re using CS4 you can perform the next steps the same way and it will work just the same, or you can skip the AssetHolder approach.

Start by importing the "music.wav" sound from the source files into your FLA.

Go in and export it for ActionScript and make sure you uncheck the "Export in first frame" box in CS3. For CS4 this won’t make much of a difference. I’m using Flash CS4 which you’ve probably figured out by now, so the screenshots show the CS4 dialog box. If you want to you can switch from the default MP3 compression to something more pleasing. That way it won’t sound terrible.

Let’s go through a couple more steps, adding some text to the movie and putting it all in an AssetHolder MovieClip!

Step 29: Create Some Text

Hit Ctrl+F8 to create a new MovieClip symbol. Name it TextHolder and export it for ActionScript, once again (in CS3) making sure the "Export in first frame" box is unchecked.

When creating, you will be "inside" this MovieClip. Type some static text and give it a white color. I’m using the same PixelMix font as before. To create a simulated stroke color, I give it a glow filter effect with the settings seen below.

Step 30: Create the AssetHolder

Create a new layer called AssetHolder. Make a keyframe on the second frame, hit Ctrl+F8 to create a new MovieClip and name it AssetHolder. Do not export this for ActionScript.

In the AssetHolder MovieClip, create three layers called AS, music and Assets. Since “music” is the name of the sound object we’re using, that’s what I’m naming the layer. Now you must put a stop(); call on the first frame of the AS layer.

Next, make a keyframe on the second frame of both the music and Assets layer. Drag the music sound onto the stage when you’re standing on the second keyframe in the music layer. Then do the same with the TextHolder MovieClip onto the Assets layer.

Exit out of the AssetHolder MovieClip and make sure you place it on the second keyframe of the AssetHolder layer on the main timeline. As you’ll notice, the MovieClip is not visible, but it is placable, which is quite cool!

Step 31: Changing the Application Class

Alright, now we just want to make sure we play the sound and show the TextHolder MovieClip. Add this to the Application class’s constructor:

var s:Music = new Music();
s.play();

var textHolder:TextHolder = new TextHolder();
textHolder.x = 120;
textHolder.y = 20;
addChild(textHolder);

Step 32: Preview the Movie

Go ahead and preview the movie. You should now, regardless of whether you’re on CS3 or CS4, be able to simulate a download of this movie and see it preload beautifully starting from 1 percent! Note that it isn’t starting at 0 percent. Had our contents been larger and the preloader smaller then that could have been possible.

Now, you might wonder why you’re staring at this orange cat paired with a short gameshow-esque music tag. This is normal to ask yourself.

Conclusion

Hopefully now you should have all the knowledge you need to preload things the way you want, in a single SWF file! To see the final version of all the class files just download the source files for this tutorial and check them out.

I’m unhealthily obsessed with this subject so I’ll gladly enter into discussion in the comments. Please join in if you have questions or ideas!

In this tutorial I will demonstrate a technique I use to protect code and assets from theft.

Editor’s Note: Thanks to Vaclav for use of his lock icon. Visit Psdtuts+ to see how he made it..

Before We Begin

I used a small project of mine to demonstrate how vulnerable SWFs are to decompilation. You can download it and test yourself via the source link above. I used Sothink SWF Decompiler 5 to decompile the SWF and look under its hood. The code is quite readable and you can understand and reuse it fairly easily.

What Can We do About it?

I came up with a technique for protecting SWFs from decompilers and I’m going to demonstrate it in this tutorial. We should be able to produce this:

The code that is decompiled is actually the code for decrypting the content and has nothing to do with your main code. Additionally, the names are illegal so it won’t compile back. Try to decompile it yourself.

Before we get going, I want to point out that this tutorial is not suitable for beginners and you should have solid knowledge of AS3 if you want to follow along. This tutorial is also about low level programming that involves bytes, ByteArrays and manipulating SWF files with a hex editor.

Here’s what we need:

• A SWF to protect. Feel free to download the SWF I’ll be working on.
• Flex SDK. We will be using it to embed content using the Embed tag. You can download it from opensource.adobe.com.
• A hex editor. I’ll be using a free editor called Hex-Ed. You can download it from nielshorn.net or you can use an editor of your choice.
• A decompiler. Whilst not necessary, it would be nice to check if our protection actually works. You can grab a trial of Sothink SWF Decompiler from sothink.com

Step 1: Load SWF at Runtime

Open a new ActionScript 3.0 project, and set it to compile with Flex SDK (I use FlashDevelop to write code). Choose a SWF you want to protect and embed it as binary data using the Embed tag:

[Embed (source = "VerletCloth.swf", mimeType = "application/octet-stream")]
// source = path to the swf you want to protect
private var content:Class;

Now the SWF is embedded as a ByteArray into the loader SWF and it can be loaded through Loader.loadBytes().

var loader:Loader = new Loader();
addChild(loader);
loader.loadBytes(new content(), new LoaderContext(false, new ApplicationDomain()));

In the end we should have this code:

package
{
    import flash.display.Loader;
    import flash.display.Sprite;
    import flash.system.ApplicationDomain;
    import flash.system.LoaderContext;

    [SWF (width = 640, height = 423)] //the dimensions should be same as the loaded swf's
    public class Main extends Sprite
    {
        [Embed (source = "VerletCloth.swf", mimeType = "application/octet-stream")]
        // source = path to the swf you want to protect
        private var content:Class;

        public function Main():void
        {
            var loader:Loader = new Loader();
            addChild(loader);
            loader.loadBytes(new content(), new LoaderContext(false, new ApplicationDomain()));
        }
    }

}

Compile and see if it works (it should). From now on I will call the embedded SWF the “protected SWF”, and the SWF we just compiled the “loading SWF”.

Step 2: Analyze the Result

Let’s try to decompile and see if it works.

Yey! The assets and the original code are gone! What’s shown now is the code that loads the protected SWF and not its content. This would probably stop most of the first-time attackers who are not too familiar with Flash but it’s still not good enough to protect your work from skilled attackers because the protected SWF is waiting for them untouched inside the loading SWF.

Step 3: Decompressing the SWF

Let’s open the loading SWF with a hex editor:

It should look like random binary data because it’s compressed and it should begin with ASCII “CWS”. We need to decompress it! (If your SWF begins with “FWS” and you see meaningful strings in the SWF it’s likely that it didn’t get compressed. You have to enable compression to follow along).

At first it might sound difficult but it’s not. The SWF format is an open format and there is a document that describes it. Download it from adobe.com and scroll down to page 25 in the document. There is a description of the header and how the SWF is compressed, so we can uncompress it easily.

What is written there is that the first 3 bytes are a signature (CWS or FWS), the next byte is the Flash version, the next 4 bytes are the size of the SWF. The remaining is compressed if the signature is CWS or uncompressed if the signature is FWS. Let’s write a simple function to decompress a SWF:

private function decompress(data:ByteArray):ByteArray
{
    var header:ByteArray = new ByteArray();
    var compressed:ByteArray = new ByteArray();
    var decompressed:ByteArray = new ByteArray();

    header.writeBytes(data, 3, 5); //read the uncompressed header, excluding the signature
    compressed.writeBytes(data, 8); //read the rest, compressed

    compressed.uncompress();

    decompressed.writeMultiByte("FWS", "us-ascii"); //mark as uncompressed
    decompressed.writeBytes(header); //write the header back
    decompressed.writeBytes(compressed); //write the now uncompressed content

    return decompressed;
}

The function does a few things:

1. It reads the uncompressed header (the first 8 bytes) without the signature and remembers it.
2. It reads the rest of the data and uncompresses it.
3. It writes back the header (with the “FWS” signature) and the uncompressed data, creating a new, uncompressed SWF.

Step 4: Creating a Utility

Next we’ll create a handy utility in Flash for compressing and decompressing SWF files. In a new AS3 project, compile the following class as a document class:

package
{
    import flash.display.Sprite;
    import flash.events.Event;
    import flash.net.FileFilter;
    import flash.net.FileReference;
    import flash.utils.ByteArray;

    public class Compressor extends Sprite
    {
        private var ref:FileReference;

        public function Compressor()
        {
            ref = new FileReference();
            ref.addEventListener(Event.SELECT, load);
            ref.browse([new FileFilter("SWF Files", "*.swf")]);
        }

        private function load(e:Event):void
        {
            ref.addEventListener(Event.COMPLETE, processSWF);
            ref.load();
        }

        private function processSWF(e:Event):void
        {
            var swf:ByteArray;
            switch(ref.data.readMultiByte(3, "us-ascii"))
            {
                case "CWS":
                    swf = decompress(ref.data);
                    break;
                case "FWS":
                    swf = compress(ref.data);
                    break;
                default:
                    throw Error("Not SWF...");
                    break;
            }

            new FileReference().save(swf);
        }

        private function compress(data:ByteArray):ByteArray
       {
            var header:ByteArray = new ByteArray();
            var decompressed:ByteArray = new ByteArray();
            var compressed:ByteArray = new ByteArray();

            header.writeBytes(data, 3, 5); //read the header, excluding the signature
            decompressed.writeBytes(data, 8); //read the rest

            decompressed.compress();

            compressed.writeMultiByte("CWS", "us-ascii"); //mark as compressed
            compressed.writeBytes(header);
            compressed.writeBytes(decompressed);

            return compressed;
        }

        private function decompress(data:ByteArray):ByteArray
        {
            var header:ByteArray = new ByteArray();
            var compressed:ByteArray = new ByteArray();
            var decompressed:ByteArray = new ByteArray();

            header.writeBytes(data, 3, 5); //read the uncompressed header, excluding the signature
            compressed.writeBytes(data, 8); //read the rest, compressed

            compressed.uncompress();

            decompressed.writeMultiByte("FWS", "us-ascii"); //mark as uncompressed
            decompressed.writeBytes(header); //write the header back
            decompressed.writeBytes(compressed); //write the now uncompressed content

            return decompressed;
        }

    }

}

As you probably noticed I’ve added 2 things: File loading and the compress function.

The compress function is identical to the decompress function, but in reverse. The file loading is done using FileReference (FP10 required) and the loaded file is either compressed or uncompressed. Note that you have to run the SWF locally from a standalone player, as FileReference.browse() must be invoked by user interaction (but the local standalone player allows to run it without).

Step 5: Uncompressing the Loading SWF

To test the tool, fire it up, select the loading SWF and choose where to save it. Then open it up with a hex editor and scrub through. You should see ascii strings inside like this:

Step 6: Analyze Again

Let’s return back to step 2. While the decompiler didn’t show any useful info about the protected SWF, it’s quite easy to get the SWF from the now uncompressed loader; just search for the signature “CWS” (if the protected SWF is uncompressed search for “FWS”) and see the results:

What we found is a DefineBinaryData tag that contains the protected SWF, and extracting it from there is a piece of cake. We are about to add another layer of protection over the loading SWF : Encryption.

Step 7: Encryption

To make the protected SWF less “accessible” we will add some kind of encryption. I chose to use as3crypto and you can download it from code.google.com. You can use any library you want instead (or your own implementation, even better), the only requirement is that it should be able to encrypt and decrypt binary data using a key.

Step 8: Encrypting Data

The first thing we want to do is write a utility to encrypt the protected SWF before we embed it. It requires very basic knowledge of the as3crypto library and it’s pretty straightforward. Add the library into your library path and let’s begin by writing the following:

var aes:AESKey = new AESKey(binKey);
var bytesToEncrypt:int = (data.length & ~15); //make sure that it can be devided by 16, zero the last 4 bytes
for (var i:int = 0; i < bytesToEncrypt; i += 16)
        aes.encrypt(data, i);

What’s going on here? We use a class from as3crypto called AESKey to encrypt the content. The class encrypts 16 bytes in a time (128-bit), and we have to for-loop over the data to encrypt it all. Note the second line : data.length & ~15. It makes sure that the number of bytes encrypted can be divided by 16 and we don’t run out of data when calling aes.encrypt().

Note: It’s important to understand the point of encryption in this case. It’s not really encryption, but rather obfuscation since we include the key inside the SWF. The purpose is to turn the data into binary rubbish, and the code above does it’s job, although it can leave up to 15 unencrypted bytes (which doesn’t matter in our case). I’m not a cryptographer, and I’m quite sure that the above code could look lame and weak from a cryptographer’s perspective, but as I said it’s quite irrelevant as we include the key inside the SWF.

Step 9: Encryption Utility

Time to create another utility that will help us encrypt SWF files. It’s almost the same as the compressor we created earlier, so I won’t talk much about it. Compile it in a new project as a document class:

package
{
    import com.hurlant.crypto.symmetric.AESKey;
    import flash.display.Sprite;
    import flash.events.Event;
    import flash.net.FileReference;
    import flash.utils.ByteArray;

    public class Encryptor extends Sprite
    {
        private var key:String = "activetuts"; //I hardcoded the key
        private var ref:FileReference;

        public function Encryptor()
        {
            ref = new FileReference();
            ref.addEventListener(Event.SELECT, load);
            ref.browse();
        }

        private function load(e:Event):void
        {
            ref.addEventListener(Event.COMPLETE, encrypt);
            ref.load();
        }

        private function encrypt(e:Event):void
        {
            var data:ByteArray = ref.data;

            var binKey:ByteArray = new ByteArray();
            binKey.writeUTF(key); //AESKey requires binary key

            var aes:AESKey = new AESKey(binKey);
            var bytesToEncrypt:int = (data.length & ~15); //make sure that it can be divided by 16, zero the last 4 bytes
            for (var i:int = 0; i < bytesToEncrypt; i += 16)
                aes.encrypt(data, i);

            new FileReference().save(data);
        }

    }

}

Now run it, and make an encrypted copy of the protected SWF by selecting it first and then saving it under a different name.

Step 10: Modifying the Loader

Return back to the loading SWF project. Because the content is now encrypted we need to modify the loading SWF and add decryption code into it. Don’t forget to change the src in the Embed tag to point to the encrypted SWF.

package
{
    import com.hurlant.crypto.symmetric.AESKey;
    import flash.display.Loader;
    import flash.display.Sprite;
    import flash.system.ApplicationDomain;
    import flash.system.LoaderContext;
    import flash.utils.ByteArray;

    [SWF (width = 640, height = 423)] //the dimensions should be same as the loaded swf's
    public class Main extends Sprite
    {
        [Embed (source = "VerletClothEn.swf", mimeType = "application/octet-stream")]
        // source = path to the swf you want to protect
        private var content:Class;

        private var key:String = "activetuts";

        public function Main():void
        {
            var data:ByteArray = new content();

            var binKey:ByteArray = new ByteArray();
            binKey.writeUTF(key); //AESKey requires binary key

            var aes:AESKey = new AESKey(binKey);
            var bytesToDecrypt:int = (data.length & ~15); //make sure that it can be divided by 16, zero the last 4 bytes
            for (var i:int = 0; i < bytesToDecrypt; i += 16)
                aes.decrypt(data, i);

            var loader:Loader = new Loader();
            addChild(loader);
            loader.loadBytes(data, new LoaderContext(false, new ApplicationDomain()));
        }
    }

}

This is the same as before except with the decryption code stuck in the middle. Now compile the loading SWF and test if it works. If you followed carefully up to now, the protected SWF should load and display without errors.

Step 11: Look Inside Using a Decompiler

Open the new loading SWF with a decompiler and have a look.

It contains over a thousand lines of tough looking encryption code, and it’s probably harder to get the protected SWF out of it. We’ve added a few more steps the attacker must undertake:

1. He (or she) has to find the DefineBinaryData that holds the encrypted content and extract it.
2. He must create a utility to decrypt it.

The problem is that creating a utility is as simple as copy-pasting from the decompiler into the code editor and tweaking the code a little bit. I tried to break my protection myself, and it was quite easy – I managed to do it in about 5 minutes. So we’re going to have to take some measurements against it.

Step 12: String Obfuscation

First we’d put the protected SWF into the loading SWF, then encrypted it, and now we’ll put the final touches to the loading SWF. We’ll rename classes, functions and variables to illegal names.

By saying illegal names I mean names such as ,;!@@,^#^ and (^_^). The cool thing is that this matters to the compiler but not to the Flash Player. When the compiler encounters illegal characters inside identifiers, it fails to parse them and thus the project fails to compile. On the other hand, the Player doesn’t have any problems with those illegal names. We can compile the SWF with legal identifiers, decompress it and rename them to a bunch of meaningless illegal symbols. The decompiler will output illegal code and the attacker will have to go over the hundreds of lines of code manually, removing illegal identifiers before he can compile it. He deserves it!

This is how it looks before any string obfuscation:

Let’s start! Decompress the loading SWF using the utility we created before and fire up a hex editor.

Step 13: Your First Obfuscation

Let’s try to rename the document class. Assuming you’ve left the original name (Main), let’s search for it in the uncompressed loader SWF with a hex editor:

Rename “Main” to ;;;;. Now search for other “Main”s and rename them to ;;;; too.

When renaming make sure that you don’t rename unnecessary strings or the SWF will not run.

Save and run the SWF. It works! And look what the decompiler says:

Victory!!

Step 14: Renaming the Rest of the Classes

Keep renaming the rest of your classes. Choose a class name and search for it, replacing it with illegal symbols until you reach the end of the file. As I said, the most important thing here is to use your common sense, make sure you don’t mess your SWF up. After renaming the classes you can start renaming the packages. Note that when renaming a package, you can erase the periods too and make it one long illegal package name. Look what I made:

After you finish renaming the classes and the packages, you can start renaming functions and variables. They are even easier to rename as they usually appear only once, in one large cloud. Again, make sure you rename only “your” methods and not the built-in Flash methods. Make sure you don’t wipe out the key (“activetuts” in our case).

Step 15: Compress the SWF

After you finish renaming you would probably want to compress the SWF so it will be smaller in size. No problem, we can use the compressing utility we created before and it will do the job. Run the utility, select the SWF and save it under another name.

Conclusion: Have a Final Look

Open it one last time and have a look. The classes, the variables and the method names are obfuscated and the protected SWF is somewhere inside, encrypted. This technique could be slow to apply at first, but after a few times it takes only a few minutes.

A while ago I created an automatic utility to inject the protected SWF for me into the loading SWF, and it worked fine. The only problem is that if it can be injected using an automatic utility, it can be decrypted using another utility, so if the attacker makes a utility for that he will get all your SWF easily. Because of this I prefer to protect the SWFs manually each time, adding a slight modification so it would be harder to automate.

Another nice application of the technique is Domain locking. Instead of decrypting the SWF with a constant string you can decrypt it with the domain the SWF is currently running on. So instead of having an if statement to check the domain, you can introduce a more powerful way to protect the SWF from placement on other sites.

Last thing, you may want to replace the encryption code with your own implementation. Why? We invested efforts in making the crypto code illegal, but the code we use is from a popular open source library and the attacker could recognize it as such. He will download a clean copy, and all the obfuscation work is rendered unnecessary. On the other hand, using your own implementation will require him to fix all the illegal names before he can continue.

Other Protection Methods

Because SWF theft is a big problem in the Flash world, there are other options for protecting SWFs. There are numerous programs out there to obfuscate AS on the bytecode level (like Kindisoft’s secureSWF). They mess up the compiled bytecode and when the decompiler attempts to output code it will fail, and even crash sometimes. Of course this protection is better in terms of security but it costs $$$, so before choosing how to protect your SWF consider the amount of security needed. If it’s about protecting a proprietary algorithm your 50-employee Flash studio has been developing for the past two years, you may consider something better then renaming the variables. On the other hand if you want to prevent the kiddies from submitting false high scores you may consider using this technique.

What I like about this technique is the fact that your protected SWF is left untouched when run. AS obfuscation tampers with the byte code and it could possibly damage the SWF and cause bugs (although I haven’t encountered any myself).

That’s all for today, hope you enjoyed the tutorial and learned something new! If you have any questions feel free to drop a comment.

In this Quick Tip screencast, Daniel Apt demonstrates how to set up your project’s folders, and shows three standard ways of doing so.

View Screencast

In this article, I’m going to give you a chance to see what all the chatter is about and to prepare yourselves for the slow disappearance of the .fla format.

Note: I have included all the files for this example. If you don’t have After Effects don’t dial out. You can still work along because I have also included the XFL file created by After Effects CS4.

Introduction

Richard Galvan, the Flash Products Manager, and I have a most interesting relationship. We both highly respect what the other is doing but to call us great friends would be stretching the term. What Richard does know is that he can bounce ideas off of me and that they will go no further until the idea comes to life. For me, this is great because I can start thinking of ways to let you know what’s up when it happens.

In the case of the XFL format, I first heard about it, prior to the CS4 release, on a rainy street corner in Toronto when Richard and I were in a line waiting for entry into an FITC event. “What would you say,Tom”, asked Richard, “if I were to tell you we are thinking of getting rid of the .fla format?”

This one caught me by surprise but, as Richard walked me through the reasoning behind their thinking it became rather clear that this was a great idea.

In fact it wasn’t ,for me, a complete surprise. The rise of XML over the past few years has given Flash developers the luxury of working with Flash content that is external to the .swf. At the same time using XML with Flash had moved into the realm of “easy to accomplish” from the nightmare it had been. All of this is good but there was a major issue: Flash stored documents in a binary source file, the .fla, which was a proprietary specification. XFL is Adobe’s response to this issue.

Creating an XFL Document

Contrary to what you may have heard Flash can’t create an XFL document. It can only read them. At the moment there are in fact only two applications in the Adobe lineup that can create these docs: After Effects CS4 and InDesign CS4. Here’s how an XFL document is created in After Effects:

Step 1: AET.aep

Open the AET.aep file in After Effects CS4. It is a simple animation of the letters in the Activetuts+ name Raining In and Raining out.

I have used this effect in a couple of XFL demos I have done, not because I am lazy but because the focus here is technique not design. In this case notice the two layers named active tuts + In and active tuts + Out. The other feature to be aware of is that the Comp i’s dimensions are 400 X 100 and the frame rate is 24 frames per second.

Step2: Export

Select File>Export> Adobe Flash Professional (XFL)… which will open the XFL Settings dialog box.

Step 3: Format

Select PNG Sequence from the Format drop down menu.

Your two choices in the Dialog Box section may seem a bit odd. Here’s what they do:

• Rasterize to: You need to decided whether the output will be rasterized to a series of PNG images or an FLV. The PNG choice may strike many of you as being one to be avoided at all costs. Exporting a series of images and then sticking them in the Flash movie is, to say the least, a tad heretical. Not quite. If you select this option, frames that are identical and adjacent to each other are rasterized only once to a single PNG. That PNG is then referenced several times in the XFL document. Use the FLV option if a layer contains video. Clicking the Format Options button launches the FLV/F4V export settings.
• Ignore: Select this to tell After Effects to ignore layers containing unsupported features such as blending modes other than Normal. Choose this and those layers won’t be added to the XFL document.

Step 4: OK

Click OK to close the dialog box and get the process underway.

You will be prompted to choose a location for the XFL file and to give it a name (I used AETuts). When you click the Save button the dialog box disappears. You can quit After Effects and open the folder where you placed the XFL document. Inside you will see the .aep file and the XFL file as well as a report of the process. Create a new folder and place a copy of the XFL file into it. We’ll be using the copy in a moment.

Step 5: Open the XFL File

Launch Flash and, when it opens, use File>Open to navigate to the XFL file. Open it. A progress bar will appear.

Step 6: Examine the Flash File

When the file opens notice how the layers order is preserved, the animations are placed on Motion layers and that the file opens as an Untitled Flash file. Another very subtle change is that the Scene 1 link has been renamed Comp 1. This is the name of the item in After Effects.

Why does the XFL document open as an Untitled Flash document? The reason is because this document is contstructed from the information contained in the XFL document and new documents in Flash always open as Untitled.

So what does all this “information” I have been chattering about look like? Let’s find out.

Step 7: Change the Extension

Quit Flash, navigate to the folder holding the copy of the XFL file and change the XFL file extension to .zip. The icon will change to a .zip file icon. The key aspect of the XFL format, if you pay close attention to what Adobe is saying, is that it is a container format. In fact they are very clear that you should regard an XFL file as a zip file.

Step 8: Uncompress the .zip File

Using the application you use to open .zip files (I use BetterZip on my Mac) open the .zip file. When it opens you will see that your XFL file contains a lot more than you expected. Move the Library folder and the DOMDocument files to your open folder.

Step 9: Open the Library Folder.

The structure of this folder is how the Flash Library is created. The only difference between the two is that the contents of the folders are placed into movieclips when the file is constructed.

Step 10: Open the DOMDocument.xml File

I am not going to get deep into this document but you can see that each element that makes up the animations from the folders is between the <media> </media> tags and how the movieclips with animation are constructed as well.

Conclusion:

The implication of the new format is quite staggering when you really think about it. For example, nothing says you can’t edit one of the images in the Library folder in Photoshop or Fireworks and not have any effect whatsoever on on the Flash timeline. Another is, once this format takes hold, it won’t be odd to see Flash movies authored using XML and Flash being used primarily for the final .swf export.

I am going to leave the final word on this to the master, Colin Moock. When he learned about this change in CS4 he wrote in his blog:

The natural next step in the evolution of XFL authoring would be to take the Flash authoring tool out of the equation altogether. If Adobe were to offer a command-line XFL-to-SWF compiler along with XFL, nearly any decent programmer would be able to create a .swf-authoring tool, even in ActionScript. The Flash developer community itself would finally be able to create its own custom Flash-authoring tools. I wonder who would be the first to nostalgically make Flash 4 for AIR in ActionScript?

Wouldn’t that be neat?

Final Animation Preview

During this tutorial we will be creating the following animation:

Overview

This tutorial will be divided into 4 parts. In each part we will go over the different stages in creating an animation from start to finish. These are the tutorial parts and their contents:

1. Before Animating
   • Drawing the character
   • Planning the animation
2. The Rough Animation
   • Sketching in Flash
   • Key drawings and timing
   • Inbetweens
3. The Clean Animation
   • Clean drawings
   • Optimization
   • Coloring the character
4. Finishing Touches
   • Adding the background
   • Masking
   • Creating a shadow

Part I: Before Animating

In the first part of this tutorial, we will go over the things you need to know before starting to animate. Do not overlook these things; planning your animation before jumping straight into Flash will save you a lot of time later on.

Step 1: Getting to Know Your Character

The very first step in creating an animation is, of course, deciding what you want to animate. In this tutorial, we will be animating this:

He’s a simple spy character I made up some time ago. Because he’s so simple, it’s easy to animate him. If this is your first time attempting to animate, I suggest you give my spy a go before moving on to more complex characters.

So, grab a piece of paper and draw the spy a few times. Frame-by-frame animation means drawing the same thing over and over again, so you should feel comfortable drawing your character. Here’s how I draw him:

Step 2: Key Drawings

Once you know your character inside out, it’s time to start thinking about bringing him to life. Animations are planned through key frames (also called thumbnails). In this tutorial I will refer to them as key drawings so as to not confuse them with Flash’s keyframes. So, what is a key drawing? Key drawings are the drawings that tell the story and define the movement in an animation. In other words, they are a way to summarize the animation in a few drawings. The example below shows how a slight difference in a key drawing can have a big impact on the final animation:

A key drawing must be planned at the start and end of a movement and every time a change in direction or rhythm occurs in the animation. So, take another look at the final animation and sketch the key drawings keeping in mind these pointers. They should look something like this:

Part II: The Rough Animation

When you have gotten the hang of drawing your character and have planned out the animation, it’s time to move on to Flash.

Step 3

Start by opening a new Flash document. The default 12 fps is too low for an animation, so for this tutorial we’ll be using 15 fps.

Step 4

Name the current layer “BG”. Select a light color and sketch the basic background of the scene, in our case, a room. Don’t draw anything fancy, just the elements needed to create the rough animation: walls, floor, and the window.

To sketch in Flash I usually choose a large brush size with pressure sensitivity on and bring the smoothing down to around 10. This gives me more freedom to sketch, as I can vary the stroke thickness as much as I want and have more control over sharp angles because of the low smoothing. I suggest you use the same settings as me. Don’t worry if your strokes look jagged; we can fix that at the end.

Step 5

Now we’re going to recreate the key drawings we made previously. Create a new layer and name it something like “Spy”. In the first frame, sketch the first key drawing you planned before. Again, just draw the basic shapes. It should look something like this:

Step 6

Insert a blank keyframe (F7) in the “Spy” layer. Turn on onion skinning so that you can see the previous frame. With the first drawing as a guide, draw the second key drawing.

Step7

Repeat the same process for the rest of the key drawings. When you’re done, you should have five keyframes with five different key drawings.

Step8

We now arrive at the most important (and probably the most difficult) step in creating an animation: timing; calculating the time between our key drawings. What we do now will determine the whole animation, so it is important that it is done right.

Select the first frame in the “Spy” layer and add a few blank keyframes (F7) between the first and second key drawings. Do the same with the rest keyframes. This is what your timeline should look like:

Step 9

Test the movie (Ctrl+Enter). As you can see, the timing is all wrong, so go back into the .fla to fix it. If the timing between two key drawings is too short, add more blank keyframes between them; if the timing is too long, delete some keyframes.

After tweaking it a bit, test the movie to see if it looks better than before. If it still doesn’t look right apply some more changes. It’s hard to picture the animation with only five keyframes, so don’t worry if it’s not perfect at this stage; we can tweak the timing again later. So far, this is my result:

Step 10

The core of our animation is now complete, but there is still a lot of work to be done. Firstly, we need to add more keyframes to make the animation seem smooth. The drawings that appear between key drawings to complete the animation are appropriately called inbetweens. Drawing inbetweens is quite easy, as we’ve already done most of the work when we made the key drawings.

Select a keyframe between the first two key drawings and turn on onion skinning. With two drawings as a reference, draw the spy halfway between the key drawings in the current frame.

Step 11

Repeat the process. Draw a new keyframe between each of the key drawings. You should have nine keyframes.

Step 12

Test the movie. If the timing still doesn’t look right, now is the time to change it. As I said before, timing is the most important part in animation, so take your time to make sure it’s right. After tweaking keyframes, the animation should look like this:

Step 13

There is little more to explain. Keep adding inbetweens between inbetweens to smooth out the animation until there are no more blank keyframes left. Test your movie to see if anything needs to be fixed. This was my result up to this stage:

Part III: The Clean Animation

The rough animation is now done. In this part of the tutorial we’ll work on drawing the clean version of our character.

Step 14

Create a new folder and name it “rough”. Turn the “BG” and “Spy” layers into guide layers so they will not be shown when the movie is published. Lock both layers and put them in the folder. Create a new layer and name it “Spy” again. In this layer we are going to draw the clean version of our character.

Change the fill color to black and set the brush settings as described in Step 4. Now take out the drawings you made at the beginning. Use them as a reference to draw the spy over the rough drawing.

Step 15

Do the same thing for all of the keyframes. You can use onion skinning to use the previous frame as a reference.

Step 16

Things are definitely looking much cleaner, but they are still not clean enough. Take a close look at the clean drawings. You’ll notice the strokes are jagged. We could leave them as is for this animation, but if we were working on a larger project, we would need to optimize them. Optimizing is a method Flash uses to refine a shape by reducing the amount of curves needed to define the shape.

To optimize the strokes in the animation, select the drawings from all the frames (with “Edit multiple frames” turned on) and click Modify > Shape > Optimize (Crt+Alt+Shift+C). The Optimize Curves dialogue box will open up. You can adjust the amount of smoothing with the slider. Check the “Use multiple passes” box. This will smooth the shape over and over until no further smoothing can be achieved without affecting the shape. When you click OK, message will come up showing the percentage of the curve reduction.

Step 17

Turn off “edit multiple frames” and take a look at your drawings. They are much smoother now, but chances are the optimization has altered (at least slightly) the shapes. You can edit them with the Free Transform Tool (Q). Make sure all drawings are closed and have no gaps.

Step 18

It’s now time to give the spy some color. So grab the Paint Bucket (K) and fill him in! I used #000033 for the head, #010243 for the body, and #FFFFFF for the eyes.

Note: If you click with the Paint Bucket inside the drawing and nothing happens, it means your drawing has a gap somewhere. Find it and close it with the Free Transform Tool.

Part IV: Finishing Touches

The animation is complete, but there are some improvements still left to do. What I explain here are mere suggestions which you do not have to follow word by word, and I will therefore not spend much time on each one.

Step 19: A Clean Background

Now that we’ve colored the spy we need an equally colorful background. The purpose of this tutorial, however, was to show the process of animation, so creating the background is beyond the scope of this tut. But for those who are curious, here’s a quick summery of how it was made:

I recreated the room in Swift3D, a program designed to incorporate 3D elements in Flash. I exported the scene as vectors and opened it in Flash. Lastly, I made some changes to the color and added a yellow glow for the lamp.

You can create your background directly in Flash or any other way want. If you want to use mine, you’ll find it in the source files.

Step 20: Masking

As you have probably already noticed, there’s a small problem that we need to fix. Because the “Spy” layer is on top of the “BG” layer, we can see the spy when he’s supposed to be behind the wall in the first frames. To cover the part of his body that should not be shown we’ll use a layer mask.

Create a new layer, turn it into a mask layer, and appropriately name it “Mask”. Make the “Spy” layer masked. If you’ve been able to follow along this tutorial, you probably know Flash well enough to be familiar with layer masks, but I’ll go over them quickly:

A mask layer contains a filled shape which allows a linked (masked) layer to be seen through it; all empty areas in the mask layer will become invisible in the masked layer.

Our mask must cover the entire spy (in all the frames where part of his body should be hidden) except for the part that sticks out of the window. They say a picture is worth a thousand words, so take a look below:

Note: If you lock both the mask layer and the masked layer, you will see the mask’s effect.

Step 21: The Shadow

The last touch I added to the animation was a soft shadow beneath the spy. Create a black circle in a new layer. Transform it so that it looks like the spy’s shadow.

Convert it into a movie clip and animate it so that is follows the wall and ground below the spy (as I said before, I won’t get into details; you should be able to do this on your own). The animated shadow should look like this:

Step 22: Filters

To make the shadow look like a shadow, lower its alpha to 25% in the Movie Clip Property Inspector. To make it seem soft, add a blur filter in the filters tab with the parameters shown below.

Conclusion

Congratulations! Test your movie, sit back, and relax. You can now call yourself an animator. But keep in mind this is just the beginning! Look around you! There are infinite things to animate! Create your own characters, explore new techniques, develop your own style, and most importantly: have fun animating!

Other References

There are many books on traditional animation which I suggest you take a look at. Three books that stand out are:

• The Illusion of Life: Disney Animation
• The Animator’s Survival Kit
• All About Techniques in Drawing for Animation Production

If you are interested in Flash animation, you should head to biteycastle.com and check out Adam Phillips’s award-winning animations as well as his Bitey Castle Academy.

The purpose of this introduction is not to get into the intricacies of the framework, but to walk you through a rather simple exercise designed to demonstrate some of the possibilities this Open Source project offers you.

Overview:

As many of you may have guessed I am not a hard core coder.

The reason, as I will tell anybody who listens, is that “coding is not hard wired into my genes”. Give me a blank ActionScript panel in Flash and I’ll stare at it for hours. What makes this odd is I can read the code when it is given to me. Think of me as being the kind of guy who will sit in a café in France reading a French book but can’t speak the language.

I need to tell you this now because it’s important you know how I approached the exercise. Also, I want you to clearly understand that even though I have known Josh and Branden for quite a few years, I am not even close to being in their league or part of their “hype machine”. I’m just a guy, like you, who stumbled across something that made my life easier. As a teacher, I’ve been handed a tool that lets me teach AS3 basics in a manner that gives “Visual Learners” immediate feedback.

The thing is, I get that code, like the Flash IDE is a “creative medium”. The stuff that happens when artists and designers get hold of code is awesome to behold. Yet talk to people that are coming into Flash or have discovered they need to know AS3 to expand their creative possibilities and you will hear, “Man, this stuff is hard”. At that point, frustration takes hold and, as they say, “Now you know the rest of the story …”

This brings me to Josh and Branden. They hear the same story from the people they meet in their travels. The thing is, Josh was once in their shoes and what sets him apart from the rest of the pack is that he mastered the fundamentals of code while, at the same time, bringing his awesome Fine Arts talents to his work. He didn’t do it alone.

Branden and Josh first became deeply involved with each other at FlashForward 2000 when they were both relatively unknown and, since then, a deep and profound professional relationship has developed between them. Over the years, Josh has come up with ideas, Branden has wired them up and then Josh rearranged the wiring to take the work to levels neither expected 10 years ago.

What has always struck me, if you have ever seen them at a conference or presentation, is their infectious sense of “wonder” and “fun” when it comes to their collaborations or solo efforts.

With the introduction of ActionScript 3, both Josh and Branden quickly realized “wonder” and “fun” were two words that were disappearing from the Flash community. Creatives avoided code as a creative medium because the language was perceived, among this group, as too complicated or complex to master. The ability to play what I call “What if…” games became too risky because the odds of breaking the project were almost 100% unless you had a deep understanding of OOP.

In many respects, this explains the rise of the “Developer” in the Flash community over the past few years. I am not saying this is a bad thing or “dissing” the developers. It is just that because of the complexity of the language the critical balance of the Designer/Developer partnership became more weighted toward the Developer. Branden and Josh, rather than talk about it, decided to do something about it.

What many people don’t know is the genesis for HYPE was another project, Flow, which essentially tried to make things easier for designers but it fell flat on its face simply because it was too ahead of itself. Rather than give up, Branden retooled Flow and with Josh’s input it evolved into HYPE.

What has me jacked about the HYPE project is that the words “wonder” and “fun” will come back if the creative community gets behind it. As you’re about to discover, you really don’t need a degree in Rocket Science to get hooked by HYPE. All you need is to be unafraid to to play with numbers and values.

Step 1 : Download HYPE.

Be aware that Branden and Josh suggest you have Flash Professional CS4 installed before starting, even though this product will work with CS3.

Step 2: Extension Manager

Unzip the download and double-click the .mxp file to launch the Extension Manager. The Extension Manager will install everything into their ultimate destinations. If you’re curious, explore the HYPE folder- hype_01 – that you have just unzipped. Inside you will find:

• All the help files inside the doc folder.
• Examples of the various HYPE classes, including their corresponding source fla files in the examples folder.
• The HYPE classes, found in the src folder.

Step 3. Launch Flash

Double-click the Setup Classpath.jsfl to launch Flash. All this step does is let Flash know where everything was placed during the install.

That’s it folks. Now it’s time to play.

Getting Caught in the HYPE

The idea for this exercise actually appeared in a tweet sent by Branden a week or so before the HYPE release. He said Josh was having too much fun playing with the SoundAnalyzer in HYPE and posted this link.

The tweet caught my attention because one of the things I love to show is Audio Visualization in Flash. I use it as an example of being fearless around code rather than a full bore ActionScript lesson.. I use myself as the poster child for this and show how, by playing with numbers and changing things I know, the complex can become interesting. I start with a basic visualization and then progress to a full bore light show.

Even though I make it interesting and fun, if I were to get into the nitty-gritty of working with the SoundMixer class and Byte Arrays, I may as well toss a wad of aluminum foil over to the shiny thing the audience is now staring at. They will have dialed out because I’m going way, way over their heads. When I saw Josh’s example I immediately pawed through the code looking for what wasn’t there; the complexity.

Let’s bring the fun back to playing with audio in Flash:

Step 4: New Document

Open a new Flash ActionScript 3.0 document. To get yourself started grab an mp3 audio file. This example uses “Busted Chump”, an ActiveDen demo track, but any audio file from your collection will do.

Step 5: Triangle

Draw a small filled triangle on the stage and convert it to a movieclip named “Triangle”. Once you’ve drawn the triangle and converted it to a movieclip, delete the movieclip from the stage.

Step 6: Symbol Properties

Right-click on the symbol in the Library and open the Symbol Properties. Select Export for Actionscript. Your symbol name will appear as the class. Click OK and disregard the error message that appears.

As you may have guessed, HYPE is going to pull the symbol out of the Library and allow you to play with it using ActionScript. For those of you recoiling from this, keep in mind that at its heart HYPE is a playground that gives creatives the opportunities to play “What if …” games and see the results with very little effort. In the case of this exercise I am going to play three “What if …” games:

1. What if I put the triangles on a grid?
2. What if those triangles on the grid pulsated to the music?
3. What if those pulsating triangles were put into motion?

Step 7: ActionScript

Enter the following ActionScript:

import hype.extended.layout.GridLayout;

var numItems:int = 80;

var gridLayout:GridLayout = new GridLayout(30,30, 70, 50, 10);

  for (var i:uint = 1; i < numItems; ++i) {
  var clip:Triangle = new Triangle();
  gridLayout.applyLayout(clip);
  addChild(clip);
  };

The first “What if ” game involves placing the movieclip in a grid and, to paraphrase Apple, “there is a class for that”. In fact, in HYPE there is a class for practically everything you will want to do. If there isn’t, write one because HYPE is Open Source.

The next line tells Flash you want to put 80 triangles on the stage. Having done that, you now determine how they will appear on the grid by adding the parameters into the GridLayout object. In this case I want the grid to start 30 pixels in from the left of the stage and 30 pixels from the top of the stage. Also, there is to be 70 pixels of space between the triangles on the x axis and 50 pixels of space between the rows. The final parameter tells HYPE that I want to see what happens if there are 10 columns of triangles.

The “for” loop tells HYPE how to place the 80 triangles on the stage. You grab the movieclip out of the library, give it an instance name, then by using the applyLayout() method of the Gridlayout class, lay the objects into the grid using the parameters of the GridLayout object.

Step 8: Test

Save and test the movie.

That was easy and if I want to change up the look all I need to do is to play with the values in the numItem variable and the parameters in the GridLayout object. Don’t like the triangle? Then toss something else – an image, for example – into the movieclip or create a completely different movieclip and use that instead.

What if the triangles were tied to an audio track?

The triangles are on a grid and it is now time for our next “What if …” game. In this case : What if the alpha and scale values of the triangles were tied to an audio track? At this point, many creatives would be, as I said earlier, looking at the “shiny thing” over there. Just keep in mind the whole purpose of HYPE is to let you play, not become a hard-core coder. Let’s have some fun:

Step 9: Import Classes

Click into line 2 of the Script and add the following code:

import hype.extended.behavior.FunctionTracker;
import hype.framework.sound.SoundAnalyzer;

These two classes work together in HYPE. FunctionTracker, in very simple terms, manages the functions that are running and makes sure they are mapped to the specific properties of the target object. In our case, we are going to play with the alpha and scale properties of the triangle as it reacts to the audio track.

The SoundAnalyzer class is where the magic happens. What it does, again in very simple terms, is to turn an audio file into data which can then be played with. What I absolutely adore about this class is I don’t have to write a ton of very complex code to get immediate results. I just need to know what the parameters do and then start playing.

Step 10: SoundAnalyzer Object

Add the following two lines of code after the import statements:

var soundAnalyzer:SoundAnalyzer = new SoundAnalyzer();
soundAnalyzer.start();

All these two lines do is to create the SoundAnalyzer object and switch it on using the start() method (which is how you turn these classes on and off in HYPE). Think of the start() method as nothing more than a light switch.

Step 11: Octaves

Add the following code under the “applyLayout” method in the “for” loop:

  var ranNum:Number = int(Math.random() *7);
  var alphaTracker:FunctionTracker = new FunctionTracker(clip, "alpha", soundAnalyzer.getOctave, [ranNum, 0.01, 1]);
  var scaleTracker:FunctionTracker = new FunctionTracker(clip, "scale", soundAnalyzer.getOctave, [ranNum, 0.5, 4]);

  alphaTracker.start();
  scaleTracker.start();

The key to the visualization is the first three lines of the code block.

The SoundAnalyzer class uses the audio track’s octaves; the values for octaves range from 0 to 7. The first line, therefore, creates a random number based on the maximum octave value allowed. Keep this in mind when playing with this value. Numbers greater than 7 will be rounded down to 7.

The next two lines use the functionTracker class to play with the triangles in the grid. You target the object, tell FunctionTracker which property of the object you want to play with, which function is to be run (getOctave) and which values to use.

In this case we’re going to play with the random octave values- ranNum – and make sure the alpha values range from 1% to 100% alpha based on the “size” of the octave in the audio track. Small numbers mean low alpha, big numbers mean full alpha. Also note that these values must be passed as an Array and that the properties being changed are String values.

The final two lines switch on the functions.

Step 12: Sound

Add the following ActionScript to the end of the code block:

  	var sound:Sound = new Sound();
  	sound.load(new URLRequest("YourAudioTrackGoesHere.mp3"));
	sound.play();

Step 13: Test

Save and test the movie.

What if those pulsating triangles were put in motion?

As you have discovered, this stuff is not hard and, in fact, by simply playing with numbers, you can have a huge amount of fun as you “tweak up” how those triangles pulsate and fade. Now that we have that working, let’s play our final “What if …” game and put them in motion. Here’s how:

Step 14: One More Class

Click once at the end of the class list and add one more class:

import hype.extended.behavior. Oscillator;

This class is an absolute blast to play with because it puts an object on an oscillating wave. Here’s the best part: You don’t need a trigonometry background to do it. In fact, there is no math involved.

Step 15: Define Boundaries

Add the following ActionScript below the import statements:

  var myWidth = stage.stageWidth;
  var myHeight = stage.stageHeight;
  var freq:int= 20;

All this code does is confine the resulting animation to the boundaries of the stage and to set a value for the wave frequency. It is time to play with the grid.

Step 16: Oscillator Object

Add the following code after the “scaleTracker” variable in the “for” loop:

  var ypositionOsc:Oscillator = new Oscillator (clip,"y", Oscillator.sineWave, freq, clip.y, myHeight/3, i/(freq/2));
  var scaleOsc:Oscillator = new Oscillator (clip, "scaleY", Oscillator.sineWave, freq, 5,50, i/(freq/2));
  var rotateOsc:Oscillator = new Oscillator (clip,"rotation", Oscillator.sineWave, freq, 0,90, i/(freq/2));

  yOsc.start();
  sOsc.start();
  rOsc.start();

Again, the Oscillator object, like the FunctionTracker object, doesn’t require a degree in particle physics. The parameters are really simple:

• Which object is going to oscillate?
• Which property- a string- of the object is going to be affected?
• Which wave is to be applied? Your choices are sineWave, sawWave,squareWave and triangleWave.
• What is the wave frequency?
• What is the minimum wave value?
• What is the maximum wave value?
• What wave value do we use to start?

In this case we are applying a sineWave to three properties – y position, yScale and rotation- of the triangle and then using the remaining three parameters to set the look of the wave’s motion.

The remaining three lines switch the Oscillator on. The values I used simply popped out of “I wonder what the animation would look like if I used these numbers?” Nothing more.

Step 17: Test

Save and test the animation.

Conclusion:

This exercise was designed to introduce you to the HYPE framework and give you a chance to kick the tires. I showed you how to install it and then used three “What if … ” scenarios that took a simple triangle and heaved it onto a pulsating and waving grid that was driven by an audio track. In regular ActionScript coding those tasks, to many, would be a reason to “Flee. Screaming. Into the night”.

Instead, you discovered that HYPE is aimed at dialing down the developer side of the Flash equation while bringing the fun back to the designer side. Having completed this exercise it might not be a bad idea to revisit the code with a different point of view. What would that be? In many respects, using HYPE to work out ideas very much follows the creative process. It doesn’t get you bogged down in code but instead, by playing with numbers and values, you get to do what you do best: play ‘What If …’ games.

Good news for all you Flexers, but it’s a different story for all you AS3′ers. Flex allows you to quickly and simply build a service that will interact with your AMFPHP code, but you have to get your hands dirty with AS3. So, I’ve decided that it’s time there’s a decent set of classes out there that help Bob build a site with AS3 using the AMFPHP gateway.

And to throw some more dirt into the mix, we’ll be integrating AMFPHP with CodeIgniter so that we have a fantastic PHP framework for the backend.

As you can see there’s not much to look at, but in fact it’s the basis for our Flash communication classes; we can simply and easily send and receive data objects between the client side and the server side without serialisation.

Before we start…

It’s a logical idea that you’ve had a good delve with ActionScript and PHP. You don’t necessarily have to know how to use CodeIgniter as you could just use a PHP class as a service, but it’s worth knowing PHP.

Step 1: Why Use AMFPHP?

This question gets thrown around a lot. We know that flash can get data from XML, JSON, etc… But AMFPHP uses a different form of encoding called “Action Message Format”. It’s simply sending binary data rather than ASCII. Now there’s lots of blog posts around comparing XML, JSON and AMF, but at the end of the day AMF has these great advantages:

• You don’t need to serialise any data! For example, if you’re passing some objects from PHP to Flash, you need to serialise them as, say, JSON. Flash will then have to parse them in order for them to be usable, this takes time and memory.
• It’s lighter than XML because you’re never duplicating yourself. For example, in XML you have to start with a root tag, then more tags, then closing tags, so you’ll see yourself duplicating tag names and this takes up bandwidth. Further more, XML, just like JSON, needs to be parsed into E4X and this takes time.
• AMF can be fully integrated with your PHP code meaning that you can write less code. I’ll show you this by using CodeIgniter as well as AMF’s standard services.

Remember, AMF isn’t a replacement for XML or JSON, it’s simply another tool in your arsenal when it comes to developing scalable dynamic applications.

Step 2: The Set Up

Fire up your favourite IDE, whether it’s Flex Builder, FDT, FlashDevelop or TextMate and create a new ActionScript project. In addition to this, we’ll be doing some PHP coding too, so get your PHP IDE ready (I recommend Aptana)

Additionally, we’re going to be using GreenSock’s TweenLite class just to give the application a bit of magic.

For those of you who’ve read my recent articles: we’re not going to be delving into PureMVC this time as I wanted the outcome of this article to be a set of classes that you can reuse again, with or without PureMVC.

Step 3: Creating the Base App

Just like with any ActionScript app, we need to set up our base app. I’m just going to start by just creating a simple background for the app, then we’re going to look at creating the text area for the response and buttons to send a string, array, and object to PHP; so create a new file called "App.as" within "src/":

		package
		{
			import flash.display.GradientType;
			import flash.display.Sprite;
			import flash.geom.Matrix;
			import flash.text.Font;

			[SWF( width='600', height='400', frameRate='30', backgroundColor='#000000' )]

			public class App extends Sprite
			{
				[Embed( systemFont='Arial', fontName='Arial', mimeType='application/x-font' )]
				private var arialFont:Class;

				public function App()
				{
					init();
				}

				private function init():void
				{
					var mat:Matrix = new Matrix();
					var bg:Sprite = new Sprite();

					mat.createGradientBox( stage.stageWidth, stage.stageHeight, Math.PI * .5 );

					bg.graphics.beginGradientFill( GradientType.LINEAR, [ 0x333333, 0x000000 ], [ 1, 1 ], [ 0, 255 ], mat );
					bg.graphics.drawRect( 0, 0, stage.stageWidth, stage.stageHeight );
					bg.graphics.endFill();

					addChild( bg );

					Font.registerFont( arialFont );
				}
			}
		}
	

Step 4: Creating the UI

Since we’re going to need some sort of UI for the user to be able to interact with our app, we’re going to have to code one! Now it’s up to you whether you want to create your UI in the Flash IDE (or the new Flash Catalyst IDE, looks nice) but I’m going to be hardcore and code it..

In terms of UI components, we’re after:

• An input text box
• A button
• A text area

It’s just the start to your UI classes, but these are all we’re going to need at the moment.

Step 5: Creating an Input Text Box

Since I believe that re-writing code is just long and unnecessary, let’s create a reusable UI button component. Create a new file called "InputTextField.as" within "src/com/flashtuts/lib/display/ui" and use the following code within it:

		package com.flashtuts.lib.display.ui
    {
    	import flash.display.Sprite;
    	import flash.text.TextField;
    	import flash.text.TextFieldAutoSize;
    	import flash.text.TextFieldType;
    	import flash.text.TextFormat;

    	public class InputTextField extends Sprite
    	{
    		private var minWidth:Number								= 200;

    		private var bg:Sprite;
    		private var field:TextField;

    		public function InputTextField()
    		{
    			bg = new Sprite();

    			addChild( bg );

    			field = new TextField();

    			addChild( field );
    		}

    		public function init(format:TextFormat, width:Number=0, height:Number=0, backgroundColour:uint=0, strokeThickness:Number=0, strokeColour:uint=0, cornerRadius:Number=0, padding:Number=4):void
    		{
    			field.autoSize = TextFieldAutoSize.LEFT;
    			field.defaultTextFormat = format;
    			field.embedFonts = true;
    			field.type = TextFieldType.INPUT;
    			field.width = ( width > 0 ? width - ( padding * 2 ) : minWidth );
    			field.x = padding;
    			field.y = padding;

    			bg.graphics.clear();
    			bg.graphics.lineStyle( strokeThickness, strokeColour );
    			bg.graphics.beginFill( backgroundColour );
    			bg.graphics.drawRoundRect( 0, 0, ( width > 0 ? width : field.width + ( padding * 2 ) ), ( height > 0 ? height : field.height + ( padding * 2 ) ), cornerRadius );
    			bg.graphics.endFill();
    		}

    		public function set text(text:String):void
    		{
    			field.text = text;
    		}

    		public function get text():String
    		{
    			return field.text;
    		}
    	}
    }
	

Now, let’s quickly go through it. We start with our constructor, we construct our two main variables: the background ‘bg’ and the textfield ‘field’ then we add them to the stage:

		public function InputTextField()
		{
			bg = new Sprite();

			addChild( bg );

			field = new TextField();

			addChild( field );
		}
	

Our class relies on the user using the public function "init()" that will draw the background as well as setting up the text field:

		public function init(format:TextFormat, width:Number=0, height:Number=0, backgroundColour:uint=0, strokeThickness:Number=0, strokeColour:uint=0, cornerRadius:Number=0, padding:Number=4):void
		{
			field.autoSize = TextFieldAutoSize.LEFT;
			field.defaultTextFormat = format;
			field.embedFonts = true;
			field.type = TextFieldType.INPUT;
			field.width = ( width > 0 ? width - ( padding * 2 ) : minWidth );
			field.x = padding;
			field.y = padding;

			bg.graphics.clear();
			bg.graphics.lineStyle( strokeThickness, strokeColour );
			bg.graphics.beginFill( backgroundColour );
			bg.graphics.drawRoundRect( 0, 0, ( width > 0 ? width : field.width + ( padding * 2 ) ), ( height > 0 ? height : field.height + ( padding * 2 ) ), cornerRadius );
			bg.graphics.endFill();
		}
	

Then finally we want to be able to set some text (if we need to) and to get any text that the user has entered, so we use get/set functions:

	    public function set text(text:String):void
		{
			field.text = text;
		}

		public function get text():String
		{
			return field.text;
		}
	

You can see that you’re able to set an ample number of variables. You can always come back and change this, but for the time being it works for this tutorial, so let’s continue.

We now want to add this field to our application, so I’ve created a new function called "addTextField()", and called it within "init()", so our app’s code looks like this:

		package
        {
        	import com.flashtuts.lib.display.ui.InputTextField;

        	import flash.display.GradientType;
        	import flash.display.Sprite;
        	import flash.geom.Matrix;
        	import flash.text.Font;
        	import flash.text.TextFormat;

        	[SWF( width='600', height='400', frameRate='30', backgroundColor='#000000' )]

        	public class App extends Sprite
        	{
        		[Embed( systemFont='Arial', fontName='Arial', mimeType='application/x-font' )]
        		private var arialFont:Class;

        		public function App()
        		{
        			init();
        		}

        		private function init():void
        		{
        			var mat:Matrix = new Matrix();
        			var bg:Sprite = new Sprite();

        			mat.createGradientBox( stage.stageWidth, stage.stageHeight, Math.PI * .5 );

        			bg.graphics.beginGradientFill( GradientType.LINEAR, [ 0x333333, 0x000000 ], [ 1, 1 ], [ 0, 255 ], mat );
        			bg.graphics.drawRect( 0, 0, stage.stageWidth, stage.stageHeight );
        			bg.graphics.endFill();

        			addChild( bg );

        			Font.registerFont( arialFont );

        			addTextField();
        		}

        		private function addTextField():void
        		{
        			var textField:InputTextField = new InputTextField();

        			textField.init( new TextFormat( 'Arial', 12, 0x000000 ), 200, 25, 0xFFFFFF, 1, 0x333333, 5 );

        			textField.text = 'Hello';

        			addChild( textField );
        		}
        	}
        }
	

You can see that within the function I’ve created a new text format and passed that, with other parameters too, to our "InputTextField()" class. Fire up a preview and you’ll see your text field in the top left hand corner. Before we position anything, let’s finish the other UI components.

Step 6: Creating a Button

Now that we have our input text area down, let’s create a button that’ll allow us to push the data we enter to AMFPHP. So create file called "Button.as" inside "src/com/flashtuts/lib/display/ui/" and use the following code:

	    package com.flashtuts.lib.display.ui
        {
        	import flash.display.Sprite;
        	import flash.text.TextField;
        	import flash.text.TextFieldAutoSize;
        	import flash.text.TextFormat;

        	public class Button extends Sprite
        	{
        		private var bg:Sprite;
        		private var field:TextField;

        		public function Button()
        		{
        			this.buttonMode = true;
        			this.mouseChildren = false;

        			bg = new Sprite();

        			addChild( bg );

        			field = new TextField();

        			addChild( field );
        		}

        		public function init(text:String, format:TextFormat, backgroundColour:uint=0, strokeThickness:Number=0, strokeColour:uint=0, cornerRadius:Number=0, padding:Number=4):void
        		{
        			field.autoSize = TextFieldAutoSize.LEFT;
        			field.defaultTextFormat = format;
        			field.embedFonts = true;
        			field.mouseEnabled = false;
        			field.text = text;
        			field.x = padding;
        			field.y = padding;

        			bg.graphics.clear();
        			bg.graphics.lineStyle( strokeThickness, strokeColour );
        			bg.graphics.beginFill( backgroundColour );
        			bg.graphics.drawRoundRect( 0, 0, field.width + ( padding * 2 ), field.height + ( padding * 2 ), cornerRadius );
        			bg.graphics.endFill();
        		}
        	}
        }
	

A quick run through: much like our "InputTextField()" class, we construct our two variables ‘bg’ and ‘field’ and also set properties so that this class acts as a button:

	    public function Button()
		{
			this.buttonMode = true;
			this.mouseChildren = false;

			bg = new Sprite();

			addChild( bg );

			field = new TextField();

			addChild( field );
		}
	

Again, just like our "InputTextField()" class, we set up the display of the class:

	    public function init(text:String, format:TextFormat, backgroundColour:uint=0, strokeThickness:Number=0, strokeColour:uint=0, cornerRadius:Number=0, padding:Number=4):void
		{
			field.autoSize = TextFieldAutoSize.LEFT;
			field.defaultTextFormat = format;
			field.embedFonts = true;
			field.mouseEnabled = false;
			field.text = text;
			field.x = padding;
			field.y = padding;

			bg.graphics.clear();
			bg.graphics.lineStyle( strokeThickness, strokeColour );
			bg.graphics.beginFill( backgroundColour );
			bg.graphics.drawRoundRect( 0, 0, field.width + ( padding * 2 ), field.height + ( padding * 2 ), cornerRadius );
			bg.graphics.endFill();
		}
	

Finally we need to adjust our app’s base class like so:

	    package
        {
        	import com.flashtuts.lib.display.ui.Button;
        	import com.flashtuts.lib.display.ui.InputTextField;

        	import flash.display.GradientType;
        	import flash.display.Sprite;
        	import flash.geom.Matrix;
        	import flash.text.Font;
        	import flash.text.TextFormat;

        	[SWF( width='600', height='400', frameRate='30', backgroundColor='#000000' )]

        	public class App extends Sprite
        	{
        		[Embed( systemFont='Arial', fontName='Arial', mimeType='application/x-font' )]
        		private var arialFont:Class;

        		public function App()
        		{
        			init();
        		}

        		private function init():void
        		{
        			var mat:Matrix = new Matrix();
        			var bg:Sprite = new Sprite();

        			mat.createGradientBox( stage.stageWidth, stage.stageHeight, Math.PI * .5 );

        			bg.graphics.beginGradientFill( GradientType.LINEAR, [ 0x333333, 0x000000 ], [ 1, 1 ], [ 0, 255 ], mat );
        			bg.graphics.drawRect( 0, 0, stage.stageWidth, stage.stageHeight );
        			bg.graphics.endFill();

        			addChild( bg );

        			Font.registerFont( arialFont );

        			addTextField();
        		}

        		private function addTextField():void
        		{
        			var format:TextFormat = new TextFormat( 'Arial', 12, 0x000000 );
        			var textField:InputTextField = new InputTextField();
        			var button:Button = new Button();

        			textField.init( format, 200, 25, 0xFFFFFF, 1, 0x333333, 5 );

        			textField.text = 'Hello';

        			addChild( textField );

        			button.init( 'Click on me!', format, 0xCCCCCC, 1, 0x333333, 5 );

        			addChild( button );
        		}
        	}
        }
	

If you ran this in debug you’d see a button over a text field, so nearly there!

Step 7: Create a Text Area

This one won’t be so hard as we’ve done the hard work in the "InputTextField()" class already, so all we’ll need to do is set the height and width of our textarea, a simple enough copy and paste job. So create a new file called "InputTextArea.as" inside "src/com/flashtuts/lib/display/ui/" and use the following code:

	    package com.flashtuts.lib.display.ui
        {
        	import flash.display.Sprite;
        	import flash.text.TextField;
        	import flash.text.TextFieldAutoSize;
        	import flash.text.TextFormat;

        	public class InputTextArea extends Sprite
        	{
        		private var minHeight:Number							= 200;
        		private var minWidth:Number								= 200;

        		private var bg:Sprite;
        		private var field:TextField;

        		public function InputTextArea()
        		{
        			bg = new Sprite();

        			addChild( bg );

        			field = new TextField();

        			addChild( field );
        		}

        		public function init(format:TextFormat, width:Number=0, height:Number=0, backgroundColour:uint=0, strokeThickness:Number=0, strokeColour:uint=0, cornerRadius:Number=0, padding:Number=4):void
        		{
        			field.autoSize = TextFieldAutoSize.LEFT;
        			field.defaultTextFormat = format;
        			field.embedFonts = true;
        			field.multiline = true;
        			field.wordWrap = true;
        			field.height = ( height > 0 ? height - ( padding * 2 ) : minHeight );
        			field.width = ( width > 0 ? width - ( padding * 2 ) : minWidth );
        			field.x = padding;
        			field.y = padding;

        			bg.graphics.clear();
        			bg.graphics.lineStyle( strokeThickness, strokeColour );
        			bg.graphics.beginFill( backgroundColour );
        			bg.graphics.drawRoundRect( 0, 0, ( width > 0 ? width : field.width + ( padding * 2 ) ), ( height > 0 ? height : field.height + ( padding * 2 ) ), cornerRadius );
        			bg.graphics.endFill();
        		}

        		public function set text(text:String):void
        		{
        			field.text = text;
        		}

        		public function get text():String
        		{
        			return field.text;
        		}
        	}
        }
	

I think at this point there’s no need to explain the whole class, but it’s worth mentioning the configuration of the field that allows it to become a text area. We simply added two more properties and set them to true: ‘multiline’ and ‘wordwrap’. These turn the input box into a text area.

So finally, let’s add the last component to the app’s class:

	    package
        {
        	import com.flashtuts.lib.display.ui.Button;
        	import com.flashtuts.lib.display.ui.InputTextArea;
        	import com.flashtuts.lib.display.ui.InputTextField;

        	import flash.display.GradientType;
        	import flash.display.Sprite;
        	import flash.geom.Matrix;
        	import flash.text.Font;
        	import flash.text.TextFormat;

        	[SWF( width='600', height='400', frameRate='30', backgroundColor='#000000' )]

        	public class App extends Sprite
        	{
        		[Embed( systemFont='Arial', fontName='Arial', mimeType='application/x-font' )]
        		private var arialFont:Class;

        		public function App()
        		{
        			init();
        		}

        		private function init():void
        		{
        			var mat:Matrix = new Matrix();
        			var bg:Sprite = new Sprite();

        			mat.createGradientBox( stage.stageWidth, stage.stageHeight, Math.PI * .5 );

        			bg.graphics.beginGradientFill( GradientType.LINEAR, [ 0x333333, 0x000000 ], [ 1, 1 ], [ 0, 255 ], mat );
        			bg.graphics.drawRect( 0, 0, stage.stageWidth, stage.stageHeight );
        			bg.graphics.endFill();

        			addChild( bg );

        			Font.registerFont( arialFont );

        			addTextField();
        		}

        		private function addTextField():void
        		{
        			var format:TextFormat = new TextFormat( 'Arial', 12, 0x000000 );
        			var textField:InputTextField = new InputTextField();
        			var textArea:InputTextArea = new InputTextArea();
        			var button:Button = new Button();

        			textField.init( format, 200, 25, 0xFFFFFF, 1, 0x333333, 5 );

        			textField.text = 'Hello';

        			addChild( textField );

        			textArea.init( format, 200, 200, 0xFFFFFF, 1, 0x333333, 5 );

        			textArea.text = 'Text will appear here that's returned from the server!';

        			addChild( textArea );

        			button.init( 'Click on me!', format, 0xCCCCCC, 1, 0x333333, 5 );

        			addChild( button );
        		}
        	}
        }
	

Finally, let’s just align our UI so it’s usable and set the ‘textField’ and ‘textInput’ so that they’re class wide functions rather than within the "addTextField()" function:

		package
		{
			import com.flashtuts.lib.display.ui.Button;
			import com.flashtuts.lib.display.ui.InputTextArea;
			import com.flashtuts.lib.display.ui.InputTextField;

			import flash.display.GradientType;
			import flash.display.Sprite;
			import flash.geom.Matrix;
			import flash.text.Font;
			import flash.text.TextFormat;

			[SWF( width='600', height='400', frameRate='30', backgroundColor='#000000' )]

			public class App extends Sprite
			{
				private var textField:InputTextField 					= new InputTextField();
				private var textArea:InputTextArea 						= new InputTextArea();

				[Embed( systemFont='Arial', fontName='Arial', mimeType='application/x-font' )]
				private var arialFont:Class;

				public function App()
				{
					init();
				}

				private function init():void
				{
					var mat:Matrix = new Matrix();
					var bg:Sprite = new Sprite();

					mat.createGradientBox( stage.stageWidth, stage.stageHeight, Math.PI * .5 );

					bg.graphics.beginGradientFill( GradientType.LINEAR, [ 0x333333, 0x000000 ], [ 1, 1 ], [ 0, 255 ], mat );
					bg.graphics.drawRect( 0, 0, stage.stageWidth, stage.stageHeight );
					bg.graphics.endFill();

					addChild( bg );

					Font.registerFont( arialFont );

					addTextField();
				}

				private function addTextField():void
				{
					var format:TextFormat = new TextFormat( 'Arial', 12, 0x000000 );
					var button:Button = new Button();

					textField.init( format, 200, 25, 0xFFFFFF, 1, 0x333333, 10 );

					textField.text = 'Hello';

					addChild( textField );

					textArea.init( format, 300, 200, 0xFFFFFF, 1, 0x333333, 10 );

					textArea.text = 'Text will appear here that\'s returned from the server!';

					addChild( textArea );

					button.init( 'Click on me!', format, 0xCCCCCC, 1, 0x333333, 10 );

					addChild( button );

					textField.x = ( stage.stageWidth / 2 ) - ( ( textField.width + button.width + 20 ) / 2 );
					textField.y = 20;

					button.x = textField.x + textField.width + 20;
					button.y = 20;

					textArea.x = ( stage.stageWidth / 2 ) - ( textArea.width / 2 );
					textArea.y = 60;
				}
			}
		}
	

So that’s our base class pretty much finished. Now we’ll move on to writing the classes for AMFPHP communication.

Step 8: Starting With the Basics

I’m assuming that you’ve worked with loading data into Flash player before. When working with static data that’s normally loaded right at the start of your application being loaded, using XML or JSON is fine. It’s also fine with dynamic data, but AMF gives you the advantage of a constant gateway, good performance and, most importantly, less code to write as there’s no need encode or decode the data.

What normally happens when working with data and Flash is you’d normally either load a static file or have XML or JSON dynamically created, for example:

• A static file: ./assets/xml/data.xml
• A dynamic file: http://mydomain.com/data.php?someId=1234

It’s all fair and well loading data, but what if you want to send data? Yep you can of course set up a few classes to send data to your site’s dynamic scripts but then you’ll already have set up a class for retrieving data and then you’ll have to modify it so that it’ll allow you to send data. Plus of course, you’ll need to update your dynamic scripts on your site’s servers. Now this is where AMFPHP is so great, you only need to create one set of classes for ActionScript and then all your PHP code can be contained within one simple code base. I’ll also extend it to show you how you can use a framework, in this case CodeIgniter.

Step 9: Creating the ActionScript Classes

Since AMFPHP is a remote connection service, you may want to create other classes in the future, besides what’s the point of duplicating code? What we’ll do is create three classes:

• "RemoteConnectionService.as": this will act as our base class and will have useful functions that we can use in the future for other remote connection services
• "RemoteConnectionServiceEvent.as": this will act as the events class that the base class will use
• "AMFPHPService.as": and this will be our AMFPHP connection class

This way we’ll be able to create a nice set of classes but also have them clean and scalable should we need to write some new ones in the future.

Step 10: Creating the Base Class

First thing we’ll do is start with the base class. So create a file called "RemoteConnectionService.as" within "src/com/flashtuts/lib/data/" and it’ll extend the "NetConnection" class:

		package com.flashtuts.lib.data
		{
			import flash.net.NetConnection;

			public class RemoteConnectionService extends NetConnection
			{
				public function RemoteConnectionService()
				{
					super();
				}

			}
		}
	

Now we’ve got our class, we need to write some code, so we’ve got to think what functions can be placed within the base rather than be duplicated. I would suggest using the constructor to set up the connection, then using the base to handle any events the connection sends and finally we create a standard function that we will use to send our data.

The first thing to do is to write our constructor:

		package com.flashtuts.lib.data
		{
			import flash.events.NetStatusEvent;
			import flash.net.NetConnection;
			import flash.net.Responder;

			public class RemoteConnectionService extends NetConnection
			{
				public var handleReady:Boolean							= true;

				public var data:Object;
				public var gatewayURL:String;
				public var responder:Responder;

				private var loadedEvent:String;
				private var readyEvent:String;
				private var faultEvent:String;

				public function RemoteConnectionService(gatewayURL:String, loadedEvent:String='', readyEvent:String='', faultEvent:String='', encoding:uint=3)
				{
					this.gatewayURL = gatewayURL;
					this.loadedEvent = loadedEvent;
					this.readyEvent = readyEvent;
					this.faultEvent = faultEvent;

					objectEncoding = encoding;

					if ( gatewayURL )
					{
						responder = new Responder( handleResponseResult, handleResponseFault );

						addEventListener( NetStatusEvent.NET_STATUS, handleNetEvent );

						connect( gatewayURL );
					}
				}
			}
		}
	

Now you may be wondering what on earth all that is, not to fear, here’s a quick run down:

• The public vars:
  Since this class is going to act like a service we need to tell it where the AMFPHP gateway is, therefore we set the ‘gatewayURL’, furthermore in order to have result and fault listeners we have to create a new "Responder()" (you may be wondering why this isn’t through events, maybe Adobe were hungover that day) and we will bind this responder to our calls. Finally it’s always handy to have the ability to store the data we receive from our transactions in an accessible public var, in this case called ‘data’.
• The private vars and ‘handleReady’ var:
  Now since this is the base class for our remote connection service, there may be times when you’ll want to manipulate the data before it’s sent back to your application. Therefore instead of just having a ‘ready’ event fired, I’ve set a ‘loaded’ event too. This will allow you to hook into the service, manipulate the data and then dispatch the ‘ready’ event. By default, any subclasses will define these events as part of the ‘RemoteConnectionServiceEvent()’ class, but we have the ability, when super-ing, to say otherwise, allowing for greater flexibility.

When we construct the class, remember this is a base class so it’ll always be super-ed rather than constructed itself, we pass in the ‘gatewayURL’, the events, and the encoding value (this defaults to ‘3′ which is AMF3 style encoding, perfect for us).

Step 11: Handling the Responses and Event

Now we need to create the event and responder handlers for this class, so let’s add them:

		package com.flashtuts.lib.data
		{
			import com.flashtuts.lib.events.RemoteConnectionServiceEvent;

			import flash.events.NetStatusEvent;
			import flash.net.NetConnection;
			import flash.net.Responder;

			public class RemoteConnectionService extends NetConnection
			{
				public var handleReady:Boolean							= true;

				public var data:Object;
				public var gatewayURL:String;
				public var responder:Responder;

				private var loadedEvent:String;
				private var readyEvent:String;
				private var faultEvent:String;

				public function RemoteConnectionService(gatewayURL:String, loadedEvent:String='', readyEvent:String='', faultEvent:String='', encoding:uint=3)
				{
					this.gatewayURL = gatewayURL;
					this.loadedEvent = loadedEvent;
					this.readyEvent = readyEvent;
					this.faultEvent = faultEvent;

					objectEncoding = encoding;

					if ( gatewayURL )
					{
						responder = new Responder( handleResponseResult, handleResponseFault );

						addEventListener( NetStatusEvent.NET_STATUS, handleNetEvent );

						connect( gatewayURL );
					}
				}

				private function handleNetEvent(e:NetStatusEvent):void
				{
					dispatchEvent( new RemoteConnectionServiceEvent( faultEvent, e.info.code ) );
				}

				private function handleResponseResult(data:Object):void
				{
					dispatchEvent( new RemoteConnectionServiceEvent( loadedEvent, data ) ); 

					if ( handleReady )
					{
						handleLoaderDataReady( data );
					}
				}

				public function handleLoaderDataReady(data:Object):void
				{
					this.data = data;

					dispatchEvent( new RemoteConnectionServiceEvent( readyEvent, data ) );
				}

				private function handleResponseFault(data:Object):void
				{
					dispatchEvent( new RemoteConnectionServiceEvent( faultEvent, data ) );
				}
			}
		}
	

Here you see that we’ve added the responder functions "handleResponseResult()" and "handleResponseFault()". Also, we have the "handleNetEvent()" just incase anything falls on it’s face and finally we have the "handleLoaderDataReady()" that will be called once the data is ready – instead of any hooks you may want to use.

You can see that it’s always dispatching events that you’re able to define. This will allow for greater flexibility and scalability in the long run.

Step 12: Creating the Events Class

Since we’re dispatching events from our service base class, it makes sense to have a default events class. If you’re feeling lazy and can’t be bothered to create your own events class, you can just use this as we’ll specify the class to use these events by default, so create a file called "RemoteConnectionServiceEvent.as" inside "src/com/flashtuts/lib/events/":

		package com.flashtuts.lib.events
		{
			import flash.events.Event;

			public class RemoteConnectionServiceEvent extends Event
			{
				public static const NAME:String							= 'RemoteConnectionServiceEvent';

				public static const LOADED:String						= NAME + 'Loaded';
				public static const READY:String						= NAME + 'Ready';
				public static const FAULT:String						= NAME + 'Fault';

				public var data:Object;

				public function RemoteConnectionServiceEvent(type:String, data:Object=null, bubbles:Boolean=true, cancelable:Boolean=false)
				{
					super( type, bubbles, cancelable );

					this.data = data;
				}
			}
		}
	

It’s a pretty basic events class, we’re extending the standard "Event()" class and adding our own public var called ‘data’ so that we can send data with the event and easily retrieve it through our listeners.

Step 13: Creating the AMFPHP Class

Now our base class and it’s events class are ready, all we need to do is extend the base so that we can use it for our AMFPHP service class. Create a new file called "AMFPHPService.as" inside "src/com/flashtuts/lib/data/":

		package com.flashtuts.lib.data
		{
			import com.flashtuts.lib.events.RemoteConnectionServiceEvent;

			import flash.net.ObjectEncoding;

			public class AMFPHPService extends RemoteConnectionService
			{
				public function AMFPHPService( url:String )
				{
					super( url, RemoteConnectionServiceEvent.LOADED, RemoteConnectionServiceEvent.READY, RemoteConnectionServiceEvent.FAULT, ObjectEncoding.AMF3 );
				}
			}
		}
	

Don’t be confused, it’ll all make sense in a few paragraphs time, let’s start with the constructor: like I’ve said further up, our base class will always be super-ed, so within the constructor we pass the ‘url’ variable given to this class when it’s constructed as well as the events and finally the default encoding. The reason I’m choosing to separate the "AMFPHPService()" class from the "RemoteConnectionService()" class is because it’ll allow for greater flexibility and scalability, as you can write other services that will take advantage of the base, but have different events and functions.

Before we continue, it’s worth talking these special variables called …(rest) which basically means that a function can accept any number of comma-delimited arguments, for example:

Traditionally you’d need to declare a function’s arguments like this:

		function test(arg1, arg2, arg3, arg4):void
		{
			...
		}
	

However with …(rest) arguments you can do this:

		function test(... args):void
		{
			...
		}
	

And call it like this:

		test('var1', 'var2', 'var3', 'var4', 'var5', 'varN', 'varN+1');
	

So you can use any number of variables. These are then accessible in the function as an array, for example:

		function test(... args):void
		{
			trace(args.length);
		}

		test('var1', 'var2'); // traces 2
		test('var1', 'var2', 'var3', 'var4', 'var5'); // traces 5
	

"NetConnection.call()" takes advantage of these …(rest) arguments allowing you to send any number of arguments to your gateway. However, the function also requires you to give the ‘responder’, something that we created within our "RemoteConnectionService()" class. So since we’re always going to need to use this "call()" function but don’t want to write the ‘responder’ variable every time we use it, we should put it within our base class. Go ahead and open up the "RemoteConnectionService()" class then update it with this:

		package com.flashtuts.lib.data
		{
			import com.flashtuts.lib.events.RemoteConnectionServiceEvent;

			import flash.events.NetStatusEvent;
			import flash.net.NetConnection;
			import flash.net.Responder;

			public class RemoteConnectionService extends NetConnection
			{
				public var handleReady:Boolean							= true;

				public var data:Object;
				public var gatewayURL:String;
				public var responder:Responder;

				private var loadedEvent:String;
				private var readyEvent:String;
				private var faultEvent:String;

				public function RemoteConnectionService(gatewayURL:String, loadedEvent:String='', readyEvent:String='', faultEvent:String='', encoding:uint=3)
				{
					this.gatewayURL = gatewayURL;
					this.loadedEvent = loadedEvent;
					this.readyEvent = readyEvent;
					this.faultEvent = faultEvent;

					objectEncoding = encoding;

					if ( gatewayURL )
					{
						responder = new Responder( handleResponseResult, handleResponseFault );

						addEventListener( NetStatusEvent.NET_STATUS, handleNetEvent );

						connect( gatewayURL );
					}
				}

				public function send(method:String, ... args):void
				{
					call.apply( null, [ method, responder ].concat( args ) );
				}

				private function handleNetEvent(e:NetStatusEvent):void
				{
					dispatchEvent( new RemoteConnectionServiceEvent( faultEvent, e.info.code ) );
				}

				private function handleResponseResult(data:Object):void
				{
					dispatchEvent( new RemoteConnectionServiceEvent( loadedEvent, data ) ); 

					if ( handleReady )
					{
						handleLoaderDataReady( data );
					}
				}

				public function handleLoaderDataReady(data:Object):void
				{
					this.data = data;

					dispatchEvent( new RemoteConnectionServiceEvent( readyEvent, data ) );
				}

				private function handleResponseFault(data:Object):void
				{
					dispatchEvent( new RemoteConnectionServiceEvent( faultEvent, data ) );
				}
			}
		}
	

Step 14: Tying it in

Now that our service classes are ready, if we go back to our app’s base class we have to add the service by creating it as a class-wide variable and constructing it within our "init()" function:

		package
		{
			import com.flashtuts.lib.data.AMFPHPService;
			import com.flashtuts.lib.display.ui.Button;
			import com.flashtuts.lib.display.ui.InputTextArea;
			import com.flashtuts.lib.display.ui.InputTextField;

			import flash.display.GradientType;
			import flash.display.Sprite;
			import flash.events.MouseEvent;
			import flash.geom.Matrix;
			import flash.text.Font;
			import flash.text.TextFormat;

			[SWF( width='600', height='400', frameRate='30', backgroundColor='#000000' )]

			public class App extends Sprite
			{
				private var service:AMFPHPService						= new AMFPHPService( 'http://localhost/amfphp/gateway.php' );
				private var textField:InputTextField 					= new InputTextField();
				private var textArea:InputTextArea 						= new InputTextArea();

				[Embed( systemFont='Arial', fontName='Arial', mimeType='application/x-font' )]
				private var arialFont:Class;

				public function App()
				{
					init();
				}

				private function init():void
				{
					var mat:Matrix = new Matrix();
					var bg:Sprite = new Sprite();

					mat.createGradientBox( stage.stageWidth, stage.stageHeight, Math.PI * .5 );

					bg.graphics.beginGradientFill( GradientType.LINEAR, [ 0x333333, 0x000000 ], [ 1, 1 ], [ 0, 255 ], mat );
					bg.graphics.drawRect( 0, 0, stage.stageWidth, stage.stageHeight );
					bg.graphics.endFill();

					addChild( bg );

					Font.registerFont( arialFont );

					addTextField();
				}

				private function addTextField():void
				{
					var format:TextFormat = new TextFormat( 'Arial', 12, 0x000000 );
					var button:Button = new Button();

					textField.init( format, 200, 25, 0xFFFFFF, 1, 0x333333, 10 );

					textField.text = 'Hello';

					addChild( textField );

					textArea.init( format, 300, 200, 0xFFFFFF, 1, 0x333333, 10 );

					textArea.text = 'Text will appear here that's returned from the server!';

					addChild( textArea );

					button.init( 'Click on me!', format, 0xCCCCCC, 1, 0x333333, 10 );

					addChild( button );

					textField.x = ( stage.stageWidth / 2 ) - ( ( textField.width + button.width + 20 ) / 2 );
					textField.y = 20;

					button.x = textField.x + textField.width + 20;
					button.y = 20;

					textArea.x = ( stage.stageWidth / 2 ) - ( textArea.width / 2 );
					textArea.y = 60;
				}
			}
		}
	

And since we’re going to be using the service when the user hits the button, we need to add the event listeners to the buttons and then set up the function that will run our service’s "send()" function to make the call:

		package
		{
			import com.flashtuts.lib.data.AMFPHPService;
			import com.flashtuts.lib.display.ui.Button;
			import com.flashtuts.lib.display.ui.InputTextArea;
			import com.flashtuts.lib.display.ui.InputTextField;

			import flash.display.GradientType;
			import flash.display.Sprite;
			import flash.events.MouseEvent;
			import flash.geom.Matrix;
			import flash.text.Font;
			import flash.text.TextFormat;

			[SWF( width='600', height='400', frameRate='30', backgroundColor='#000000' )]

			public class App extends Sprite
			{
				private var service:AMFPHPService						= new AMFPHPService( 'http://dev.ahmednuaman.com/amfphp/gateway.php' );
				private var textField:InputTextField 					= new InputTextField();
				private var textArea:InputTextArea 						= new InputTextArea();

				[Embed( systemFont='Arial', fontName='Arial', mimeType='application/x-font' )]
				private var arialFont:Class;

				public function App()
				{
					init();
				}

				private function init():void
				{
					var mat:Matrix = new Matrix();
					var bg:Sprite = new Sprite();

					mat.createGradientBox( stage.stageWidth, stage.stageHeight, Math.PI * .5 );

					bg.graphics.beginGradientFill( GradientType.LINEAR, [ 0x333333, 0x000000 ], [ 1, 1 ], [ 0, 255 ], mat );
					bg.graphics.drawRect( 0, 0, stage.stageWidth, stage.stageHeight );
					bg.graphics.endFill();

					addChild( bg );

					Font.registerFont( arialFont );

					addTextField();
				}

				private function addTextField():void
				{
					var format:TextFormat = new TextFormat( 'Arial', 12, 0x000000 );
					var button:Button = new Button();

					textField.init( format, 200, 25, 0xFFFFFF, 1, 0x333333, 10 );

					textField.text = 'Hello';

					addChild( textField );

					textArea.init( format, 300, 200, 0xFFFFFF, 1, 0x333333, 10 );

					textArea.text = 'Text will appear here that's returned from the server!';

					addChild( textArea );

					button.init( 'Click on me!', format, 0xCCCCCC, 1, 0x333333, 10 );

					button.addEventListener( MouseEvent.CLICK, handleButtonClick );

					addChild( button );

					textField.x = ( stage.stageWidth / 2 ) - ( ( textField.width + button.width + 20 ) / 2 );
					textField.y = 20;

					button.x = textField.x + textField.width + 20;
					button.y = 20;

					textArea.x = ( stage.stageWidth / 2 ) - ( textArea.width / 2 );
					textArea.y = 60;
				}

				private function handleButtonClick(e:MouseEvent):void
				{
					service.send( 'HelloWorld.say', textField.text );
				}
			}
		}
	

You’ll see that we’re using a method called ‘HelloWorld.say’, this is a test AMFPHP service and I’ll show you how to create your own later. And finally we need to add listeners to the service so that we can handle the ready event and display the response in the text area:

		package
		{
			import com.flashtuts.lib.data.AMFPHPService;
			import com.flashtuts.lib.display.ui.Button;
			import com.flashtuts.lib.display.ui.InputTextArea;
			import com.flashtuts.lib.display.ui.InputTextField;
			import com.flashtuts.lib.events.RemoteConnectionServiceEvent;

			import flash.display.GradientType;
			import flash.display.Sprite;
			import flash.events.MouseEvent;
			import flash.geom.Matrix;
			import flash.text.Font;
			import flash.text.TextFormat;

			[SWF( width='600', height='400', frameRate='30', backgroundColor='#000000' )]

			public class App extends Sprite
			{
				private var service:AMFPHPService						= new AMFPHPService( 'http://dev.ahmednuaman.com/amfphp/gateway.php' );
				private var textField:InputTextField 					= new InputTextField();
				private var textArea:InputTextArea 						= new InputTextArea();

				[Embed( systemFont='Arial', fontName='Arial', mimeType='application/x-font' )]
				private var arialFont:Class;

				public function App()
				{
					init();
				}

				private function init():void
				{
					var mat:Matrix = new Matrix();
					var bg:Sprite = new Sprite();

					mat.createGradientBox( stage.stageWidth, stage.stageHeight, Math.PI * .5 );

					bg.graphics.beginGradientFill( GradientType.LINEAR, [ 0x333333, 0x000000 ], [ 1, 1 ], [ 0, 255 ], mat );
					bg.graphics.drawRect( 0, 0, stage.stageWidth, stage.stageHeight );
					bg.graphics.endFill();

					addChild( bg );

					Font.registerFont( arialFont );

					addTextField();

					service.addEventListener( RemoteConnectionServiceEvent.READY, handleDataReady );
				}

				private function addTextField():void
				{
					var format:TextFormat = new TextFormat( 'Arial', 12, 0x000000 );
					var button:Button = new Button();

					textField.init( format, 200, 25, 0xFFFFFF, 1, 0x333333, 10 );

					textField.text = 'Hello';

					addChild( textField );

					textArea.init( format, 300, 200, 0xFFFFFF, 1, 0x333333, 10 );

					textArea.text = 'Text will appear here that's returned from the server!';

					addChild( textArea );

					button.init( 'Click on me!', format, 0xCCCCCC, 1, 0x333333, 10 );

					button.addEventListener( MouseEvent.CLICK, handleButtonClick );

					addChild( button );

					textField.x = ( stage.stageWidth / 2 ) - ( ( textField.width + button.width + 20 ) / 2 );
					textField.y = 20;

					button.x = textField.x + textField.width + 20;
					button.y = 20;

					textArea.x = ( stage.stageWidth / 2 ) - ( textArea.width / 2 );
					textArea.y = 60;
				}

				private function handleButtonClick(e:MouseEvent):void
				{
					service.send( 'HelloWorld.say', textField.text );
				}

				private function handleDataReady(e:RemoteConnectionServiceEvent):void
				{
					textArea.text = e.data.toString();
				}
			}
		}
	

That’s our ActionScript classes done! Now on to some PHP!

Step 15: Using AMFPHP

The first thing to do is to go to the AMFPHP web site and download yourself a copy of the code base. Once you’ve got it, uncompress it and stick it on your testing server or run it on your localhost. If you’re new to PHP, it’s worth reading up on it at w3schools.com.

Once you’re happy that you know enough about PHP, it’s time to get your hands dirty! The idea behind AMFPHP is that you can create a set of services and call them much like how you import files in ActionScript, for example:

AMFPHP comes with a standard service called ‘HelloWorld.say’. The class and file are called ‘HelloWorld’ and the function is called ’say’. AMFPHP goes to the services folder, finds a file called ‘HelloWorld.php’, constructs the class called ‘HelloWorld’ and then runs the function called ’say’. If you were to have a class called ‘Test’ that belonged to the ‘com.flashtuts’ code base, so you created a file called ‘Test.php’ inside the folders ‘com/flashtuts/’ then you would reference the service like ‘com.flashtuts.Test.function’. Simple eh?

The first thing we’re going to do is just get our PHP class to return a simple string and then we’ll move on to integrating CodeIgniter.

Step 16: Saying Hello Back

Since we’ve defaulted the text in our input field to say ‘Hello’, we may as well say something back, so create a new file called "HelloWorld.php" inside the "services" folder in your AMFPHP folder and use the following class:

		<?php
		/* include the AMFPHP utils */
		include_once( AMFPHP_BASE . 'shared/util/MethodTable.php' );

		class HelloWorld
		{
			function say($msg)
			{
				return 'You said: ' . $msg;
			}
		}

		?>
	

Now if you fire up your application you’ll see that the server will return ‘You said: (whatever you said, probably hello!)’ in the text area, without the bracket bit at the end. Yay, you’ve used AMFPHP, good work! Let’s get a bit deeper.

Step 17: Using a Database

We’ve returned what we sent to the server, but who wants that eh? Surely we’d want to store something in the database right? So, let’s sort that out. Open up the file "globals.php" in the AMFPHP base directory and you’ll see a bit of code that’s commented out like this:

		/*
		if(!PRODUCTION_SERVER)
		{
			define("DB_HOST", "localhost");
			define("DB_USER", "root");
			define("DB_PASS", "");
			define("DB_NAME", "amfphp");
		}
		*/
	

You can either copy this and paste it underneath or just uncomment it, we’ll be using it to set our DB access. So enter your DB username, password and database, so it looks like this:

		if(!PRODUCTION_SERVER)
		{
			define("DB_HOST", "localhost");
			define("DB_USER", "bob");
			define("DB_PASS", "bobsCatsName");
			define("DB_NAME", "bobsDatabase");
		}
	

Now we’re ready to alter our PHP class, so load up the "HelloWorld.php" service class and paste the following inside:

		<?php
        include_once( AMFPHP_BASE . 'shared/util/MethodTable.php' );

        class HelloWorld
        {
        	var $db;

        	function __construct()
        	{
        		$this->db = mysql_connect( DB_HOST, DB_USER, DB_PASS );
        		mysql_select_db( DB_NAME );
        	}

        	function say($msg)
        	{
        		return 'You said: ' . $msg;
        	}

        	function put($data)
        	{
        		$query = mysql_query( 'INSERT INTO hello_world ( id, data ) VALUES ( \'\', \'' . $data . '\' )', $this->db );

        		if ( $query )
        		{
        			return mysql_insert_id();
        		}
        		else
        		{
        			return mysql_error();
        		}
        	}
        }

        /* End of file HelloWorld.php */
        /* Location: ./services/HelloWorld.php */
        ?>
	

Here’s a quick run through:

• We create a class wide variable called $db, we’ll use this to store our database connection so that we won’t need to reconnect within our functions
• The "__construct()" function sets up the database connection for us
• The "put()" function inserts the string $data into a table called ‘hello_world’ within our database

Cool yea? let’s try it out. Change the method in your ActionScript app to ‘HelloWorld.put’, fire up the debug and have a go. Then use your SQL browser or phpMyAdmin to check the results in your database. You should see the insert id returned in your text area.

Step 18: Tying in CodeIgniter

Now stopping with the above is fine, you can go ahead and make a few classes and functions that will suit your site’s needs, but what if you have bigger aspirations? We all know that building apps can be faster when using frameworks and CodeIgniter is a great framework. I don’t want to get into the argument of which framework to use because at the end of the day CodeIgniter works for me for a few simple reasons:

• It’s lightweight
• It’s simple to install
• It’s easy to learn
• It’s got good community support
• And it’s free!

There are other frameworks out there, but for this tut I’m going to show you how you can hook CodeIgniter into the AMFPHP platform.

Step 19: Installing CodeIgniter

Grab yourself a copy of CodeIgniter from their site, decompresss it and stick it up on your server or localhost. It’s pretty simple to install but for the time being we don’t need to set up a database or anything like that. For future reference, have a read of their user guide. So if you then load up your browser and point it towards where you’ve put CodeIgniter you’ll see something like this:

Step 20: Creating the Hook

Ok, now we need to modify CodeIgniter’s output by using a hook. A hook is simply a method that allows us to ‘hook’ into the core of the system without directly editing CodeIgniter’s code. So we need to edit CodeIgniter’s config so that we can enable hooks, register our hook and then write our hook. Within your CodeIgniter directory open up "system/application/config/config.php", scroll down to line 91 and change the variable to true:

	   $config['enable_hooks'] = TRUE;
	

Now open up "hooks.php" in the same folder and add the following code before the ‘/* End of file … */’ line (so add it to line 13):

	    $hook['display_override'] = array(
        								'class'		=> 'AMFPHP',
        								'function'	=> 'output',
        								'filename'	=> 'amfphp.php',
        								'filepath'	=> 'hooks'
        							);
	

What we’re telling CodeIgniter here is that we want it to override it’s display output method and instead re-route everything to our hook class called ‘AMFPHP’ within the ‘hooks/amfphp.php’ file. Since that fine doesn’t exist, create the file "system/application/hooks/amfphp.php" and use the following code:

	    <?php if ( !defined('BASEPATH') ) exit( 'No direct script access allowed' ); 

        class AMFPHP
        {
        	function output()
        	{
        		if ( !defined( 'AMFPHP' ) )
        		{
        			$CI =& get_instance();

        			$CI->output->_display( $CI->output->get_output() );
        		}
        	}
        }

        /* End of file amfphp.php */
        /* Location: ./system/application/hooks/amfphp.php */
        ?>
	

All we’re doing here is telling CodeIgniter to write its output. This way we’re controlling the system by checking to see we’re not making a request via AMFPHP so it can display the code as normal, otherwise AMFPHP won’t work.

Step 21: Creating the Controller

Ok we’re nearly there, all we have to do now is create our controller so that we can return the data back to the AMFPHP gateway. Create a file called "system/application/controllers/main.php" and paste this in the file:

	    <?php if ( !defined('BASEPATH') && !defined('AMFPHP') ) exit( 'No direct script access allowed' ); 

        class Main extends Controller
        {
        	function __construct()
        	{
        		parent::Controller();
        	}

        	function index()
        	{
        		global $value;

        		$value = $_POST;
        	}
        }

        /* End of file main.php */
        /* Location: ./system/application/controllers/main.php */
        ?>
	

All we’re going to do here is just return the variables we sent to AMFPHP as an array rather than as the string we sent. This will show you how magic AMFPHP is, the fact that you don’t need to serialise objects before sending them back and forth is a great asset and speeds things up.

Step 22: Configuring AMFPHP

We’re really nearly there! We now need to create a service that will invoke the CodeIgniter framework. This service will act in the same way as the "HelloWorld.php" service we created, but will instead fire up CodeIgniter so that we can access all of it’s goodness. Create a new file inside your AMFPHP directory "services/CI.php" and paste in the following code:

	    <?php
        include_once( AMFPHP_BASE . 'shared/util/MethodTable.php' );

        class CI
        {
        	function execute($path='', $vars=false)
        	{
        		global $value;

        		define( 'AMFPHP', true );

        		if ( $vars && is_array( $vars ) )
        		{
        			$_POST = $vars;
        		}

        		$_SERVER['PATH_INFO'] = $_SERVER['QUERY_STRING'] = $_SERVER['REQUEST_URI'] = '/' . $path;

        		require_once( '../../codeigniter/index.php' );

        		return $value;
        	}
        }

        /* End of file CI.php */
        /* Location: ./services/CI.php */
        ?>
	

We define a function called "execute()" where we will pass the URL of our ’spoof’ CodeIgniter method (if you’re confused, it works on the basic principle of MVC URLs where by the application responds to URL patterns like http://host/controller/function/value1/value2/valueN, you can find out more here: http://codeigniter.com/user_guide/general/urls.html) and the values for that method. In then requires the ‘index.php’ file of your CodeIgniter app, make sure it can find this by the way!

Step 23: One Last Configuration Item

You’re so close! One last thing to do is to tell CodeIgniter to only explicitly show errors, so open up the "index.php" file in your CodeIgniter directory and edit line 12 to be:

	    error_reporting(E_ALL ^ E_NOTICE);
	

We’re telling PHP not to display any notice errors, only full fat ones!

And that’s the PHP side down! All we need to do now is go back to our ActionScript code and change the method, so open up your app’s base file and change the method and values we send like so:

	    private function handleButtonClick(e:MouseEvent):void
        {
			service.send( 'CI.execute', 'main', [ textField.text, 'another var', 1, 0xFFFFFF, { data: 'test', data2: 'test2' } ] );
		}
	

Here we’re sending an Array rather than a number of values. This is easier and means that you can have your gateway receive the method (as the ‘URL’) and the data as an Array.

There we have it! You’ve just dug deep into AMFPHP from both the ActionScript and PHP side! Congrats!

Conclusion

While some people may ask what’s the point of this, there will be times within a professional developers life where he or she will need to use AMFPHP when it comes to sending and receiving data. And while XML and JSON work just fine, the beauty with AMFPHP is that when you’ve set up the classes (as you just have) you don’t have to worry about the joys of serialising data and parsing it at the receiving end as it’s all done for you!

For those of you who aren’t familiar with unit testing let’s see what Wikipedia has to say

In computer programming, unit testing is a software verification and validation method where the programmer gains confidence that individual units of source code are fit for use… Unit tests are typically written and run by software developers to ensure that code meets its design and behaves as intended. – wikipedia

In this tutorial I’ll show you how I set up a few simple unit tests on my Flash Camo framework. You’ll need to download a copy of Flash Builder 4 (in Beta right now) to follow along. Also, you’ll want to download the latest version of Flash Camo (2.2.1) from here.

Step 1: Setting up a Unit Test Project

Let’s create a new project called UnitTestIntro.

We’ll need to place our Flash Camo SWC into a libs/swcs folder inside our project:

Finally we’ll need to tell our project where to find our SWC, right-click on the project and go into its properties. Go to the ActionScript Build Path and select the Library Path tab. Click on Add SWC Folder and point it to the lib/swcs directory.

Now that we have everything setup, we can begin doing some basic unit testing. It’s important to note that you cannot do unit testing directly in a Flex Library Project. That’s not an issue for this project but if you want to test a library of code what I usually do is set up a new project (like we are doing here) then link the two projects together and create all the tests in the new project.

If you are not working in a Flex Library project and want to test your code you can simply create your tests in the same project. I would suggest keeping the two separate, this way you can clearly see what are test classes and what are real classes. We’ll get into this a little later when you see how we set up the test.

Step 2: Drafting a Plan

Before I start anything, I take a moment to figure out exactly what I’m going to do. This is very critical when setting up unit tests. This kind of development is called Test Driven Development. I think I see another definition coming up:

Test-driven development (TDD) is a software development technique that uses short development iterations based on pre-written test cases that define desired improvements or new functions. Each iteration produces code necessary to pass that iteration’s tests. Finally, the programmer or team refactors the code to accommodate changes. A key TDD concept is that preparing tests before coding facilitates rapid feedback changes. – wikipedia

Since this is a short intro we’re going to use an existing code library to test against. However, as you build your own application you should be writing tests along the way to validate that the code works and that any changes/refactoring doesn’t break your code’s implementation. Here’s an outline of the tests we’ll perform:

• Create an instance of a CamoPropertySheet.
• Validate that it can parse CSS.
• Test the number of selectors it found.
• Test that the CamoPropertySheet can be converted back to a string.
• Test what happens when we request a selector that was not found.
• Validate clearing a CamoPropertySheet.

If you’re new to Flash Camo you can check out the intro I wrote (part 1 and part 2) but you can easily do this tutorial without any knowledge of how the framework works. Again, this is simply going to be a code library for us to test with.

Step 3: Creating Our First Test

Now that we have a plan for doing our testing, let’s create our first test. Right-click on your project and select New > Test Case Class

You will now be presented with the creation wizard. It should be familiar to anyone who has created a class in Flex/Flash Builder before. Here is what the window looks like:

Let’s talk about a few of the new fields in the wizard. We can start with the fact that Superclass is already filled in for us: flexunit.framework.TestCase. You can’t change this and probably shouldn’t. All this does is extend the base test class from the Unit Test Framework. Next you’ll see a few check boxes for code generation. Leave all of these checked by default. Finally there is a field for the Class we want to test.

Since we’re going to test Flash Camo’s CamoPropertySheet let’s fill the following values into the form:

Name: CamoPropertySheetTest
Class to test: camo.core.property.CamoPropertySheet

Here’s a screen shot of how I set this up:

Hit finish and we should have our first test ready for us to add some code to.

Step 4: Anatomy of a TestCase Class

Let’s take a look at the code Flash Builder has generated for us:

We start out by having a private property called classToTestRef which is set to the value of our CamoPropertySheet. This allows the test to create an instance of this class and forces the compiler to import it when we run our test.

The next important method is setUp. This is where we’ll create an instance of our test class, configure it and make sure everything is ready for us to perform a test.

The last method here is tearDown. This is where we’ll destroy our test class’ instance when the test is complete. This is very important when running multiple tests.

You may have noticed at the end of the class there’s another method called testSampleMethod which is commented out. This is an example of how you would set up a single test.

Each test will be a method we add to this class. When we run the Unit Test Harness it will automatically call all of our methods dynamically, of course starting with setUP and finishing with tearDown.

Now that we have a basic understanding of the TestClass setup let’s look at running it.

Step 5: Running the Unit Test

Before we can run this we’ll need at least one test. Let’s uncomment the testSampleMethod for this example.

Once you’ve uncommented the testSampleMethod let’s right-click on our project and select Run As > Execute FlexUnit Test.

You should now see the following window prompting us to select which test we want to run.

As you see, this is set up for when we have lots to test but for now we only have one testSampleMethod to run. Click Select All and hit OK.

After the test is run, your web browser will pop up with the following page:

If you go back to Flash Builder you’ll also see this in the FlexUnit Results panel:

See how easy this was to run? We’ve performed our first unit test and already we have a single error. Before we move on to fix this error let’s talk about these two windows.

The webpage that was open should automatically close but sometimes it doesn’t. This is a simple swf that performs our tests in FLash and outputs some data the Flash Builder reads to display to final results of the test. You can ignore this webpage for the most part.

The FlexUnit Results panel is where all of the results will be shown as well as a place that allows you to organize and filter the test feedback. We’ll go over this a little later in the tutorial when we actually have something to test.

Step 6: Set Up

Before we can really get into testing we’ll need to setup our test class. let’s add the following code to the setUp method:

var xml:XML = <css><![CDATA[/* This is a comment in the CSS file */
							baseStyle {
								x: 10px;
								y: 10px;
								width: 100px;
								height: 100px;
								padding: 5px;
								margin: 10px;
							}

							baseStyle .Button{
								x: 0px;
								y: 0px;
								background-color: #000000;
							}

							#playButton {
								background-color: #FFFFFF;
							 	background-image: url('/images/full_screen_background.jpg');
							}

							#fullScreenButton{
								background-color: #FF0000;
								background-image: url('/images/full_screen_background.jpg');
							}

							#playButton:over {
								background-color: #333333;
							}

							interactive {
								cursor: hand;
							}
									]]>
										</css>;
rawCSS = xml.toString();
sheet = new CamoPropertySheet();
sheet.parseCSS(rawCSS);

We’ll also need to setup some properties:

private var sheet:CamoPropertySheet;
private var rawCSS:String;

Here’s what’s happening in this setup: in order for us to test our CamoPropertySheet we are going to need some CSS as a string. Normally I would load in the CSS from an external file but since we’re doing a simple test I just create a new XML block and put the CSS text inside of the first node. Normally, you don’t have to wrap CSS for the CamoPropertySheet inside of XML but when working with large strings inside of the editor I find it easier to use xml since you can wrap the text and it retains some formatting.

Next you’ll see that we set our rawCSS property to the xml’s string value. This converts the xml into a string. Then we create a new CamoPropertySheet. Finally, we tell the sheet to parse the rawCSS.

That’s all there is to setting up this particular class. The setup is different for each class you test. It is important to demonstrate that we’re doing the bare minimum to get a class ready to be tested and we can’t test a class without values can we?

Step 7: Our First Test

Let’s get right to it. Once a CamoPropertySheet has successfully parsed a css string we can request an array of Selector names to verify everything has indeed been parsed. For those not familiar with CSS jargon, a selector is the name of a css style ie baseStyle{…} would have a selector called baseStyle.

In here is what our test would look like in English:

1. Get a list of selectors from the CamoPropertySheet.
2. Get the length of the selector array.
3. Compare the length value to 6 (the number we are expecting returned).

Let’s replace our testSampleMethod with the following method:

public function testParseCSS():void
{
	var selectors:Array = sheet.selectorNames;
	var total:Number = selectors.length;

	assertEquals(total,6);
}

As you can see we get an array of selector names. Next we get the total and introduce our first test assetEquals. In the next step I’ll explain the assertMethods in more detail, but let’s just run this and see if the test passes.

When you run the test you should see the following in the FlexUnit Results panel:

Nice, our test passed. We received the exact number of selectors that we were expecting. Let’s look at what assert tests we can use.

Step 8: Assertions

In unit testing we run assertions. Each assertion handles a particular type of test. Here is a brief overview of the most common assertions you will probably use:

• assertEquals – test to see if one value equals another.
• assertFalse – test to see if value equals false.
• assertNotNull – test to see if value is not equal to null.
• assertNotUndefined – test if value is not undefined.
• assertNull – test if value is null.
• assertStrictlyEquals – test to see if two values strictly equal each other.
• assertTrue – test to see if value is true.
• assertUndefined – test to see if value is undefined.

Now, before we test an example of each one let’s set up our tearDown method.

Step 9: Tear Down

This is going to be a very short step but it’s a very important one. Let’s add the following line to our tearDown method after super.tearDown():

sheet = null;

What this basically does is remove the reference to our CamoPropertySheet so the Garbage Collector can remove it.

You should always set up your tearDown especially when running multiple test classes or a large test suite.

Step 10: Assert Equals

We’ve already seen an example of this before in Step 7, but let’s go through and add another assertEquals. Here is the next test we’ll perform:

1. Compress CSS text (remove white spaces, special characters and other obstacles the css parser may not be able to recognize) since the CamoPropertySheet automatically compresses css test when it is parsed.
2. Convert the CamoPropertySheet into text (this will be a compressed version of the rawCSS we used earlier).
3. Compare that the CamoPropertySheet text is equal to our compressed css string.

In order to run the test, let’s add the following method:

public function testToString():void
{
	var compressedCSS:String = "baseStyle{x:10;y:10;width:100;height:100;padding:5;margin:10;}baseStyle .Button{x:0;y:0;background-color:#000000;}#playButton{background-color:#FFFFFF;background-image:url('/images/full_screen_background.jpg');}#fullScreenButton{background-color:#FF0000;background-image:url('/images/full_screen_background.jpg');}#playButton:over{background-color:#333333;}interactive{cursor:hand;}";
	assertEquals(sheet.toString(), compressedCSS);
}

Now run the Unit Test and make sure you select both tests from the check boxes. New tests don’t automatically get selected. If everything went well you should see a success and that 2 tests were run.

Step 11: Assert False

We can do a simple test to make sure if we request a Selector that doesn’t exist we get a false value. Here’s how we would do this with the CamoPropertySheet:

1. Make a request for a selector that doesn’t exist.
2. Check the returned selector’s name to see if it equals “EmptySelector” – a constant on the PropertySelector class.
3. Assert if the value is false.

Here is the code to perform the test:

public function testEmptySelector():void
{
	var selector:PropertySelector = sheet.getSelector("testSelector");
	var exists:Boolean = (selector.selectorName == PropertySelector.DEFAULT_SELECTOR_NAME) ? false : true;

	assertFalse(exists);
}

As you can see, we’re simply requesting a fake style name testSelector. We check to see if the selector’s name is the default name applied when no selector is found. Finally we pass the exists variable to the assertFalse method. When you run this you should now see 3 passes totaling a success.

Step 12: Assert Not Null

Next we want to make sure that the text value from our CamoPropertySheet is never null. Let’s look at how to structure our test:

1. call toString on our CamoPropertySheets instance and test to see if it is not null

Here’s our test method:

public function testCSSValue():void
{
	assertNotNull(sheet.toString());
}

This is pretty straight forward so when you run the test we should now have 5 successes. Every time we run the test we can check to see the names of our method tests by clicking on the Default Suite folder our FlexUnit Results Panel back in Flash Builder.

Step 13: Assert Not Undefined

In this next test we’re going to follow up on the empty selector test to verify that every selector has a selectorName.

1. Get a selector that doesn’t exist.
2. Get a selector that does exist.
3. Test to see if both selectors’ names are not undefined.

Here is the test method:

public function testSelectorsHaveNames():void
{
	var selectorA:String = sheet.getSelector("testSelector").selectorName;
	var selectorB:String = sheet.getSelector("baseStyle").selectorName;

	assertNotUndefined(selectorA, selectorB);
}

The first two lines are self explanatory; we simply ask for two selectors and one of which we know does not exist. When we do the assert however you’ll notice we’re passing in two values instead of the normal one we’ve done up until this point. This is not a unique example, in fact each of the assert methods allow you pass in any number of values to test. Here we simply make sure that selectorA and selectorB are not undefined.

Step 14: Assert Strictly Equals

Here is an example of how to strictly compare two objects. Here I’m using strings which may not be the best use of this example but it’s good to see the test in action. What are we going to do?

1. Clone the CamoPropertySheet.
2. Test that the string value of our CamoPropertySheet is equal to the value of a cloned CamoPropertySheet.

public function testClone():void
{
	var clone:CamoPropertySheet = sheet.clone() as CamoPropertySheet;

	assertStrictlyEquals(sheet.toString(), clone.toString());
}

As you can see we call the clone method of the CamoPropertySheet to get back an exact copy of the PropertySheet. Next we run it through the assert test by calling the toString method on each. If the returned CSS test is the same we have a success for the test.

Step 15: Assert True

Now we want to test that when we request a selector, it has a property we are expecting. Here is the test:

1. Request the baseStyle selector.
2. Test to see if the selector has the property x.

Here is the test method:

public function testSelectorHasProperty():void
{
	var selector:PropertySelector = sheet.getSelector("baseStyle");
	assertTrue(selector.hasOwnProperty("x"));
}

As you can see here we are expecting our baseStyle selector to have the x property. If this exists we can assume that it was correctly parsed from the CSS string. Since it exists we have passed this test.

Each of these tests becomes self explanatory as to how you implement them. Let’s look into what happens when we fail a test in the next two steps.

Step 16: Assert Undefined

We’re going to test for undefined now but Flash Camo has been designed to not return undefined. So the following test will fail. Let’s check out what we’re going to test for.

1. Call the clear method on the CamoPropertySheet.
2. Test to see if calling toString will return undefined.

Here’s the code for the test:

public function testClear():void
{
	sheet.clear();
	assertUndefined(sheet.toString());
}

Now let’s run this test and go onto the next step to discuss the results.

Step 17: Failing A Test

If you did the previous step and ran the unit test, you should see the following in the FlexUnit Results panel:

Notice how we have 1 failure from our testClear method?

If you double-click on the failed test in the Test Results panel you will jump to the source of the test that failed. This is a great way to correct your mistake or alter the test so it doesn’t fail. There isn’t much more to failing a test then this. Every test that fails will show up in this panel, you can tell the panel to only show failed tests by clicking on the red exclamation mark above where it tells you how many errors you had.

Now that we have failed this test replace it with the following:

public function testClear():void
{
	sheet.clear();
	assertEquals(sheet.toString(),"");
}

If you run the test again you’ll see that it will pass. Now you have 7 out of 7 passed tests and this class is successfully working. Let’s talk about setting up unit tests for your own custom classes.

Step 18: Auto Generating Test Classes

Up until this point we have been testing a precompiled library, but you may be interested in how this will work on your own classes. We’re going to alter the doc class a little then run a custom unit test on it. To get started, replace all of the code in the UnitTestIntro class with the following:

package
{
	import flash.display.Sprite;

	public class UnitTestIntro extends Sprite
	{

		private var _firstName:String;
		private var _lastName:String;
		private var _loggedIn:Boolean;

		public function UnitTestIntro()
		{
			_firstName = "Jesse";
			_lastName = "Freeman";
		}

		public function get firstName():String
		{
			return _firstName;
		}

		public function get lastName():String
		{
			return _lastName;
		}

		public function isLoggedIn():Boolean
		{
			return _loggedIn;
		}
	}
}

Once you have the code in place, right-click on UnitTestIntro and select New > Test Case Class. If you look at the wizard this time you’ll see all of the fields are filled in for us:

This time, instead of clicking Finish, hit next and look at the following window:

Here you can select all of the public methods of that class to test. Notice how our getters for firstName and lastName are not part of this list. Unit testing can only be performed on public methods. Also, you will see every inherited method of the class so we have Sprite/DisplayObject methods here since our doc class extends Sprite. Select isLoggedIn and hit finish.

If you scroll down to the bottom of the new test class that was just generated you’ll see it has automatically added in a testMethod for isLoggedIn.

When testing your own code Flash Builder can help automate the process of scaffolding your tests. This is a great help when dealing with large classes that have lots of methods.

Step 19: Best Practices

By now you should have a solid understanding of how Unit Testing in Flash Builder works. You may even be ready to start setting up your own test. There are a lot of things I wasn’t able to cover in this short tutorial so here are some things to keep in mind when creating your tests.

• Keep your code small and easily testable. Make short methods, break code down into “units” to help facilitate testing. It’s ok to have lots of methods in your classes. Not only does it help you when unit testing but also when extending classes and dealing with inheritance overriding.
• Test a behavior and not a method. This tutorial showed you how I would interact with the instance of the CamoPropertySheet. I was testing behavior responses for the underlying parsing/retrieval system. Make sure you are not testing that functions simply return values but that the underlying logic is correct. Did something get parsed, did the dependent methods do what they were expected to do?
• Keep your test names clean. You should be able to easily understand what is going on by simply looking at the name of the test method. Remember this code is not compiled into your final application so if you have incredibly long method names, that’s ok as long as they’re descriptive.
• Don’t rely on the console window for your test. This means you shouldn’t expect a developer to watch trace outputs to see if the test is working correctly. Instead make the test fail or succeed and not output its results.
• Do a search for Unit Testing in other languages to see how it has been implemented elsewhere. Also pick up a book on Test Driven Development (TDD).

Conclusion

As you can see, setting up Unit Testing is very simple, but creating applications revolving around Test Driven Development is an art form in its own right. Hopefully after this intro you’ll be comfortable setting up a simple test to validate that your code works as expected. As you rely more and more on Unit testing the number of bugs in your code will dramatically go down. As long as you remember to code towards passing a test, keeping your methods small and validating your unit tests often, you’ll be well on your way to building more stable code.

Thanks for reading.

Let’s get started.

Preview

To refresh our memory, this is the final product we’re going to create. It is the Bobble Person Site Launcher I use on http://jessefreeman.com.

Step 15: Decals Sheets

I’ve talked about creating a Decal Sheet System before, but now we’re going to take advantage of Flash Camo’s own built in system. Let’s talk about how Decals work in Camo.

The main feature of the framework is the DecalSheet system (located in the "camo.core.decal" package); made up of the DecalSheetManager, DecalSheet and Decal classes. The DecalSheet concept was inspired by the decals you would get with model airplanes. Each model kit would contain sheets of graphics and on each sheet you could peel off a decal and place it on the model. Camo’s version of the DecalSheet allow you to load in external images, cut out decals and skin your application with them.

For this step you will need Photoshop CS 3/4 to open the psd. You can download it from here.

Once you have downloaded the PSD, open it up and take a look.

As you can see we have our simple design. I’ve gone ahead and done all of the prep work for you so let’s just go to "save as" and create a new PNG. Note: if you go to "Save For Web" you will see the slices we’ll be using later in the tutorial.

We’ll save this png as "default.png" to our "html-template/images/skins" folder in our BobbleHeadApp project. You can also right-click on the following image and use it instead of the PSD. Make sure you save it as "default.png"

Now that we have our skin, we need to create a Global DecalSheet Manager.

Step 16: Create a Global DecalSheet Manager

Our site is going to make extensive use of the DecalSheet system, but first we’re going to need to come up with a way to make it accessible throughout our application. Just like we did with the GlobalStyleSheetManager, we’re going to create a Singleton for our DecalSheetManager class.

The DecalSheetManager (located in the "camo.core.managers" package) is the manager for the decal system. It handles the xml that defines a list of DecalSheet images and coordinates for cutting out each Decal. It also stores a collection of DecalSheets to make creating complex Decal lookup tables easier to manage. You can configure DecalSheets and Decals on the DecalSheetManager at run time or with XML. Once this data is set, the DecalSheetManager goes out and gets all the images it needs for the DecalSheet images.

Now we’re ready to set up our GlobalDecalSheetManager class. You’ll need to create a new class called "GlobalDecalSheetManager" and put it into "com.jessefreeman.managers" package.

Here’s the code for the class:

package com.jessefreeman.managers
{
	import camo.core.managers.DecalSheetManager;

	public class GlobalDecalSheetManager
	{

		public static const INIT:String = "init";

		private static var __instance:DecalSheetManager;

		/**
		 *
		 * @param enforcer
		 *
		 */
		public function GlobalDecalSheetManager(enforcer:SingletonEnforcer)
		{
			if (enforcer == null)
			{
				throw new Error("Error: Instantiation failed: Use GlobalDecalSheetManager.instance instead.");
			}
		}

		/**
		 *
		 * @return
		 *
		 */
		public static function get instance():DecalSheetManager
		{
			if (GlobalDecalSheetManager.__instance == null)
			{
				GlobalDecalSheetManager.__instance = new DecalSheetManager();
			}
			return GlobalDecalSheetManager.__instance;
		}

	}
}

internal class SingletonEnforcer{}

This should look familiar to you by now, so there isn’t much to go over. Let’s talk about how to load in DecalSheet XML and parse it.

Step 17: Defining Decals

We’re going to modify the DecalSheet xml in our htm-template folder. In order to create our decals we’ll need to know the x,y,width and height of each decal we want to use. Here is a quick mockup of our PSD with the coordinates.

Now that we have all the values we need, replace the contents of our decahsheet.xml in the html-template/xml folder with the following:

<?xml version="1.0" encoding="UTF-8"?>
<decalsheet>
	<sheets baseURL="images/skins">
		<sheet name="default" src="/default.png" preload="true" w="570" h="359"/>
	</sheets>
	<decals>
		<decal name="head" sheet="default" x="433" y="181" w="136" h="138"/>
		<decal name="body" sheet="default" x="255" y="139" w="182" h="139"/>
		<decal name="leftArm" sheet="default" x="208" y="278" w="194" h="76"/>
		<decal name="leftFoot" sheet="default" x="4" y="172" w="125" h="78"/>
		<decal name="leftLeg" sheet="default" x="128" y="172" w="122" h="78"/>
		<decal name="rightArm" sheet="default" x="251" y="17" w="182" h="122"/>
		<decal name="rightLeg" sheet="default" x="3" y="6" w="216" h="168"/>
	</decals>
</decalsheet>

This xml should be easy to follow, we’re defining our DecalSheet source then defining each decal and the sheet they belong to. Notice how the sheet has an attribute to preload, we’re going to use DecalSheetManager’s loader to prelaod all of our site’s images. This will play a more important role when we preload several DecalSheets later on.

Step 18: Loading DecalSheets

The DecalSheetManager uses xml to create DecalSheets and Decals. We’ll need to load in some XML first then we can pass it off to the GlobalDecalSheetManager’s DecalSheetManager (try saying that 3 times fast).

Let’s start by adding the following methods after our "onPropertySheetLoad" method in the Doc Class:

private function loadDecalSheetData():void
{
	var urlLoader:URLLoader = new URLLoader();
	urlLoader.addEventListener(Event.COMPLETE, onDecalSheetDataLoad, false, 0, true);
	urlLoader.load(new URLRequest("xml/decalsheet.xml"));
}

private function onDecalSheetDataLoad(event:Event):void
{
	// Remove Event Listener
	URLLoader(event.target).removeEventListener(Event.COMPLETE, onDecalSheetDataLoad);

	//
	var xml:XML = XML(event.target.data);
	var decalSheetManager:DecalSheetManager = GlobalDecalSheetManager.instance;
	decalSheetManager.addEventListener(LoaderManagerEvent.PRELOAD_NEXT, onPreloadNext, false, 0, true);
	decalSheetManager.addEventListener(LoaderManagerEvent.PRELOAD_DONE, onDecalSheetsLoad, false, 0, true);
	decalSheetManager.parseXML(xml);
}

protected function onPreloadNext(event:LoaderManagerEvent):void
{
	trace("Loading DecalSheet " + event.data.totalPreloaded + " of " + event.data.totalPreloading);
}

private function onDecalSheetsLoad(event:LoaderManagerEvent):void
{
	var target:DecalSheetManager = event.target as DecalSheetManager;
	target.removeEventListener(LoaderManagerEvent.PRELOAD_DONE, onDecalSheetsLoad);
	init();
}

You will also need to import the following:

import camo.core.managers.DecalSheetManager;
import com.jessefreeman.managers.GlobalDecalSheetManager;
import camo.core.events.LoaderManagerEvent;

We just added a lot of code so let’s take a second to go over what’s going on. First we define the "loadDecalSheetData" method. All we’re doing here is creating a new urlLoader and having it load our decalsheet.xml. When the load is completed we call "onDecalSheetDataLoad". This method handles removing the event listener from our URL loader and passes off the XML to the instance of the DecalSheetManager obtained from our GlobalDecalSheetManager Singleton. We also added two listeners; one for the notification of the "next" preload initiation and the second is when the preload is completed. When we’re done loading we call "onDecalSheetLoad", remove our listeners and call init.

Now we have to remove the "init" call from our "onPropertySheetLoad" method. Replace that function with the following:

private function onPropertySheetLoad(event:Event):void
{
	var target:URLLoader = event.target as URLLoader;
	target.removeEventListener(Event.COMPLETE, onPropertySheetLoad);

	propSheet.parseCSS("global.properties", target.data);

	loadDecalSheetData();
}

If you compile, everything should look the same but we’re now loading in our DecalSheet xml along with the DecalSheet image.

Step 19: Decal Display

We’ll need a component to display our Decal in. Normally you can take advantage of the BoxModel’s background image property to automatically load in any image you would need, but since our body parts need to be centered we’ll have to position them by hand.

Let’s start by renaming our "SimpleDisplay" in "com.jessefreeman.components" to "DecalDisplay".

Once you’ve done that, open the class up and replace its code with the following:

package com.jessefreeman.components
{
	import camo.core.decal.Decal;
	import com.jessefreeman.managers.GlobalDecalSheetManager;
	import com.jessefreeman.components.AbstractComponent;

	public class DecalDisplay extends AbstractComponent
	{
		protected var decalInstance:Decal;

		public var pixelSnapping:String = "auto";

		public var smoothing:Boolean = true;

		public function DecalDisplay(id:String)
		{
			super(this, id);
		}

		public function set src(decalName:String):void
		{
			decalInstance = GlobalDecalSheetManager.instance.getDecal(decalName, pixelSnapping, smoothing);
			if (!contains(decalInstance))
				addChild(decalInstance);
		}
	}
}

As you can see, we have a few properties that we can use to style this class from a PropertySheet. Let’s take a look at the public variables, pixelSnapping and smoothing should look familiar if you have worked with the Bitmap Class before. These just help with making our Decals look smooth when they bobble around.

The main functionality of the class is the setter for src. As you can see it accepts a decal name, then requests the Decal from the GlobalDecalSHeetManager. If the decal exists we add it to the display. Let’s talk about Decals a little.

A Decal is a Bitmap that contains a reference to the DecalSheet it was cut out from. Now that you have seen how we get xml data into the DecalSheetManager, let’s talk about how to retrieve Decal instances. When you call "getDecal" on the DecalSheetManager or DecalSheet, you need to supply the name of a Decal. You can check if a Decal exists by looking through a DecalSheet’s "decalName" Array. Once a Decal is requested, the Decal’s name gets passed to the parent DecalSheet through the "sample" method and the Decal’s BitmapData is returned inside of a new Decal Instance.

Since all Decals contain a reference to the DecalSheet it was cut out from, this connection allows the Decal to receive updates from its parent DecalSheet. You can change a DecalSheet’s BitmapData at any time just as you would any other Bitmap instance. Decals listen for "Event.CHANGE" events from their parent Sheet and once an event is received, it resamples the DecalSheet and updates its own BitmapData. Later we’ll reskin an entire application on the fly by changing the BitmapData of our DecalSheet.

Step 20: Using The Decal Display

Now that we have our DecalDisplay we need to add it to our BobbleContainer. In BobbleContainer, add the following method after "get active":

public function set src(value:String):void
{
	decalDisplay = new DecalDisplay(id + "DecalDisplay");
	decalDisplay.src = value;
	addChildAt(decalDisplay, 0);
}

Also we’ll need to create the following property:

protected var decalDisplay:DecalDisplay;

So all we’re doing is adding a setter for src that we can pass into a new instance of the DecalDisplay. Notice that we’re using "addChildAt"? Since we add our label, we want to make sure that the DecalDisplay is at the lowest end of the display list. Now we have our DecalDisplay in place, we just need to set up some property styles.

Step 21: Styling Decal Displays

We have everything we need in place to start displaying our Decals. All we have to do is add some new properties to our PropertySheet. Take a look at this sample style for the DecalDisplay then we’ll update the entire property sheet:

#body
{
	x: 355;
	y: 229;
	width: 181;
	height: 144;
	src: body;
}

#bodyDecalDisplay
{
	x: -84;
	y: -65;
}

As you may have noticed earlier when we create our DecalDisplays in the BobbleContainer, we pass in the BobbleContainer’s id and the string "DecalDisplay" so each instance has a unique id. In the above example we’ve added src to refer to the name of the Decal we want to use and then have a corresponding style with the x,y offset for the decal. Replace the contents of your "main.properties.css" with the following:

/* CSS file */

.BobblePerson
{
	part-ids: head body leftArm rightArm leftLeg leftFoot rightLeg;
}

.Label
{
	font: Arial Black;
	size: 20px;
	embedFonts: true;
	color: #ffffff;
	anti-alias-type: advanced;
}

#siteLabel
{
	text: ANATOMY OF JESSE FREEMAN;
	x: 155;
	y: 60;
	size: 18px;
	rotation: 24px;
	letter-spacing: -2;
	text-height: 30px;
	alpha: .5;
}

.BobbleContainer
{
	active: true;
	rollOverForce: 1;
	roll-over-force: 1;
	nodding-force: 0;
	nodding-angle: 0;
	nodding-range: 10;
	nodding-hit: .7;
	nodding-damp: .985;
}

/* BobbleContainers */

#body
{
	x: 355;
	y: 229;
	src: body;
}

#head
{
	x: 449;
	y: 250;
	src: head;
}

#leftArm
{
	x: 381;
	y: 313;
	src: leftArm;
}

#leftFoot
{
	x: 145;
	y: 213;
	src: leftFoot;
}

#leftLeg
{
	x: 263;
	y: 235;
	src: leftLeg;
}

#rightArm
{
	x: 419;
	y: 176;
	src: rightArm;
}

#rightLeg
{
	x: 275;
	y: 176;
	src: rightLeg;
}

/* BobbleContainer Labels */

#bodyLabel
{
	alpha: 1;
	rotation: 20;
	x: -35;
	y: -30;
	text-align: center;
	auto-size: center;

}

#leftArmLabel
{
	text: bFreeDesign;
	x:  -90;
	y: 25;
	rotation: -9;
	size: 18;
	letter-spacing: -3;
}

#leftFootLabel
{
	text: eMail;
	x: -78;
	y: -13;
	rotation: 6;
}

#leftLegLabel
{
	text: FlashBum;
	x: -95;
	y: -40;
	rotation: 9;
}

#rightArmLabel
{
	text: FlashArtOfWar;
	x: -80;
	y: -75;
	rotation: 32;
	font-size: 16;
	letter-spacing: -1;
}

#rightLegLabel
{
	text: iLikeToDream;
	x: -157;
	y: -83;
	rotation: 27;
}

/* BobbleContainer Displays */

#bodyDecalDisplay
{
	x: -84;
	y: -65;
}

#headDecalDisplay
{
	x: -20;
	y: -18;
}

#leftArmDecalDisplay
{
	x: -162;
	y: -11;
}

#leftFootDecalDisplay
{
	x: -104;
	y: -20;
}

#leftLegDecalDisplay
{
	x: -103;
	y: -43;
}

#rightArmDecalDisplay
{
	x: -136;
	y: -104;
}

#rightLegDecalDisplay
{
	x: -192;
	y: -142;
}

Now you have a clean PropertySheet with our decals correctly connected. If you do a compile you should see all of the body parts in their correct place along with our labels.

Step 22: Focus Event

As we begin to add interactivity to our app we’ll need a custom event to track mouse interaction on the body parts. Let’s create a new class called "FocusEvent" in "com.jessefreeman.events"

Here’s the code:

package com.jessefreeman.events
{
	import flash.events.Event;

	public class FocusEvent extends Event
	{
		public static const IN_FOCUS:String = "inFocus";
		public static const LOST_FOCUS:String = "lostFocus";

		public var text : *;
		public var skinName : String;

		public function FocusEvent(type:String, text:String = "" , skinName:String = "default", bubbles:Boolean=false, cancelable:Boolean=false)
		{
			this.text = text;
			this.skinName = skinName;
			super(type, bubbles, cancelable);
		}

	}
}

So in this FocusEvent class we have added two new properties to the event’s default constructor, "text" and "skinName". Text will be the label of the body part we roll over and skinName will be used later when we start to dynamically reskin our app. We also have two constants representing our states, "inFocus" and "lostFocus".

Let’s dispatch this event by going into the BobbleContainer class and add the following line to the end of the "onRollOver" method:

dispatchEvent( new FocusEvent( FocusEvent.IN_FOCUS, rollOverText, "default", true, true ) );

Then add the following to the "onRollOut" method:

dispatchEvent( new FocusEvent( FocusEvent.LOST_FOCUS, rollOverText, "default", true, true ) );

Also make sure you import the FocusEvent:

import com.jessefreeman.events.FocusEvent;

Now we have two events being dispatched letting us know the state of BobbleContainer. Before we’re done we need to add a new public variable to the BobbleContainer:

public var rollOverText : String = "";

We pass this variable into the in focus event that gets dispatched. You will need to modify your css with the new rollOverText. Replace these styles found in the /* BobbleContainers */ comment block with the following:

/* BobbleContainers */

#body
{
	x: 355;
	y: 229;
	rollOverLabel:;
	src: body;
}

#head
{
	x: 449;
	y: 250;
	src: head;
	rollOverText: RESUME;
}

#leftArm
{
	x: 381;
	y: 313;
	src: leftArm;
	rollOverText: HIRE;
}

#leftFoot
{
	x: 145;
	y: 213;
	src: leftFoot;
	rollOverText: CONTACT;
}

#leftLeg
{
	x: 263;
	y: 235;
	src: leftLeg;
	rollOverText: PORTFOLIO;
}

#rightArm
{
	x: 419;
	y: 176;
	src: rightArm;
	rollOverText: BLOG;
}

#rightLeg
{
	x: 275;
	y: 176;
	src: rightLeg;
	rollOverText: MY ART;
}

Step 23: Updating Body Label

Now we have all of the roll over text in place it’s time to display them. You may have noticed that the "body" part doesn’t have any rollOverText. We’re going to display the body part’s text here. Let’s go into the BobblePerson and make a few modifications.

At the end of the "createParts" method add the following two event listeners:

display.addEventListener( FocusEvent.IN_FOCUS, onContainerRollOver );
display.addEventListener( FocusEvent.LOST_FOCUS, onContainerRollOut );

Below the "createParts" method add the following:

public function onContainerRollOver(event:FocusEvent):void
{
	if (event.target != partDisplay)
	{
		partDisplay.label.text = event.text;
	}
}

public function onContainerRollOut(event:FocusEvent):void
{
	partDisplay.label.text = "";
}

We’ll need to add a new getter so put the following under get "partIds".

public function get partDisplay():BobbleContainer
{
	var index:int = _partIds.indexOf(partDisplayId);

	return (index != -1) ? partInstances[index] : null;
}

We’re almost there, now let’s make sure you have the following property:

public var partDisplayId : String;

Then import the follow class:

import com.jessefreeman.events.FocusEvent;

Before we test this, we just need to update our ".BobblePerson" css style to include the following property:

part-display-id: body;

Now do a compile and roll over the body parts.

Notice how we can change the body part that will display the text at any time by modifying the part-display-id in our css. Let’s add in the final set of logic to our site.

Step 24: Adding Click Logic

Now we’re going to add some listeners to track when a BodyPart is clicked so we can open a corresponding url in a new window. Go into the BobbleContainer and replace "addEventListeners" and "removeEventListeenrs" with the following code:

protected function addEventListeners(target : IEventDispatcher) : void
{
	target.addEventListener( MouseEvent.ROLL_OVER, onRollOver );
	target.addEventListener( MouseEvent.ROLL_OUT, onRollOut );
	target.addEventListener( MouseEvent.CLICK, onClick );
}

protected function removeEventListeners(target : IEventDispatcher) : void
{
	target.removeEventListener( MouseEvent.ROLL_OVER, onRollOver );
	target.removeEventListener( MouseEvent.ROLL_OUT, onRollOut );
	target.removeEventListener( MouseEvent.CLICK, onClick );
}

We’re simply adding a listener for Mouse Click. Add the following method below "onRollOut":

protected function onClick(event : MouseEvent) : void
{
	if(url)
    	navigateToURL( url, "_self" );
}

Let’s add a new public variable for our urls:

public var url : URLRequest;

Import the following classes:

import flash.net.URLRequest;
import flash.net.navigateToURL;

All we need to do is modify our PropertySheet to include urls for each part by replacing the "/* BobbleContainers */" comment block with the following:

/* BobbleContainers */

#body
{
	x: 355;
	y: 229;
	rollOverLabel:;
	src: body;
}

#head
{
	x: 449;
	y: 250;
	src: head;
	rollOverText: RESUME;
	url: url("http://www.linkedin.com/in/jessefreeman");
}

#leftArm
{
	x: 381;
	y: 313;
	src: leftArm;
	rollOverText: HIRE;
	url: url("http://www.bfreedesign.com");
}

#leftFoot
{
	x: 145;
	y: 213;
	src: leftFoot;
	rollOverText: CONTACT;
	url: url("mailto:jessefreeman@gamil.com");
}

#leftLeg
{
	x: 263;
	y: 235;
	src: leftLeg;
	rollOverText: PORTFOLIO;
	url: url("http://www.flashbum.com");
}

#rightArm
{
	x: 419;
	y: 176;
	src: rightArm;
	rollOverText: BLOG;
	url: url("http://www.flashartofwar.com");
}

#rightLeg
{
	x: 275;
	y: 176;
	src: rightLeg;
	rollOverText: MY ART;
	url: url("http://www.iliketodream.com");
}

Notice how we have added url properties. This is how we tell Camo’s CSS parser to convert urls into URL Requests. Now when a user clicks on a body part we simply pass off the url request set by the PropertyStyleSheet to the "navigateToURL" class.

If you would like the Bobble Parts to act as buttons, simply add the following to the ".BobbleContainer" style:

button-mode: true;
use-hand-cursor: true;
mouse-children: false;

Now all of the BobbleContainer classes will automatically act as buttons. You may want to change one more style, the "#body", so it doesn’t have mouse interactivity. Simply add the following to the property selector:

button-mode: false;
use-hand-cursor: false;
mouse-children: false;

Now it overrides the Class’s default settings and will not have mouse interactivity.

Let’s look into how to do some advanced skinning.

Step 25: Advanced Skinning

When you opened up the PSD you may have noticed a few extra "skins" in the Body Skin folder.

I have prepared the following skins for us to use. You can download the zip here and put the skins in your html-template/images/skins folder.

Now you have each skin let’s look at how we can load them all in.

Step 26: Loading Multiple DecalSheets

Loading in multiple DecalSheet images is as easy as modifying out xml. Let’s replace our decalsheet.xml with the following:

<?xml version="1.0" encoding="UTF-8"?>
<decalsheet>
	<sheets baseURL="images/skins">
		<sheet name="default" src="/default.png" preload="true" w="570" h="359"/>
		<sheet name="iliketodream" src="/iliketodream_skin.png" preload="true" w="570" h="359"/>
		<sheet name="flashbum" src="/flashbum_skin.png" preload="true" w="570" h="359"/>
		<sheet name="bfreedesign" src="/bfreedesign.png" preload="true" w="570" h="359"/>
		<sheet name="artofwar" src="/artofwar_skin.png" preload="true" w="570" h="359"/>
	</sheets>
	<decals>
		<decal name="head" sheet="default" x="433" y="181" w="136" h="138"/>
		<decal name="body" sheet="default" x="255" y="139" w="182" h="139"/>
		<decal name="leftArm" sheet="default" x="208" y="278" w="194" h="76"/>
		<decal name="leftFoot" sheet="default" x="4" y="172" w="125" h="78"/>
		<decal name="leftLeg" sheet="default" x="128" y="172" w="122" h="78"/>
		<decal name="rightArm" sheet="default" x="251" y="17" w="182" h="122"/>
		<decal name="rightLeg" sheet="default" x="3" y="6" w="216" h="168"/>
	</decals>
</decalsheet>

All we’ve done here is added four new DecalSheets to preload. Compile the site and check your connections to make sure they are being loaded.

Step 27: Adding Reskin Logic

Now that we’re loading in our skins, let’s add some logic to handle dynamically changing the skin bitmapdata. Let’s go into our BobblePerson class and add the following two functions:

protected function saveDefaultBitmapData():void
{
	defaultSkin = GlobalDecalSheetManager.instance.getSheet("default");
	defaultSkinBMD = defaultSkin.bitmapData.clone();
}

protected function switchSkin(skinName:String = "default"):void
{
	var newSkinBitmapData:BitmapData;

	if (skinName == "default")
	{
		newSkinBitmapData = defaultSkinBMD.clone();
	}
	else
	{
		newSkinBitmapData = GlobalDecalSheetManager.instance.getSheet(skinName).bitmapData.clone();
	}

	if (newSkinBitmapData)
		defaultSkin.bitmapData = newSkinBitmapData;
}

Let’s talk about what’s going on here. We’re going to take advantage of a neat feature of Camo’s DecalSheet system by replacing the bitmap data of our default skin with BitmapData from other skins. In order to do this we need to have a reference to the default DecalSheet as well as its BitmapData. We do this in "saveDefaultBitmapData". Next we need to add logic to switch skins. This happens in the "switchSkin" method. As you can see we set up a variable to hold our new BitmapData.

Next we test to see if the skin is "default" or something else. If it’s the default skin we get the BitmapData from "defaultSkinBMD". If it’s another skin we’ll ask the GlobalDecalSheetManager’s instance for that sheet. Lastly, we make sure we have a valid BitmapData in our newSkinBitmapData variable then set the BitmapData of our default skin to the newSkinBitmapData.

We need to add the following variables:

protected var defaultSkin:DecalSheet;
protected var defaultSkinBMD:BitmapData;

and make sure you’ve imported the BitmapData class:

import flash.display.BitmapData;
import camo.core.decal.DecalSheet;
import com.jessefreeman.managers.GlobalDecalSheetManager;

Finally we’ll call "saveDefaultBitmapData" in the setter for "partIds". Make sure your setter looks like this:

public function set partIds(value:Array):void
{
	_partIds = value;
	saveDefaultBitmapData();
	createParts();
}

Now let’s go into our BobbleContainer class and add the following property:

public var skin:String = "default";

Next you will need to modify the dispatchEvent in the "onRollOver" method to look like this:

dispatchEvent(new FocusEvent(FocusEvent.IN_FOCUS, rollOverText, skin, true, true));

Notice how we’re now passing up the skin value through the event? This will tell the body the correct skin to use when there’s a roll over.

Let’s go back to our BobblePerson and modify the "onContainerRollOver" and "onContainerRollOut" methods to look like this:

public function onContainerRollOver(event:FocusEvent):void
{
	if (event.target != partDisplay)
	{
		partDisplay.label.text = event.text;
		switchSkin(event.skinName);
	}
}

public function onContainerRollOut(event:FocusEvent):void
{
	partDisplay.label.text = "";
	switchSkin("default");
}

Now we just have to modify our PropertySheet to add a skin name to our body parts. Replace the /* BobbleContainers */ comment block with the following:

/* BobbleContainers */

#body
{
	x: 355;
	y: 229;
	rollOverLabel:;
	src: body;
	button-mode: false;
	use-hand-cursor: false;
	mouse-children: false;
}

#head
{
	x: 449;
	y: 250;
	src: head;
	rollOverText: RESUME;
	url: url("http://www.linkedin.com/in/jessefreeman");
	skin: default;
}

#leftArm
{
	x: 381;
	y: 313;
	src: leftArm;
	rollOverText: HIRE;
	url: url("http://www.bfreedesign.com");
	skin: bfreedesign;
}

#leftFoot
{
	x: 145;
	y: 213;
	src: leftFoot;
	rollOverText: CONTACT;
	url: url("mailto:jessefreeman@gamil.com");
	skin: default;
}

#leftLeg
{
	x: 263;
	y: 235;
	src: leftLeg;
	rollOverText: PORTFOLIO;
	url: url("http://www.flashbum.com");
	skin: flashbum;
}

#rightArm
{
	x: 419;
	y: 176;
	src: rightArm;
	rollOverText: BLOG;
	url: url("http://www.flashartofwar.com");
	skin: artofwar;
}

#rightLeg
{
	x: 275;
	y: 176;
	src: rightLeg;
	rollOverText: MY ART;
	url: url("http://www.iliketodream.com");
	skin: iliketodream;
}

Now if you compile, you will see the skin of our bobble guy change depending on which body part you roll over.

Notice how quickly everything is reskined. This is why Decals are so powerful. You can change the look and feel of your entire application on the fly by changing the BitmapData of your DecalSheets at runtime.

Step 28: Deploy

Now our site is done and we’re ready to deploy it to a server. This is fairly easy to do in Flex builder and a step most people over look. Simply go to the Project menu and select Export Release Build.

Once this runs you will have a new folder called bin-release along with your bin-debug. Everything looks the same, but if you check out the side of our BobbleHeadApp.swf you will notice that the release build is about 24k and the debug version is 36k. That is barely 66% of the original size. I know when you are only talking about a few k it’s not a major deal, but every k counts. Also, in larger projects this can be a significant saving.

Now you are ready to copy this bin-release folder over to your FTP server and make it live.

Conclusion

As you can see, we have created a simple Flash Site using Flash Camouflage in less then 30 steps. By now you should have a better understanding about the power of incorporating Decals and CSS in your next project. You have also seen how easy it is to build components that work with Flash Camo’s three main features. Like all frameworks there is a learning curve and this is only a small sample of what is possible. Also, Flash Camo is still in Beta so there may be small bugs or code cleanup as the project matures.

If you encounter any issues, please leave a comment or submit an issue to the issue list. Remember Flash Camo is completely open source, you should check out the code and see what is going on under the hood. A lot of advanced techniques are being used so it’s a great place to learn how a framework is put together. If you use Camo in one of your projects let please me know..

Thanks for following along!

In this two part tutorial we’re going to build a simple website to show how easy it is to incorporate Flash Camo into your next project.

Preview

We’re going to recreate the "Bobble Person Site Launcher" from http://jessefreeman.com.

Step 1: Checkout Flash Camo 2.2

In this tutorial we’re going to use Flex Builder. If you haven’t worked in Flex Builder or need help getting a Flex Library project setup, take a look at my "Flash Development Sandbox Tutorial" (part 1 and part 2). This tutorial will also walk you through downloading and setting up Flash Camo from SVN. For this project we’re going to be using version 2.2 of the framework, you can check it out here:

http://flash-camouflage.googlecode.com/svn/tags/FlashCamo_2.2.0_beta

Step 2: Setting Up Our Project

Create a new project called BobbleHeadApp and make sure you link it to the Flash Camo SWC we checked out in step 1.

You will also need the following resource folders to get started. Download them from here and place them in your html-template folder. I’ve included an updated html-template file linked to swfObject along with the layout of our external resource folders.

Step 3: Creating a Flash Camo Doc Class

Now that we have our project and resources set up, let’s start with our Doc Class (BobbleHeadApp.as). You should replace your doc class with the following code:

package
{
	import flash.display.Loader;
	import flash.display.Sprite;
	import flash.display.StageAlign;
	import flash.display.StageScaleMode;
	import flash.events.Event;
	import flash.net.URLRequest;

	[SWF( width="600", height="400", backgroundColor="#3A3E4A", framerate="31" )]

	public class BobbleHeadApp extends Sprite
	{

		private var fontSWF : Loader;

		public function BobbleHeadApp()
		{
			configureStage( );
			loadFonts( );
		}

		private function configureStage() : void
		{
			stage.align = StageAlign.TOP_LEFT;
			stage.scaleMode = StageScaleMode.NO_SCALE;
		}

		private function loadFonts() : void
		{
			fontSWF = new Loader( );
			fontSWF.contentLoaderInfo.addEventListener( Event.COMPLETE, onFontsLoaded );
			fontSWF.load( new URLRequest( "swfs/fonts/FontLibrary.swf" ) );
		}

		private function onFontsLoaded(event : Event) : void
		{
			fontSWF.contentLoaderInfo.removeEventListener( Event.COMPLETE, onFontsLoaded );
			init( );
		}

		protected function init() : void
		{
			trace( "Hello World" );
		}
	}
}

Sometimes when testing local files you may see the following error:

Error #2044: Unhandled SecurityErrorEvent:. text=Error #2140: Security sandbox violation: … Local-with-filesystem and local-with-networking SWF files cannot load each other.

If this happens to you, add the following "-use-network=false" in your projects compiler Arguments. This will circumvent any Security Sandbox issues you may get while locally testing.

Now you should be ready to compile the swf and take a look at the output window. You will see "Hello World":

If you check your browser’s connections the font swf should have been loaded:

Step 4: Creating a Global PropertySheet Manager

We’re going to need a central place to store and access our css properties. Before we do this let’s talk about the CamoPropertySheet. You may have used CSS with Flash in the past but this is something completely new and unique to Flash Camo. Camo’s custom CSS parser, the "CamoPropertySheet" (found inside of the "camo.core.property" package), goes well beyond the native StyleSheet class by supporting style inheritance, pseudo selectors and merging styles on the fly. The goal of the CamoPropertySheet is to make styles something you can apply to any of your classes instead of just TextFields. CSS is a great way to define your class’s properties in an external file and Camo helps convert these css styles into property/value pairs you can apply to any Object. Camo also has a CamoPropertySheetManager (found inside of the "camo.core.managers" package) class for handling multiple CamoPropertySheets in one application.

Since we will need all of our classes to have access to the CamoPropertySheetManager we’re going to create a Singleton. This Singleton will enforce one instance of our CamoPropertySheetManager. I’m not a big fan of Singletons, but in situations like this they’re a necessary evil. We’ll need a single class instance in charge of managing and returning requested PropertySelectors. I will explain later what a ProperySelector is and how it will function in our application.

Let’s create a new class called "GlobalPropertySheetManager" and put it in the "com.jessefreeman.managers" package.

Here is the class’s code:

package com.jessefreeman.managers
{
	import camo.core.managers.CamoPropertySheetManager;

	public class GlobalPropertySheetManager
	{

		public static const INIT : String = "init";
		private static var __instance : CamoPropertySheetManager;

		public function GlobalPropertySheetManager(enforcer : SingletonEnforcer)
		{
			if (enforcer == null)
			{
				throw new Error( "Error: Instantiation failed: Use GlobalDecalSheetManager.instance instead." );
			}
		}

		public static function get instance() : CamoPropertySheetManager
		{
			if(GlobalPropertySheetManager.__instance == null)
			{
				GlobalPropertySheetManager.__instance = new CamoPropertySheetManager( );
			}
			return GlobalPropertySheetManager.__instance;
		}
	}
}

internal class SingletonEnforcer
{
}

There are many ways to create a Singleton and the discussion is a little out of scope of this tutorial. Let’s quickly talk about what is happening here. Since ActionScript 3 classes are unable to have private constructors there is no way to hide the constructor of a class. Instead of allowing the class to be created through the usual "new" construction we will enforce calling the GlobalPropertySheetManager.instance to get a reference to the class. The instance getter checks to see if the class has already been created, if the class doesn’t exist it creates a new CamoPropertySheetManager. If the instance exists it will return a reference to that instance. This ensures that we only have 1 instance of the CamoPropertySheetManager in our entire application. Now we’re ready to start loading in our CSS.

Step 5: Loading PropertySheet CSS

The CamoPropertySheetManager has no way to load CSS, instead we’ll supply the load mechanism and tell it to parse the loaded data. We’ll start by creating our load method by making use of the URLLoader. Add the following methods to our Doc Class after the "onFontsLoaded" function:

private function loadPropertySheet() : void
{
	trace( "Loading CSS" );

	propSheet = GlobalPropertySheetManager.instance;

	var loader : URLLoader = new URLLoader( );
	loader.addEventListener( Event.COMPLETE, onPropertySheetLoad );
	loader.load( new URLRequest( "css/main.properties.css" ) );
}

private function onPropertySheetLoad(event : Event) : void
{

	var target : URLLoader = event.target as URLLoader;
	target.removeEventListener( Event.COMPLETE, onPropertySheetLoad );

	propSheet.parseCSS( "global.properties", target.data );

	trace( "PropertySheetSelectors", propSheet.getPropertySheet( "global.properties" ).selectorNames );

	init( );
}

You will also need to add the following properties to the Doc Class:

private var propSheet : CamoPropertySheetManager;

Then import the following classes:

import flash.net.URLLoader;
import camo.core.managers.CamoPropertySheetManager;
import com.jessefreeman.managers.GlobalPropertySheetManager;

Finally, we’ll just alter our onFontsLoaded method to call loadPropertySheet by replacing:

init( );

with:

loadPropertySheet();

Since the URLLoader can load in any text file, we simply load in our own custom CSS then pass it off to the CamoPropertySheetManager instance that we got from the GlobalPropertySheetManager. Notice how we called "parseCSS" and passed in a name for our PropertySheet along with the string data we just loaded. That’s all you need to do in order to have Camo parse your css. Later we’ll talk about how we get our styles out, but here is a little more info on the PropertySheet system in camo.

Once the CSS is parsed, you can retrieve an Array of selector names by calling the "selectedNames" getter. A selector represents the name of the particular CSS style and its collection of values. The "getSelector" method will return the selector and its properties as a "PropertySelector". New selectors can be added to the CamoPropertySheet by calling "newSelector" and passing a selector name and a PropertySelector instance. Finally, you can duplicate a CamoPropertySheet by calling the "clone". We’ll cover this more as we start to build out our components.

Step 6: Testing The CSS Parser

Now is a good time to test that our CSS parser works. Let’s open up the css file in "html-tempalte/css/main.properties.css" and add the following style:

.TestStyle
{
	x: 100px;
	y: 100px;
	width: 100px;
	height: 100px;
	background-color: #ff0000;
	border: 1px solid #000000;
}

If you’re working in Flex Builder and modify files in your html-template folder you will need clean the project. You can do this by going to Project > Clean… and selecting the projects you want to clean. When you clean a project, it makes a fresh copy of the html-template folder over to the bin folder. Let’s say you modify something in html-template then add a new line of code. Flex Builder automatically preforms a clean. This situation only happens when you edit a file in html-template and do not do a clean. Trust me, this step will save you countless hours of frustration trying to figure out why your changes are not showing up in the browser. I usually map the clean project action to option + command + c since I use it so much.

Now if you recompile the swf and look at the output you should see the name ".TestStyle" selector name next to the "PropertySheetSelectors" trace.

Let’s try to retrieve our style and trace it out. Replace:

trace( "PropertySheetSelectors", propSheet.getPropertySheet( "global.properties" ).selectorNames );

inside of onCSSLoad from our Doc Class with this:

trace( "Test Selector", propSheet.getSelector(".TestStyle"));

Now when you compile you should see the following:

Test Selector .TestStyle{x:100;height:100background-color:#ff0000;border:1 solid #000000;selectorName:.TestStyle;y:100;width:100;}

This is the string value of our PropertySelector. Looks like an object right? Well that’s because it is! Camo’s css parser converts css selectors into native objects. It is important to note that each value is still a string. Later we will talk about how to convert these strings into natively typed values so you can apply them to any object or class in your application. Let’s start building the foundation for our project.

Step 7: Creating an AbstractComponent

Now we’re ready to start building our components. We want all of our components to inherit the ability to automatically find their own CSS style. If you’re not familiar with what an Abstract Class is, you may be surprised to hear that you might already be using them.

A simple explanation of an Abstract class is any class you create that has some core functions but has to be extended to added specific functionality.

Abstract Classes, much like our Singleton, should not be directly instantiated. Think of Abstract class as Interfaces but with code in them. We’re simply setting up a few functions all components will need and each component will add the additional logic they require. We’re going to call our Abstract Class "AbstractComponent" and put it in the "com.jessefreeman.components" package.

Let’s take a look at the code:

package com.jessefreeman.components
{
	import camo.core.display.CamoDisplay;
	import camo.core.property.PropertySelector;

	import com.jessefreeman.managers.GlobalPropertySheetManager;

	import flash.errors.IllegalOperationError;

	public class AbstractComponent extends CamoDisplay
	{

		protected static const ID_DELIMITER : String = " ";
		protected var defaultSelectorNames : Array;

		public function AbstractComponent(self : AbstractComponent, id : String)
		{
			if(self != this)
			{
				//only a subclass can pass a valid reference to self
				throw new IllegalOperationError( "Abstract class did not receive reference to self. " + className + " cannot be instantiated directly." );
			}
			else
			{
				parseStyleNames( id );
				init( );
			}
		}

		protected function parseStyleNames(id : String) : void
		{
			defaultSelectorNames = id.split( ID_DELIMITER );
			this.id = defaultSelectorNames.pop( );
			// clean up selectors
			defaultSelectorNames.unshift( "." + className );
			defaultSelectorNames.push( "#" + this.id );
		}

		protected function init() : void
		{
			var prop : PropertySelector = GlobalPropertySheetManager.instance.getSelector.apply( null, defaultSelectorNames );

			applyProperties( prop );
		}
	}
}

Even though this is a small class there’s a lot going on. Let’s start with the fact that it’s extending the CamoDisplay. Normally we would extend Sprite or MovieClip for our display classes but because we want to take advantage of Flash Camo’s BoxModel we need to build off of the CamoDisplay. We’ll talk about the BoxModel and CamoDisplay a little later.

If you check out the constructor you will notice we’re requesting two items, self and id. As we go through the constructor we do a verification that the class can only be instantiated by passing a reference of itself back into the constructor. You will see how this works with our "concrete" components (a concrete class is any fully functional class that extends an Abstract class). The other property id is important because we will be using that to look up the component’s id from css. Once the Abstract validation has passed, we call the parseStyleName method.

The parseStyleNames method is doing something special for us. If you have worked in html and css you may know that you can overload a ID or Class tag by supplying multiple CSS selector names separated by a space. In this method we allow you to add multiple IDs separated by a space and we parse them out into individual ids. The last ID becomes the main ID for the class and we add a "#" to it automatically. We also add the class’s name, from a getter of the CamoDisplay called "className", to our list of selector names. Let’s look at the init function next to see how we use this.

In the init function we’re doing two things; getting our selectors from the GlobalPropertySheetManager and then applying the css properties to the component itself through the applyProperties method. Take a look at how we’re calling the getSelector method on the GlobalPropertySheetManager. This part may make your head explode but don’t worry, I guarantee that at the end of the next few steps your code will compile and run fine whether or not you fully understand what’s going on.

First off, we want to get an instance of the CamoPropertySheetManager so we call the GlobalPropertySheetManager’s instance property. Remember this is a Singleton and we only have one instance of the CamoPropertySheetManager. Next we’re calling its function "getSelector" but instead of passing in the names of each selector we’re calling a function of the "getSelector" function. I know this is crazy but it is something built into the language. See "getSelector" is a rest function in Flash. This is a function that does not have a set number of parameters so you can pass in as many items as you want. Here is what the function actually looks like in the source code:

public function getSelector( ... selectorNames) : PropertySelector

See the "… selectorNames"? That tells the function you will get any amount of selector names, so be prepared. Since we can’t just pass an array into the "getSelector" method (because it would simply see it as 1 array variable) we have to call a special function called "apply" to pass in an array of arguments. The moral of the story is that you can pass in as many selector names as you want into the "getSelector" function and the CSS parser will merge them all into a single PropertySelector. If you want to understand more about rest statements in Flash check this out.

Now that’s out of the way, let’s look at an example to illustrate what this class will do.

Step 8: Testing The AbstractComponent

We’re going to perform a quick test to show how the AbstractComponent and BoxModel inside of the CamoDisplay work. Create a class called "SimpleDisplay" in the "com.jessefreeman.components" package.

Here is the class’s code:

package com.jessefreeman.components
{

	public class SimpleDisplay extends AbstractComponent
	{

		public function SimpleDisplay(id : String = "BoxModelDisplay")
		{
			super( this, id );
		}
	}
}

This is a very simple class, it just extends the AbstractComponent and passes a reference of itself up to super (in order to pass the AbstractComponent validation) and also passes up its id. Let’s test it out by going back to our Doc Class and adding the following after our Hello World trace inside of the "init" function:

var component:SimpleDisplay = new SimpleDisplay("BoxModelDisplay");
addChild(component);

and import:

import com.jessefreeman.components.SimpleDisplay

Now if you compile the swf, you won’t see anything, but the SimpleDisplay instance is there. Go into your CSS file and change the name of the ".TestStyle" to ".SimpleDisplay". Now recompile and you should see your SimpleDisplay.

Amazing, right? The SimpleDisplay automatically found its CSS Class name and applied its values. Any instance of the SimpleDisplay will automatically apply the ".SimpleDisplay" CSS Style to itself now. Let’s add the following style to our CSS sheet:

#BoxModelDisplay
{
	background-color: #00ff00;
	border-top: 10px;
}

Now when you compile you’ll see that the ID of the Component is overriding the base class style.

This is a very powerful way to customize the look and feel of your application. Now you can use CSS to style any class that extends the AbstractComponent. This is all made possible by Camo’s BoxModelDisplay. The "BoxModelDisplay" allows us to apply Margin, Padding, Border and a Background (Color/Image). Camo’s BoxModel works exactly like CSS’s. Here is a diagram:

As you may recall, our AbstractComponent extended the CamoDisplay which in turn extends the BoxModel. Well, the CamoDisplay not only inherits all of the BoxModel’s layout but it also adds a few extra features. You can read about all of the BoxModel and CamoDisplay’s properties in the docs folder of your Flash Camo checkout.

Step 9: LabelComponent

We’re going to create a simple component that will handle all of the text labels we need in our application. This is also a good component to help illustrate how the ProperySelector works. To get started, create a new class called "Label" in "com.jessefreeman.components" package.

Here is the code:

package com.jessefreeman.components
{
	import camo.core.enum.CSSProperties;

	import flash.text.StyleSheet;
	import flash.text.TextField;
	import flash.text.TextFormat;

	public class Label extends AbstractComponent
	{

		protected var _styleSheet : StyleSheet;
		protected var textField : TextField = new TextField( );
		protected var proxyTextFormat : TextFormat = new TextFormat( );
		protected var _textAlign : String = CSSProperties.LEFT;

		public function set autoSize(value : String) : void
		{
			textField.autoSize = validateAutoSize( value );
			invalidate( );
		}

		public function set antiAliasType(value : String) : void
		{
			textField.antiAliasType = validateAntiAliasType( value );
			invalidate( );
		}

		public function set embedFonts(value : Boolean) : void
		{
			textField.embedFonts = value;
			invalidate( );
		}

		public function set sharpness(value : Number) : void
		{
			textField.sharpness = value;
			invalidate( );
		}

		public function get text() : String
		{
			return textField.text;
		}

		public function set text(value : String) : void
		{
			textField.text = value;
			invalidate( );
		}

		public function set textAlign(value : String) : void
		{
			_textAlign = value;
			invalidate( );
		}

		public function set textFieldWidth(value : Number) : void
		{
			textField.width = value;
			invalidate( );
		}

		public function set textFieldHeight(value : Number) : void
		{
			textField.height = value;
			invalidate( );
		}

		public function set textFieldAlign(value : String) : void
		{
			proxyTextFormat.align = value;
			invalidate( );
		}

		public function set fontFace(value : String) : void
		{
			font = value;
			invalidate( );
		}

		public function set fontSize(value : Number) : void
		{
			size = value;
			invalidate( );
		}

		public function set font(value : String) : void
		{
			proxyTextFormat.font = value;
			invalidate( );
		}

		public function set color(value : uint) : void
		{
			proxyTextFormat.color = value;
			invalidate( );
		}

		public function set size(value : Number) : void
		{
			proxyTextFormat.size = value;
			invalidate( );
		}

		public function set letterSpacing(value : Number) : void
		{
			proxyTextFormat.letterSpacing = value;
			invalidate( );
		}

		public function Label( id : String = "label" )
		{
			super( this, id );
		}

		override protected function init() : void
		{
			textField.selectable = false;
			textField.autoSize = "left";
			addChild( textField );
			super.init( );
		}

		override protected function draw() : void
		{
			proxyTextFormat.align = _textAlign;
			textField.defaultTextFormat = proxyTextFormat;
			textField.setTextFormat( proxyTextFormat );
			super.draw( );
		}

		public function setTextFormat(format : TextFormat, beginIndex : int = - 1, endIndex : int = - 1) : void
		{
			textField.setTextFormat( format, beginIndex, endIndex );
		} 

		public static function validateAntiAliasType(value : String) : String
		{
			switch (value)
			{
				case CSSProperties.ADVANCED:
					return value;
					break;
				default:
					return CSSProperties.NORMAL;
					break;
			}
		}

		public static function validateAutoSize(value : String) : String
		{
			switch (value)
			{
				case CSSProperties.LEFT:
				case CSSProperties.RIGHT:
				case CSSProperties.CENTER:
					return value;
					break;
				default:
					return CSSProperties.NONE;
					break;
			}
		}
	}
}

As you can see, this label component functions like a TextField through composition. I do this by creating a instance of a TextField and uses setters to update its values. This may seem like over-kill, but by doing things this way I take advantage of two features from Flash Camo. First off I extend the AbstractDisplay > CamoDisplay > BoxModelDisplay set of classes so I get CSS styling and BoxModel for "free". Also, I no longer need to create a separate TextFormat to style the TextField and apply it each time there’s a change. This component allows me to simply apply TextFormat properties and it automatically updates the TextField instances properties. This is important when we look at how PropertySelectors are applied.

I have already shown you how our AbstractComponent automatically applies css styles to our components but let’s look at what goes on behind the scenes in the CamoDisplay when we call "applyProperties". Here’s what the code looks like:

public function applyProperties(style: PropertySelector):void
{
	clearProperties();

	PropertyApplierUtil.applyProperties(this, style);

	invalidate();
}

A few things are going on here. First, all properties are cleared from the CamoDisplay. Next, we use a utility class called PropertyApplierUtil to apply a PropertySelector to the CamoDisplay instance. I mentioned earlier that PropertySelectors are Objects created from CSS selectors. Well the values of the object are strings, but we will need a way to convert a font’s size to a number. This utility automates the process by analyzing the value types of a class’s public variables and getters, then converts the matching PropertySelector’s values to the correct type. Here is an example.

Let’s say you want to set the font size on our Label component. You may have a style that looks like this:

.Label
{
	size: 30;
}

When you apply the ".Label" PropertySelector to the Label instance (remember this is done automatically for us) the PropertyApplierUtil looks for a property called "size" on the Label instance. Once it finds it, it checks the properties value. Since we have a getter called size that accepts a number value, the utility will automatically convert the PropertySelector’s size value into a number and set it on our component. You don’t have to do anything special, the utility natively handles Strings, Number, Arrays, Objects, Colors (units) and a few other types. As long as your public variable has a type the utility can convert, any matching properties will automatically be set. We will see this in action in the next step.

Step 10: Using the Label Component

Let’s go into our Doc Class and replace our SimpleDisplay demo by replacing the init function with the following:

protected function init() : void
{
	trace( "Hello World" );
	createLabel();
}

Then create a new function under our init function:

private function createLabel() : void
{
	label = new Label( "siteLabel" );
	addChild( label );
}

Don’t forget to add the following parameter:

private var label : Label;

As well as our import:

import com.jessefreeman.components.Label;

Finally, we’ll need to add the following styles to our css file:

.Label
{
	font: Arial Black;
	size: 20px;
	embedFonts: true;
	color: #ffffff;
	anti-alias-type: advanced;
}

#siteLabel
{
	text: ANATOMY OF JESSE FREEMAN;
	x: 155;
	y: 60;
	size: 18px;
	rotation: 24px;
	letter-spacing: -2;
	text-height: 30px;
	alpha: .5;
}

Now if you compile the swf you should see your label with the text "ANATOMY OF JESSE FREEMAN".

The label automatically used ".Label" along with "#siteLabel" and styled itself. See how easy that was? A few lines of code, some CSS and we’re up and running in no time.

Now you have a reusable Label Component that can by styled with css. This class is by no means finished. You can continue to add as many getters or setters as you need to make this Label fully customizable. I simply provided you a base to get started with. As you begin to extend off the framework it’s important to understand some of the underlying draw logic.

Step 11: CamoDisplay Invalidation

You may have noticed from our Label component that the "invalidate()" method is called after we change a value in any of the setters. Redrawing the BoxModel and display is very expensive so to help alleviate the burden of constantly refreshing the display, the CamoDisplay waits until the next frame to redraw itself. This technique is used in Adobe’s own components and is very efficient in cutting down on waisted cpu processes. It is something you should keep in mind when extending the CamoDisplay and using invalidate on your own custom setters.

The other important method you should know about is "draw()". After the display has been invalidated and a new frame is being rendered by the Flash Player, draw gets called automatically by the CamoDisplay. If you have custom display logic this is the best place to put it. Once "draw" is called, the invalidate flag is reset and the CamoDisplay will not redraw itself until it is invalidated again.

If you are doing complex animations like changing the width and height or require constant updates, you can override the invalidation by calling "refresh()" at any time. This will immediately force the CamoDisplay to redraw. Use this when you need to have constant display updates since it can become very intensive to render.

Step 12: Create A Bobble Container

We’re going to create a class called "BobbleContainer" in "com.jessefreeman.components" package

Here’s the code:

package com.jessefreeman.components
{
	import com.jessefreeman.components.AbstractComponent;

	import flash.events.IEventDispatcher;
	import flash.events.MouseEvent;

	public class BobbleContainer extends AbstractComponent
	{

		protected var _active : Boolean;
		public var rollOverForce : Number = 1;
		public var noddingForce : Number = 0;
		public var noddingAngle : Number = 0;
		public var noddingRange : Number = 30;
		public var noddingHit : Number = .7;
		public var noddingDamp : Number = .985;

		public function BobbleContainer(id : String = "bobbleContainer")
		{
			super( this, id );
		}

		public function set active(value : Boolean) : void
		{
			_active = value;
			if(_active)
				addEventListeners( this );
			else
				removeEventListeners( this );
		}

		public function get active() : Boolean
		{
			return _active;
		}

		override protected function init() : void
		{
			super.init( );
		}

		protected function addEventListeners(target : IEventDispatcher) : void
		{
			target.addEventListener( MouseEvent.ROLL_OVER, onRollOver );
			target.addEventListener( MouseEvent.ROLL_OUT, onRollOut );
		}

		protected function removeEventListeners(target : IEventDispatcher) : void
		{
			target.removeEventListener( MouseEvent.ROLL_OVER, onRollOver );
			target.removeEventListener( MouseEvent.ROLL_OUT, onRollOut );
		}

		public function calculateBobble() : void
		{
			if (noddingForce)
			{
				if(noddingForce < .05)
					noddingForce = 0;
				rotation = Math.sin( noddingAngle ) * noddingForce * (noddingRange * .5);

				noddingAngle += noddingHit * noddingForce;
				noddingForce *= noddingDamp;
			}
		}

		protected function onRollOver(event : MouseEvent) : void
		{
			if(noddingForce < (rollOverForce * .5))
			{
				noddingAngle = 0;
				noddingForce = rollOverForce;
			}
		}

		protected function onRollOut(event : MouseEvent) : void
		{
		}
	}
}

In our Doc Class, let's create a BobbleContainer instance to test our code with. Let's add the following function below createLabel:

protected function createPerson() : void
{
	bobbleTest = new BobbleContainer("TestContainer");
	addChild(bobbleTest);
}

You will need the following property:

private var bobbleTest : BobbleContainer;

then import:

import com.jessefreeman.components.BobbleContainer;

In order to get this to work we will need to add a few more things. In our init function add the following:

createPerson();
addEventListener( Event.ENTER_FRAME, onEnterFrame );

Below the init function add:

private function onEnterFrame(event : Event) : void
{
	bobbleTest.calculateBobble();
}

We're almost done. Add the following to your CSS file and hit compile:

.BobbleContainer
{
	active: true;
	rollOverForce: 1;
	roll-over-force: 1;
	nodding-force: 0;
	nodding-angle: 0;
	nodding-range: 10;
	nodding-hit: .7;
	nodding-damp: .985;
}

.SimpleDisplay #TestContainer
{
	border: 4 solid white;
}

You should now be looking at a red box with a white border which bobbles when you move your mouse cursor over it.

Now that I've fully introduced Flash Camo's CSS parser I'm going to refer to it as Properties/Property Sheet instead of CSS from this point on. You're encouraged to think of Camo's PropertySheets as a natural extension of configuring the property values of your classes. Go ahead and change the values of the "nodding-range" or the "nodding-hit" to see how it works. Imagine configuring your entire application without having to recompile! Not only that but you can simply restyle an app by pointing it to a new PropertySheet.

Before we go, let's take a look at one last thing. Notice in our PropertySheet the ".SimpleDisplay #TestContainer" selector. Flash Camo supports selector inheritance. We refer to "#TestContainer" as the subject and ".SimpleDisplay" would be an ancestor element. If you were to call "getSelector" for " #TestContainer" the parser will automatically return a PropertySelector with properties from ".SimpleDisplay" and "#TestContainer" merged together. Any conflicting properties will be overridden by the subject style. Pretty cool right?

Step 13: Bobble Person

Now we're ready to create a class that will manage our BobbleContainer body parts. Let's create a Class called "BobblePerson" in the "com.jesseFreeman.components" package.

Here's the code:

package com.jessefreeman.components
{
	import com.jessefreeman.components.AbstractComponent;

	public class BobblePerson extends AbstractComponent
	{

		protected var _partIds : Array = new Array( );
		protected var partInstances : Array = new Array( );
		public var partDisplayId : String;

		public function set partIds(value : Array) : void
		{
			_partIds = value;
			createParts( );
		}

		public function BobblePerson(id : String = "BobblePerson")
		{
			super( this, id );
		}

		public function get partDisplay() : BobbleContainer
		{
			var index : int = _partIds.indexOf( partDisplayId );

			return (index != - 1) ? partInstances[index] : null;
		}

		override protected function init() : void
		{
			super.init( );
		}

		public function createParts() : void
		{
			var total : int = _partIds.length;
			var i : int;
			var part : BobbleContainer;
			var partID : String;

			for (i = 0; i < total ; i ++)
			{
				partID = _partIds[i];
				part = new BobbleContainer( partID );
				addChild( part );
				partInstances.push( part );
			}
		}

		public function calculateBobble() : void
		{
			var total : int = partInstances.length;
			for (var i : int = 0; i < total ; i ++)
			{
				BobbleContainer( partInstances[i] ).calculateBobble( );
			}
		}
	}
}

As you can see here, we have a few methods revolving around setting up, creating and updating body parts. This class creates parts once the partIds setter is given a value. We're doing this through a setter because we will be using our PropertySheet to pass in the array of parts. Once we have a list of parts the createParts method is called. It loops through the partIds Array and creates new instances of the BobbleContainer. Each container is given an ID then pushed into an array called partInstances so we can keep track of all of the parts.

Our final function is for updating the parts. Remember the enter frame loop we set up in the Doc Class that updated the demo BobbleContainer? We'll connect that loop to the BobblePerson's calculateBobble method and it will manage calling calculateBobble on each of our parts. This way we only have one enter frame loop running in our app at any time.

Now we're ready to set this class up. Let's replace a few things in our Doc Class in order get our BobblePerson up and running. Start by replacing your "createPerson" method with the following:

protected function createPerson() : void
{
	bobblePerson = new BobblePerson( "BobblePerson" );
	addChild( bobblePerson );
}

Next do a find and replace for "bobbleTest" with "bobblePerson".

Then replace:

private var bobblePerson : BobbleContainer;

with:

private var bobblePerson : BobblePerson;

Make sure you also import:

import com.jessefreeman.components.BobblePerson;

Finally, you'll need to replace your entire PropertySheet file with the following:

/* CSS file */

.BobblePerson
{
	part-ids: head body leftArm rightArm leftLeg leftFoot rightLeg;
	part-display-id: body;
}

.Label
{
	font: Arial Black;
	size: 20px;
	embedFonts: true;
	color: #ffffff;
	anti-alias-type: advanced;
}

#siteLabel
{
	text: ANATOMY OF JESSE FREEMAN;
	x: 155;
	y: 60;
	size: 18px;
	rotation: 24px;
	letter-spacing: -2;
	text-height: 30px;
	alpha: .5;
}

.BobbleContainer
{
	active: true;
	rollOverForce: 1;
	roll-over-force: 1;
	nodding-force: 0;
	nodding-angle: 0;
	nodding-range: 10;
	nodding-hit: .7;
	nodding-damp: .985;
	background-color: silver;
	background-color-alpha: .5;
}

#body
{
	x: 355;
	y: 229;
	width: 181;
	height: 144;
}

#head
{
	x: 449;
	y: 250;
	width: 139;
	height: 143;
}

#leftArm
{
	x: 381;
	y: 313;
	width: 195;
	height: 80;
}

#leftFoot
{
	x: 145;
	y: 213;
	width: 127;
	height: 80;
}

#leftLeg
{
	x: 263;
	y: 235;
	width: 125;
	height: 80;
}

#rightArm
{
	x: 419;
	y: 176;
	width: 184;
	height: 125;
}

#rightLeg
{
	x: 275;
	y: 176;
	width: 218;
	height: 171;
}

If you do a quick compile you'll see a bunch of semi-transparent boxes overlapping each other, which bounce when you roll your mouse over them.

We have the beginnings of our website. Next up we'll add Labels to each of the parts so we can keep track of them.

Step 14: Adding Labels to BobbleContainers

Let's go into our BobbleContainer class and add the following function after init:

protected function createLabel() : void
{
	label = new Label( id + "Label" );
	addChild( label );
}

Next modify the init function by adding the following:

createLabel( );

above :

super.init( );

You'll also need to create the following property:

public var label : Label;

And import our Label class:

import com.jessefreeman.components.Label;

As you can see we're creating our new label and using the parent class's "id + “Label”" for the id. This allows us to give a unique id to each label created, yet still allows us to style each one via its Class Name. Let's add the following to our PropertySheet:

/* BobbleContainer Labels */

#bodyLabel
{
	alpha: 1;
	rotation: 20;
	x: -35;
	y: -30;
	text-align: center;
	auto-size: center;

}

#leftArmLabel
{
	text: bFreeDesign;
	x:  -90;
	y: 25;
	rotation: -9;
	size: 18;
	letter-spacing: -3;
}

#leftFootLabel
{
	text: eMail;
	x: -78;
	y: -13;
	rotation: 6;
}

#leftLegLabel
{
	text: FlashBum;
	x: -95;
	y: -40;
	rotation: 9;
}

#rightArmLabel
{
	text: FlashArtOfWar;
	x: -80;
	y: -75;
	rotation: 32;
	font-size: 16;
	letter-spacing: -1;
}

#rightLegLabel
{
	text: iLikeToDream;
	x: -157;
	y: -83;
	rotation: 27;
}

Now if you compile you'll see that all of our Labels are working and are getting configured by CSS!

To Be Continued..

We've gone over a lot of stuff in this first tutorial. It's best that we take a break and let it all soak in. Next we'll go over how to skin our BobbleContainer using Decals, add some interactivity, optimize/clean up the code and talk about deployment. Stay tuned!