1. Code
  2. Workflow

Setting Up a Flash Development Sandbox: Part 1


Welcome to part one of the Flash Development Sandbox Tutorial! In this tutorial we're going cover ActionScript development outside of the Flash IDE. As much as we would like to put it off, the day is coming closer and closer when we will no longer be able to write complex applications in Flash and will be forced to choose a different editor.


As ActionScript evolves as a language, a clearer line is being drawn between Flash Designers and Developers. Being a self taught programmer, I understand the fear and anxiety of moving away from Flash and off to the land of text editors and math. Hopefully this tutorial will be a good primer in getting set up and help ease the transition.

I do have this warning, this is not a perfect setup for everyone. It has taken me a few years to get this to where it is now and I am always changing/tweaking it to serve my needs. ActionScript development is constantly evolving and no one solution is ever perfect. As you go through this tutorial please take each step with a grain of salt. You may need to play around with what works best for you. Depending on your OS you may even need to set things up a little differently. In the end, the notion of having a clean process and custom sandbox will help make you the most productive developer you can be.

Step 1: Pick An OS


This is a heated discussion so I'm not going to get too deeply into it. At the company where I currently work, the decision has already been made for me. The same is probably true for a lot of people. For me it's Mac all the way. I used to use a PC for my Flash Development but over the years, as OS X has been cleaned up and improved, it was just too hard to go back.

This tutorial is a little Mac-centric. Don't be afraid, all of this will work on your PC. If there are PC specific things I will make sure to take screen shots of it in Windows (another thing Macs can also run). I can't lie though, PCs still run Flash Better then Macs. They also make up the majority of the computer users out there. For now it's a PC world and us Mac people just have to accept it. The best part of this tutorial is that it's a 100% cross platform solution. So without further ado, let's talk about ActionScript Editors.

Step 2: Pick An Editor

To a lot of people, the most obvious editor for writing ActionScript is Flash CS 4. Most are are probably using it right now and there is nothing wrong with that. As a developer, I rarely use the Flash IDE. The only times I fire it up is if I need to do an animation that is too complex to be done programatically (hasn't happened yet), if I need vector assets in my project, or if I need fonts. Other then that, Flash CS 4 collects dust on my computer.

Developer editors are broken down into 3 different types: Eclipse based, stand alone, or text editors. Here is a convenient chart to show all the editors available and which OS's they run on.

Editor Type ActionScript OS Cost
Flex Builder 3 Eclipse Base AS 3/Flex Mac/PC Starting at $249
FDT Eclipse Base AS 2/3/Flex Mac/PC Staring at €399
Flash Develop 3 Stand Alone AS 3/Flex PC Free
TextMate Text Editor AS 2/3/Flex Mac €39
E-Editor Text Editor AS 2/3/Flex PC $34.95

As you can see, we have a lot of choice. For this tutorial we're going to focus on an Eclipse based editor; Flex Builder 3. FDT is an excellent editor but Flex Builder has a few key advantages that make it a must have for any ActionScript Developer. It's important to note that I've heard great things about Flash Develop, not to mention that it's free. Unfortunately it only runs on a PC so it's out of the question. My ideal sandbox has to be cross platform. I never know if I will take a new job in an all PC or all Mac company and I have to be able to keep things consistent. I invite you to try out each of these editors and pick the one that feels right. When it comes to Flex Builder or FDT (which can cost a lot of money) it's best to make the most out of the demo period they give you.

Before we move forward, let's talk about what an Eclipse base editor is and how Flex Builder fits into this category. Eclipse is an open source editor, used primarily by Java Developers. "But wait, you said that Flex Builder costs money?" Well here's the catch; Eclipse is free, but has a plug-in architecture, which allows you to install all kinds of programming language editors. Flex Builder is actually a plugin that Adobe sells. There are two version of Flex Builder, the plug in and the stand alone (a version of Eclipse stripped down which focuses solely on ActionScript/Flex Development and not Java). Let's get the editor and I'll go over it's advantages.

Step 3: Download Editor


Let's get started by downloading Flex Builder 3 from Adobe. While you wait for it to download I'll go over Flex Builder's features and why I feel it's one of the best editors out there.

Download Flex Builder 3 * Make sure you select "Flex Builder 3 Professional" and not the "Adobe® Flex® Builder 3 Professional Eclipse Plug-in" at the bottom. *


There is a little bit of confusion about Flex Builder from an ActionScript developer's point of view. As the name would imply, Flex Builder is for Flex. Right? Not true. I have been using Flex Builder for all of my AS 3 projects for the better part of a year. Before that I used FDT for about 2 years. Flex Builder has a special configuration for ActionScript-only projects. This lets us take advantage of the built in ActionScript editor and doesn't force us into using Flex at all. So what is so special about Flex Builder?

  • Code Hinting Eclipse has a powerful string parsing engine. This allows Eclipse-based editors to offer up code hinting while you are typing. Let's say you want to create a new Sprite. Normally you would have to type out new Sprite() and import the sprite class by hand. In Flex Builder, when you start to type out Sprite it will automatically pop up a list of suggestions. When you select a class from the list, it will automatically import it for you. The best part is, as you add your own custom classes Flex Builder will offer up code hinting on them as well.
  • Import organization Adobe has been making great strides in cleaning up the way you import and and manage classes. The latest builds of Flex Builder now offer up import organization to help you make sure you only import what you are using and find out what you are missing.
  • Compiler Errors As you save your code, Flex Builder will automatically display any errors you may have in your code. This way you can try to fix them before compiling your application.
  • Faster Compiling In Flex Builder, your application is automatically built in the background. Each time you hit "save" a new version is compiled so when you run your app, it launches instantaneously. Waiting for a large Flash App to compile is a thing of the past. This is part of the secret to how Flex Builder launches projects quickly. When they do the compile, any errors are shown in the editor and if everything is problem free Flex Builder just launches the compiled swf.
  • Local Version Control We'll talk about version control in more detail later, but it's good to know that every time you hit "save" Eclipse makes a backup of your changes and time stamps them for you to review later. You can increase the amount of revisions Eclipse saves for each workspace so you can rest assured that you can go back and see what you did several saves before.
  • Plug Ins Eclipse is completely extendible via plugins. You can keep adding plugins customized by Flex Builder to work they way you need them to. Do you work with PHP? Get a PHP plugin. Need some JavaScript? They have one for that as well. Need project management in your editor? You're covered.
  • Organization Eclipse stores your projects in a workspace (we'll cover this later) keeping all of your projects in one place. This makes backing up a piece of cake.
  • Debugger Flex's Debugger is amazing. I have not found anything else like it. It allows you to explore objects at runtime, go back through function calls, and use break points to debug your code.
  • Profiler Flex Builder lets you monitor memory usage, isolate memory leaks, track instance creation and monitor the Garbage Collector. This is something I couldn't live without.

Hopefully you are a slow reader and by now have downloaded a copy of Flex Builder. If not, proceed when you're ready to install it.

Step 4: Installing Flex Builder

Simply install Flex Builder with the default settings. Don't worry, we'll be customizing a lot when it's installed. Once Flex Builder has finished installing, open it up - let's take it for a spin.

Step 5: Understanding The Workspace

The workspace is the main directory where Eclipse stores critical data such as settings, any customization you make to the editors, as well as some invisible meta data files it needs to run. Each workspace is a self contained development area. This allows you to back up the workspace and move it to a different computer yet retain all the settings and configurations you have set up.

Eclipse also uses the workspace to store your projects. Flex Builder automatically creates this workspace for you in your Documents folder. It should be called "Flex Builder 3" and for right now don't worry about renaming your workspace. Even if you create your own workspace, Flex Builder automatically creates the Flex Builder 3 workspace, so you're kind of stuck with the way it automatically gets set up. Hopefully this will change with future versions of Flex Builder.

As we start to create our ActionScript projects they will be automatically set up in the workspace. You may have used your own folder structure to help organize past projects but that is now how Flex Builder handles it. All projects sit in the root of the workspace folder. We'll use other techniques for organizing these projects, but understanding that everything goes in a single workspace is a tough thing to swallow at first. It is possible to put your projects anywhere on your computer, they do not always have to sit in the workspace folder, but to keep things organized its best to follow this setup.

Step 6: Tweaking The Settings

Now that Flex Builder is open, we want to tweak a few settings. Go to the Flex Builder > Preferences menu on Mac OS X or Windows go to Window > Preferences.

Once you're in the Settings, unfold the "General" Tab and go to "Keys".

This area handles all of the short cut keys and how to call them. Below is a chart of the keys I set up and a short description on what they do.

Command Description Key
Debug Last Launched I use this to debug my applications. Since I grew accustomed to Flash's Command + Return to run a Movie, I tend to map this function to that key set up. This allows you to debug the last program you have launched (I will explain Runs and Compiling a little later). This function I map to Command + Return since it is not set up to that by default. Command Return
Run Last Launched *Optional* If you don't want to use the Debug Player when you compile your Flash app, you can use this as your default build launcher. It will launch your project in a default browser without any debug code and will ignore any breakpoints. You should not map "Debug Last Launched" and "Run Last Launched" to the same key. When using both, I tend to map Run Last Launched to Shift + Command + Return Shift + Command + Return*
Delete Line To Delete an entire line of code simply press Command + D. Command + D
Find and Replace This is a standard Find and Replace in a document. Command + F
Find in File This is a powerful Find and Replace type function that lets you search across multiple files. Shift + Command + F
Line End Jumps to the end of the line. Command + Right Arrow
Line Start Jumps to the beginning of a line. Command + D
Move Lines Up Take a selection of lines and move them up. This is useful when organizing code or changing the order of actions in a given method. Command + Up Arrow
Move Lines Down Take a selection of lines and move them down. Command + Down Arrow
Next Perspective Perspectives represent different types of Editors or areas of functionality in Flex Builder. Imagine going from the ActionScript editor to the debugger to the SVN repository explorer. Each of these is a different type of perspective and have their own collection of relevant windows. I tend to think of this a an application switcher inside of Eclipse. I use this a lot and felt it was better to change the default keys to something easier to call. Shift + Command + Right Arrow.
Previous Perspective See Next Perspective description above. I change the default keys to the following. Shift + Command + Left Arrow.
Organize Imports I had mentioned before that Flex Builder will help you keep track of Imports. Well this is the short cut to do it. Flex Builder will automatically remove any packages that are not needed and reorder used imports based on their priority and source package. Shift + Command + O
Save All When you have multiple documents open and you need to save them all to do a build, use this. Shift + Command + O
To Lower Case Use this to convert a selection to lower-case text. Shift + Command + Y
To Upper Case Use this to convert a selection to upper-case text. Shift + Command + X
Word Completion Probably the most powerful command in Flex Builder. This calls an auto complete menu based on what you have typed in. If you were to type out "Spr" and call the word completion it would pop up a menu with Sprite (and a few other close matches) for you to choose from. Once you make a selection, Flex Builder will also attempt to import the class for you. Your custom classes will also show up in this menu along with the built in classes the Flash Player supports. I can't live without this! Control + .

For a full list of Short Cuts (Mac-centric) check out this great post from Elrom Design's Blog.

So that covers some of the most important short cuts, but what about configuring the Flex Plugin? For that let's look at the Flex option in the Preferences window. Here you can change all kinds of settings such as the amount of space for tabs, how your code is formatted and colored, as well as what SDK to use. I tend to use the latest version as my default and later I will show you how to use the new Flash Player 10 SDK.

Before we leave this menu, let's check out one last thing; the "Editors" section under "General". You can customize how files are opened and edited in the File Associations section. Flex Builder comes with a default set of editors covering text(.txt), ActionScript (.as), CSS (.css) as well as FLAs (.fla). If you want to change the default editors associated with a specific type of file, this is the place to do it.

By now we should have a completely configured Flex Builder. It's time to talk about how we can extend Flex Builder through plugins.

Step 7: Installing Plugins

Since Flex Builder is built on top of Eclipse, we can take advantage of some great Eclipse plugins already out there. Plugins add missing features and editors to help extend the core application. Here is a list of Plugins I use:

  • Spell Check: Anyone who has read my blog knows that I am not the best at spelling. It's vital that I have some sort of spell check in any editor I use. Although this one is far from perfect, it does at least show me where I am making a foool of myself.
  • XMLBuddy A great plugin for writing xml in Eclipse. This does basic formatting, validation, and error flagging. Make sure you get the version for Eclipse 3.1+
  • Mylyn If you're looking for a project manager/task manager check this plugin out. It integrates right into Flex Builder and offers a ton of features.
  • SubClipse is a SVN client for Eclipse. I will go into installing this later in the tutorial.

Before we start installing plugins, let's talk about version control.

Step 8: Version Control

This is not a Flex Builder specific topic but a workflow and life saving tool. Version control is a way to manage changes in your documents. Every time you "commit" a file to the Version Control Repository the changes are saved. When you need to go back and compare what you did before, you are able to go back through the history of your document to compare revisions and changes.

If you are not using Version Control you are missing out on an incredible life saving tool. How many times have you been frantically trying to fix a bug moments before a site is supposed to go live, saving and compiling the app over and over again. Eventually you get to a place from where you can't remember how to go back - and undo is not working. Version control is your answer. Also when working in a team, managing changes across multiple files and different developers is a lot easier with version control.

Unfortunately, going into the details of version control is out of the scope of this tutorial but here is a list of the most common ones used.

  • CVS This is the first Version Control system I ever used and is still very popular. CVS support is built into Eclipse.
  • SVN This is the next step up from CVS. One of the most over looked features is SVNs ability to preserve folder structure.
  • GIT This is a relatively new Version Control System but one I have been very interested in using. It allows for synchronization across multiple repo check outs including local and server versions. Unfortunately the GIT Eclipse plugin still needs a little more work.

For this tutorial we are going to use SVN. It is a really great Version Control system and, as you will see later, the one which Google Code offers free of charge.

Step 9: Installing SVN Plugin

Flex Builder comes with support for CVS built in but we are going to use SVN. To do this we are going to need a plugin.

Let's go to SubClipse's site and check out the install instructions:

Most Eclipse plugins are installed through the help menu. Let's got to Help > Software Updates > Find and Install...


Next, we choose "Search for new features to install" and hit next:


Click on "New Remote Site..." and now we will need to supply a name for the connection as well as the path to the plugin:


After clicking ok, you will be brought back to the Install window with Subclipse selected. Click "Finish" to begin the installation process:


Here's where the fun begins! Pay close attention to the packages I've selected. Some of parts of this plugin will not with with the stand alone version of Flex Builder. To save you the trouble of figuring out what works and what doesn't, I've made the following selections for you. Don't worry, you're not missing anything you don't need. We're simply selecting the basic setup to get you up and running.


Next make sure you read the entire Software User Agreement and click next.


After that, click finish and you should be on your way to downloading the plugin.


Once it's downloaded you have to select "Install All" from the Feature Verification Window:


And that's it. Simply select yes to restart Eclipse and load in the new SVN Plugin.


So we've installed our first Eclipse Plugin. It wasn't to bad, but not the most user friendly of processes. Most plugins give you similar instructions on how to install them. Also, you can drag in a plugin to your Flex Builder's app folder and put it in the plugins folder. A few of the older plugins work that way, so make sure you always read the readme.txt included with each download.

Step 10: Setting Up A SVN Repo

We're going to want to set up a new SVN Repository. This process can be challenging for people who are unfamiliar with using the command line so lets skip setting one up from scratch and look at Google Code. Google code is a great feature of Not only can you find all kinds of open source projects and libraries but you can also host your own projects as well. Having your work as Open Source is not only good for the environment but allows you to have others share in the work you are creating.

Let's get started by creating your own project on Google Code. You'll need a google account to set this up.


When you create a new project you are going to be asked to fill in some information about the project.


As you can see, I filled in everything including picking a license (I tend to use MIT but you can read up on each the ones offered). I also added keywords to help people find my project.


Now that you have created your project, you will be presented with your project's home page. This site is basically a wiki so you can edit your home page's content, add in sub pages and basically flesh out your project as if it was a regular website. Here is an example of my Flash Camouflage's Google Code Page to get an idea of how it can be set up.


The final thing you will need to take note of is the path to your SVN Repo. You can find it under Source > Checkout. You should see something similar to the following, but with your user name and project name:


For now keep a mental note of these, we will use them later.

Step 11: Setting Up A SVN Repository Location

When working with SVN Projects you will need to perform a "Check Out" of the code. SVN is usually set up with 3 folders, trunk, branches, and tags. Let's look at what each one does:

  • trunk This is the main area where we keep our code. Trunk represents the current stable build of a project and is usually what is running on a production server.
  • branches This is where you should keep copies of your project that are unstable or are being worked on by individual developers. Let's say you need to add a new feature to your project but you don't want it to affect the stable build in the trunk; we would create a new branch of it (basically copying files in the trunk) in the branches directory. From there we can make all of our changes then when its ready, merge it back into the trunk.
  • tags When a project hits a stable build, such as 1.0, we take a copy of the trunk and copy it in the tags folder. This is similar to a branch since we are making a copy of the trunk, but tags are not meant to be worked on once they are created. Making tags is key when creating incremental builds of a project. If anything ever happened, you would be able to go back to a stable tag and compare the changes.

Here is a great resource for learning more about version control.

Since checking out an empty project isn't fun, let's go to and check out a copy of "Tweener". Tweener is a excellent animation library for ActionScript 2 & 3. We are going to need the following svn checkout url Let's go into Eclipse and open the SVN Explorer. You can do this by opening Window > Perspective > Other and select the "SVN Repository Exploring" perspective.


Now you should see a SVN Repositories window and its tab selected on the left hand side. The content of this window will be blank, since we don't have any repositories set up yet. Right click in the white space of the window and select New > Repository Location... from the contextual menu which pops up.


You'll be presented with a url field, so paste in the path to Tweener's svn trunk and hit finish. Since this is a public check out (meaning you cannot save edits back to the svn repository) you will not be prompted for a password.


There you go, you have just set up your first SVN repository in Flex Builder! You should see the following:


While you are at it, you may want to setup these other cool Google Code projects as well:

Step 12: Checking Out A Project From SVN

Now that we have Tweener set up in our SVN Repository Explorer, let's check it out. Before we get too excited, let's unfold the repository and see what's in it first. You can do this by right-clicking on the repository and selecting "Checkout" from the contextual menu:


When checking out something from SVN, Flex Builder will present us with a project wizard. For Tweener we will want to select "Check out as a project in the workspace", rename it to "Tweener" and then click Finish:


Tweener is a special example of an SVN checkout. Since it contains, AS 2 and 3 src libraries, along with examples and documentation, we're not going to be able to turn this into a true Shared Library. You can choose to only check out the as3 folder as its own project, but for this part of the example we are going to leave it as a generic project. I'll get into shared libraries in the next step but first we need to check out one more project.

Let's get a copy of Flash Camouflage version 2. Set up a new repo with the following info:


Notice how we're checking out a specific tag of Flash Camo. This insures that as the project evolves and changes you will still be able to build off a stable version that will remain unchanged. Check out the repo and choose "Check out as a project configured using the new Project Wizard".


Now we're going to see the New Project window. From here go into the Flex Builder folder, select "Flex Library Project" and click next:


Now let's give our project a name; "FlashCamo2" and click next.


Now that we've selected the Flex Library Project, we have to let the wizard know where the code is for this library. I always put my code in a src folder, so let's check that option and hit Finish


At this point you will get a dialog box to switch to a new Perspective. The Flex Development Perspective is where you'll be doing all of your coding. Click yes to continue.


You may see the following warning.


Just ignore it and click OK. When a project is set up by the wizard it sometimes creates a few default files that may get overridden by the project you're checking out. This is normal, you should always allow the checkout to override any default files set up by the project creation wizard. Now the project should be downloading to your computer. When it's done you will be in the Flex Development perspective


We've finally checked out two projects from SVN. Now let's talk about Shared Libraries and how they work.

Step 13: Shared Libraries

In Flex Builder there are two types of Shared Libraries; directories on your computer containing code (these will most likely sit inside one of your projects) and Flex Library Projects. Let's talk about a Library Project first.

Don't be confused by the name, a Flex Library Project is not just for Flex but a great way to package up code for any AS 3 project. Basically, a Flex Library Project will bundle up code you place in the source directory and compile a SWC in the bin directory for you. A SWC is a zip-like file that contains a catalog.xml, ActionScript files, SWFS, and a few other files.

SWCs have been around since MX 2004 and are an excellent way to compile code libraries to build off in other projects. It was previously only possible to create SWCs in the Flash IDE (it was an option in the "Publish settings" panel) but Flex Builder will automatically compile them for you if you are working in a Flex Library Project. It's important to note that you can't load SWCs into flash at run time and they don't have to contain only code. I have used SWCs to import assets such as vectors from flash and fonts into my ActionScript projects.

In step 12 we checked out two code libraries from svn. We're going to look at how to convert Flash Camo into a swc. Make sure you're in the Flex Development Perspective. You can switch perspective at any time in the upper right hand corner of Flex Builder.


Now is a great time to go over the basic layout of Flex Development Perspective. On the left you will see a tab called "Flex Navigator". This will show all of your projects, it allows you to explore the files in each project and gives you a glimpse into what is going on in your workspace. Below that is the "Outline" window. When you have Classes open you will see a convenient list of variables, functions and other class information. This is contextual to each file you have open and are working in.

In the middle is your main window. Right now you may see a "Welcome to Flex" window. Notice how this is just an open tab, you can close this and open any code file from the Flex Navigator. Below the main window are a few other tabs. The only one I want to go over now is the "Problems" tab. Let's take a look:


As you can see, Flex Builder is automatically attempting to warn you about some errors in the code. You can see from the Resources column that the project with the problem is FlashCamo2 and the error is:

This is a simple error to fix, but one that may stress you out if you don't know what's going on. Sometimes when you set up a library the path to the src code does not get correctly set so you see "nothing was specified to be included in the library". To fix this we need to right-click on your FlashCamo2 Project in the Flex Navigator and go down to the bottom to select Properties. You should see a window like this:


The "Project Properties" window contains all the settings and configurations for each project. Depending on the type of project you are in you will see more or fewer options. Since this is a FlexLibrary Project we are going to want to make sure that it knows the correct path to the src directory. Click on the "FLex Library Build Path", make sure you have src as the Main source folder and that you have src checked under Classes to include in the library.


What this does is tell Flex Builder that everything inside of the src folder is part of the library and should be compiled into the final SWC. You can change the Output folder, but it's best to keep it as bin for now until you get comfortable with Flex Builder's workspace and directory structure. After you click OK, the window will close. Reopen the Properties for FlashCamo2 and you should have this in the Flex Library Build Path:


Now that we have all of the classes checked off we should look at one last settings panel; the Flex Library Compiler. This is where you can pass in specific compiler params to the Flex SDK compiler for the library project. Let's take a look:


In this tutorial we won't touch any of these settings, but it's still good to know what's going on. The Flex SDK version allows you to target a specific SDK. These include Flex 2.0.1 Hotfix 3 and Flex 3.1 (may be 3.1 depending on if you did an update - more on this later). Also, you can choose to include the Adobe AIR libraries if this project depends on them.

So now we've configured our first Flex Library Project. Let's close the properties window and go back to the Flex Navigator window. If we unfold the FlashCamo2 project and look in the bin directory you should now see a FlashCamo2.swc:


If there was an error in the code, you would not get a swc and there would be errors listed in the Problems window. It looks like we're good to go now, so let's create our first ActionScript Project. Don't worry about tweener, since this project was set up a little different then Flash Camo we are going to leave it as is. It's important to note that Tweener has a blue icon and Flash Camo is a little folder with books on it. This shows that they're different types of projects.

Step 14: Creating An ActionScript Project

Wow, we have gone over a lot so far! All of this work just to set up our first project. Well now that you have a hang of how to set up Flex, check out projects, and set up Libraries, creating your projects will be a walk in the park. We'll start by right-clicking in the Flex Navigator and choosing New > ActionScript Project from the contextual menu.


See how there are 4 types of projects? Here's a break down of each one and when to use them:

  • Flex Project - if you want to build a Flex App, this is the one to pick. You can still write AS 3 code but you will mainly be working in MXML templates and the project folder structure will be set up mainly for Flex Development work.
  • ActionScript Project - this is the main project I use. It allows you to code in AS 3 similarly to how you would work in Flash, but without the IDE.
  • Flex Library Project - this is a project comprised only of Code and will generate a .swc file in the end. All of my shared code and libraries are put into these.
  • Project... - will open up the full project selector. Based on the plugins you have, you will see a Java project, XML project, PHP project etc.

Now that we have picked out ActionScript 3 Project, we are presented with the new project wizard. I've already given my project the name "HelloWorld". Before you get all crazy and hit Finish, we have to go over 2 things. Firstly, the name of your project is very important. Notice how I use HelloWorld as if it was a Class, camel case with an upper-case first letter. Flex Builder will create a doc class that matches the name of your project. It's important to follow the naming conventions and standards of the language. You could of course change this later but I won't be covering that in this tutorial.

The second thing I wanted to show you is the Flex SDK version tab. Here, you can change the version for your needs. Just something to keep in mind. Now lets click on the Next > button so we can continue to configure the project. If you hit "Finished" by accident, you can manually perform these configurations through the project's Properties panel like we did in the previous step about setting up Flex Library Projects.

Our next screen allows us to set up the build paths, shared library and output folders for our project.


Here we've pointed our source folder to src (I have always used this nomenclature for my source folder but you can use what ever you feel comfortable with) and the Main application or Doc Class is already set up based on the name of the project. Finally, our output folder is set to the default bin-debug folder. I will talk about changing this later on in the second part of this tutorial so leave it as it is. The last thing we need to do is import our two shared libraries (Tweener and FlashCamo).

Since Tweener is not a Flash Library we can simply add its class folder as a regular source folder. Click on the Add Folder... button and let's navigate to where we checked it out.


Here I've gone into my Flex Builder 3 workspace and pointed it to the Tweener (Project) and the as3 folder. This is where the main classes for tweener are kept. When I select it I'm presented with the following path:


Eclipse has its own version of variables we can use to short cut all kinds of things, including paths to projects in the workspace. Notice the ${DOCUMENTS} token, telling eclipse that the root is inside of the workspace. This becomes more important as you begin working with ANT and more complex configurations of Flex Builder. Click ok. Now you should see the path added to the Additional source folders window. Before we close this, let's set up Flash Camo.

Since Flash Camo is a Library, we'll need to click on the Library path to add it. Let's take a look at our options:


Let's briefly go over some of the important options, you will see following items:

  • Flex 3.1 is already set up as your main lib. This makes sense since you are going to be using that to get the base AS 3 classes. Don't be alarmed that its says Flex, you will not have to import any of the Flash Framework to run your project. On a positive note you will be able to use some special Flex classes such as utilities if you want.
  • Next up are the Add Project, Add SWC Folder, and Add SWC. Remember I told you that SWCs contain code? Well if you downloaded a SWC off the internet or you have a folder on your computer where you keep a collection of SWCs, you can use the last two options to import them into your project.

Since we have Flash Camo as a project already, we can just add it with the Add Project... button. Once you have selected it, click ok and you will see the following set up for you:


Now we have successfully added Tweener and Flash Camo, let's click finish and get started. Welcome to your Hello World:


Step 15: Project Properties

So before we start coding we should check out the project's properties. Flex Builder is a little temperamental and making sure everything is set up correctly before you start coding will save you some time later, I promise!. Right-click on the HelloWrold project and let's check out what's going on under the hood.

Head over to the ActionScript Application area. Here you will see all of the runnable class files or doc classes in this project. It's possible to have more then one Doc Class but you can only have one default class. If you had others or wanted to switch one for another you can add/remove them here.


We can skip over the ActionScript Build Path since we already configured our shared libraries in the project creation wizard. Instead let's look at the ActionScript Compiler area.


This window is very important, this is where you set up all of the compiler settings which go into building your project. I have already covered switching to different SDK, so lets skip it and look at Copy non-embedded files to output folder. Personally I hate this option. I hate the fact that it's always checked by default. This setting will take any other files in your project such as images and code (basically anything that is not embedded in your code) and put it in the output folder. Therefore, if you keep PDSs or FLAs or documentation in your project outside the src folder, they will be copied over to the bin-debug (our default output folder) every time we do a build. We don't want this, so make sure you uncheck this every time you start a new project. You may find that you like this feature, but as you will see later when I go in to project folder structure and organization that it will be a big pain to have everything copied over to the bin-debug folder.

The Additional arguments area is another important one. This is where you can pass in compiler parameters when your project is built. Things like background-color, frame rate, even locations to output compiler setting as xml can all be done here. There are way too many parameters to get into here, so I usually keep this website bookmarked and close by when setting up a project.

One last thing to do before closing is to uncheck the "Enable integration with browser navigation". This is a Flex/Javascript integration setting that I have never used. When I want to have deep linking and let the user's browser back/forward buttons navigate flash I use swfAddress.

Make sure you click "Apply" then "OK" and we should be done configuring our project.

Step 16: Understanding Flex Builder's Folder Structure

In our Default project we have a few folders automatically set up for us. The first one [source path] as3 is a link to our as3 folder in the Tweener project. As you can see, you can go through all the classes and edit them as if they were part of your own project, but the originals stay in their own project. Next up is the bin-debug folder. This where your application is built. This is a combination of the compiled code that makes up your project in the src folder and the html-template files. This bin directory is never committed to SVN, in fact Flex Builder will do its best to never let you even try. You would never commit your bin folder anyway, your project should contain all the code need to get up and running if someone was to check it out. The bin-debug folder should be unique for each developer and never copied across dev environments.

The html-template folder is a special folder in your project. This contains a few basic files that Flex Builder uses to create a html wrapper page, as well as a the JavaScript embed/detection if you opted to have them created in the project settings. In this folder you'll find an index.template.html. If you open it up it will look like a normal html file except for a few variables scattered around. Flex Builder will fill these values in such as the size of the swf and the background color, all based on the compiler parameters you supply.

It's important to note that this folder's entire contents get copied over to the bin-debug folder every time there is a compiler. I like to keep my loadables such as XML, images, css, and other swfs in the html-template folder so when I do a build and load up the html wrapper in the bin-debug (this is done automatically and I will talk about it in the Run a project step) all of my assets get copied over.

Let's set up a few folders to get started. In the html-template let's add "images", "xml", "css" and "swfs" folders. Then in the main project folder add "docs"; this is where code documentation would go. Then "lib"; this is where our protects library assets such as FLAs, PSDs or reference material belong. After you create the lib folder lets add "FLAs" and "PSDs" folders in there. Afterwards your project should look like this:


This is usually how I start and organize all of my projects. Before we move on there is one thing I want to talk about. The "html-template folder" is really great at automatically copying over your externally loaded assets, but it's important to be careful when changing a project's settings. For instance, if you decided to alter anything in the HTML wrapper area in the ActionScript Compiler panel, Flex Builder will automatically delete the entire html-template (including your extra files) and create a brand new folder. You will know when this is about to happen when you see the following warning:


This is why I tend to set up my project settings before adding any folders to my project. This is a mistake I have made many times and unless your files are backed up, you may lose everything in your html-template folder. You have been warned!

Step 17: Working With The Default Class

Just as you would have a Doc Class when working in the Flash IDE, Flex Builder projects have a Default Application. Now we have finally set up Flex Builder and are ready to write some crazy amazing ActionScript in our new project. Let's open up the in our src folder and check it out.


Well there really isn't much going on here. Let's add a trace and see what happens. Make a new line in the constructor (after line 7) and type in the letters "tra" then hit control + space. Hopefully we have just triggered the code hinting and you see all of the possible matches for the letters "tra":


Yeah, I know, 17 steps to write a single trace statement...

Select trace() from the drop down menu and type out "Hello World" inside of it. Now we are ready to run our first application.

Step 18: Running A Project

In order to compile your application you are going to have to select a run. Runs are wizards that automate the process of running the Flex SDK compiler and what builds your application. Above the Flex Navigator tab, you will see a row of icons, look for the green play button and roll your mouse over that. You should see the following:


Press this and watch the magic happen!

If all went according to plan you should be looking at a blueish-green Flex style background and nothing happening. Well we can't see traces with the normal run, so let's move over to the debugger and see if anything happened.

Step 19: Debugging A Project

The debugger run is the bug looking button to the right of the play button. Press that and watch the amazing blue-green webpage come back again! This time I am not playing a joke on you. Close your browser's window and go back to Flex Builder. Under your main window a new tab should have opened up called "Console". Check the output:

Our trace works and now you know where traces show up. An important thing happened here; there is a big difference between the normal run and the debug run. If you remember earlier I suggested mapping Debug Last Launched to command + return. If you did that, try running the shortcut. The browser window should pop up and Hello World gets printed to the Console again. You can now rebuild your app at any time by using the shortcut.

Before we start wrapping up this tutorial I want to show you a few more things about the editor and the console window. Delete the trace and type in the following:

Now press control + space to pull up the code hinting and select the Timer as the variable's type. After you chose the Timer from the menu, Flex Builder automatically added the flash.utils.Timer class to the import list. Now let's continue typing out the following:

Two things should have happened. First you should have seen the code hinting menu show up with possible solutions as you tried to type out Timer. Next, if you didn't select it from the menu but instead stopped at "(" you should see the following code hint:


Flex Builder will not only show you the parameters a function will accept (remember even constructors are functions too) but it will do the same for all the custom classes you create. Cool right? Let's finish this up. As you type in the following keep playing with the code hinting and auto complete. Make sure you let Flex Builder do the heavy lifting and import your classes for you. If it gets confused and forgets to import them you can also move your cursor to the end of a Class, press control + space, select the name from the list, and Flex Builder will reattempt to import the class. It's not 100% perfect but it's better then having to remember exactly where everything is; welcome to the land of the lazy coder.

Here is the rest of the code:

Now save your file and see what happens. You should have an error on line 11. Take note on how the Editor shows you the error. A red X on the left, a red tick on the right of the line, and in your problems panel a description.


If you double-click on the error in the Problems panel it will take you to the line where the problem is. This is what we are seeing:

It looks like we forgot to create a function called "onTimer" for our event listener to call. We can fix that by adding in the following under line 12:

Now when you save, you should see a new type of error called a warning:


When you see a warning, it means that you can still build the application but something may need your attention. In this case we forgot to add ":void" to the end of our function. This should be a quick fix. Save and the warning will go away.

There is one last thing we want to do; every time this timer gets called we want it to increment. We will need to create a new variable for this class to store the loop value. Add the following above the constructor on line 8:

Now let's go to the onTimer function and create a new line above the trace statement on line 16. Before you start typing, let's see what happens when we press control + space.


It looks like we have a list of every single thing we can add in this class. If you look closely, you will notice that this list is comprised of properties and methods the class has access to. Let's shorten the list by typing in the first 3 letters of our variable, "cou". Now we should only have counter in the drop down. Notice how it has a red square icon on the left of its name. That tells us that we are dealing with a private variable. Green circles with white in the middle are public properties and solid green circles are public functions. We are going to put the following on lines 18-19 replacing our original trace statement.

We just need to add one last thing in the constructor under line 13:

Great, now we can run our app. Make sure you use the debug run to compile this time.

Note: Please read the next few lines so you know how to unlock your browser after running the code.

Hopefully you read this before running the above code so you should notice that the browser just locked up and Flex Builder change to a new Perspective; the Debug Perspective.


This new perspective is where we can debug our code. I will go into more detail in the next tutorial but check out what is going on. In the Debug tab at the top you have a stack trace showing all of the steps taken before the error. Below in the console you should see the following error:

Also, your browser is locked and waiting for you to make your next move in the Debugger. In the Debug tab you have controls that resemble an mp3 player:


Click the green play button and the same error will pop back up. Since the timer is still going and every time it fires the method it calls is missing a parameter, we will continue to get this error. Let's stop the debugger by clicking on the red stop icon. Flex Builder should give you back control of the browser and hopefully didn't crash it. The debugger is really touchy when it comes to certain browsers and may accidentally crash them when exiting debug mode. I tend not to keep anything important open in my browser when I do my coding so I don't lose it when the debugger causes it to crash.

We can fix our ActionScript problem by replacing line 17 with the following:

Now we can run our program (bug free I promise) and watch "Hello World" count up in the Console. This shows you that the Console is always running so you can continue to debug your application just like you would in Flash. As we go deeper into the Debugger you will start to appreciate how little you will rely on traces to help problem solve your issues.

Step 20: Checking In A Project

Now that we have working project let's talk about how we can check this into our newly created SVN repo on Google Code. Let's start by right clicking on our project and selecting Team > Share project from the contextual menu:


Now we need to pick a repository type, select SVN and click next:


We'll choose to create a new repository location, unless you have already set up your Google Code account you will need to set this new repo up. Enter in the url to your account, make sure you pick the "member" url and not the "user" one. Refer to step 10 for how to get this information.


You will also need the password, make sure you click on the password url to get your password. When you hit "next" you'll need to supply a path to save your project. In the second part of this tutorial I'll go over SVN organization and naming conventions, but for now just put the project in the truck of your repo.


In this case, I have selected "Use project name as folder name". The final path for you project will be your svn trunk url then your project's name. Press "next" to continue to the first commit window.


When you save anything to your SVN Repo you will be prompted to add a comment. When browsing your project's history you can see these comments for clues to what changes you made. It's important to be as descriptive as possible, especially in a team environment. It's also important to note that on Google Code, all of your comments are made public. Just a warning!

At this point you're going to be asked to accept a digital certificate from Google. Click "Accept Permanently" to continue.


Now enter in your user information to verify the account. Make sure you check "Save Password" or you will have to type in your password every time you commit a file.


Now you will be at the Synchronize perspective. Here you will get a breakdown of every file that needs to be committed. Notice the + icon on each of these folders? They let you know that these files have not been added to the SVN repo yet. When a file is being removed it will have a "-" icon. Updates to files are grey arrows and if the file is newer in the SVN repo, it will be a blue arrow facing left. Red arrows indicate there is a conflict that needs your attention.


Next select the .settings folder, the .actionScriptProperties and .project files. Right-click on them and select "Add to svn:ignore".


When working in a team environment it's very important to ignore these 3 items. Each person's Flex Builder may be configured differently, so by not checking in the hidden project files you can avoid conflicts created when each developer customizes their project. This is also a good example of how you can keep files from being version controlled. Marking a file for svn:ignore insures that it will never be added to the SVN repo when you do your commits.


As you can see, you have several options for how to ignore selected resources. We're just going to use the default option. It's also good to note that if you choose to ignore a folder, all of the items in the folder are ignored as well.

Now we are ready to commit our files. You can do this one by one, but by right-clicking on the project and choosing "Commit..." you will check in all of the files in that project.


When you commit files to the SVN repo you have to add a comment. Again, be as descriptive as you can.


Now your files are being checked in and everything is getting added to the repository.


Once that's over we have successfully checked in our first project. We have covered a lot of stuff here and you may need to practice these steps before you can commit them to memory.

In part 2 of this tutorial we'll finish our sandbox with a local server, talk about workflow, resource management, go in depth with the debugger/profiler, and build a better Hello World. Thanks for reading!

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.