Advertisement
Workflow

How to Use an External Library in Your Flash Projects

by

So you've been reading about an awesome Flash library, engine, or API, and you want to use it in your own project. You download it... but it's either some weird file you don't know how to use (a SWC), or a million folders of AS files -- nothing that says "double-click to install me". What the heck?

A library is just a collection of ActionScript classes that's been designed so that they're not tied to any one project, and can be used in anything you're building. These class files can be bundled into a single SWC file, which is like a zip.

I'll use Keith Peters's excellent MinimalComps as an example, because it's available in both SWC and folder format. The same applies to all AS3 libraries, APIs, and engines, though; some other great examples are Box2DFlash and the Greensock Tweening Platform.

Let's start by looking at what to do if you open the zip and are confronted by the raw class files:


A Million Folders of AS Files

Each AS file, as you know, contains a class (okay, it possibly contains several classes, or an interface, but work with me here). You need to be able to access these classes from your project, but you also need the classes to be able to access each other, as many of them will almost certainly inherit from or be composed of other classes in the library. This means you can't just grab a few of the classes, extract them to your project folder, and expect them to work.

Open one of the files, and take a look at the package declaration. For example, in the minimalcomps zip, in the file /src/com/bit101/components/Accordion.as, the package declaration is:

package com.bit101.components

See how this corresponds to the folder structure? /src/com/bit101/components/Accordion.as. (And the class in the file is called Accordion.)

It's not just Keith Peters being neat and tidy. When you type a line like:

import com.bit101.components.Accordion;

...Flash looks for a file called Accordion.as in the folder structure /com/bit101/components/. The package has to match the folder structure, so that Flash can find the file; if you moved Accordion.as to another folder, like /com/bit101/charts/, and tried to do:

import com.bit101.charts.Accordion;

...you'd get an error message:

5001: The name of package 'com.bit101.components' does not reflect the location of this file. 
Please change the package definition's name inside this file, or move the file.

Makes sense. So, the package of the class tells you which folder is the root folder of the library; it's the first word before the first dot in the package name -- com in this case. This means you should move the /com/ folder, and all of its sub-folders, to the main code directory of your project.


What is the Main Code Directory?

Tip: You'll often find that the root folder for the library is called /com/ or /net/ or /org/, because it's a common convention to use your domain name (in reverse) as the package structure. For instance, we're http://active.tutsplus.com so if we released a library, the package would start com.tutsplus.active. If everyone sticks to their own domain names, then there's no worry about anyone accidentally creating a library with the same package names as someone else's library. However, this isn't a universal convention; neither Box2D nor the Greensock libraries use it.

The main code directory is the term I use to refer to the folder where Flash looks for your AS files (and folders containing AS files).

If you're using Flash Professional, then, by default, this will be whichever folder your FLA is in. You can change this, however; see Daniel Apt's Quick Tip, How to Organize Your Flash Project Files, for more info.

If you're using another Flash editor then the folder could be called anything -- but there'll probably be a folder called /src/ or /source/ or /code/ or something similar, so you can figure it out. (If all else fails, just create a new AS file and look at what the default save location is.)

Try it out -- download MinimalComps, extract the zip, and copy the correct folder to your project's main code directory. Then, import com.bit101.components.Accordion; and create a new Accordion() somewhere in your project. If you don't see an error message, then you did it right!


Global Classpaths

What if you found a library so useful that you wanted it to be available to all your projects by default, without having to copy and paste the root folder to each new project's main code directory?

For this, you can use global classpaths. If you specify a folder on your hard drive as a global classpath, you're telling Flash to always look for classes there, as well as in the project's main code directory.

Let's suppose you create a directory C:\FlashLibraries\ (Mac Users: think Macintosh HD / FlashLibraries instead), with a subdirectory MinimalComps, and copy the /com/ folder from the MinimalComps zip to this MinimalComps directory. The Accordion class file would be at C:\FlashLibraries\MinimalComps\com\bit101\components\Accordion.as. You could then set C:\FlashLibraries\MinimalComps\ as a global classpath, and from then on, every Flash project you opened would be able to run:

import com.bit101.components.Accordion;

...without any problems. And since Flash only compiles classes that are actually used in your project, it won't pad out your SWF with the libraries in your global classpath that you don't use.

You could even extract all the root code classes of all of your libraries to the same global classpath -- i.e., you could set C:\FlashLibraries\ as a global classpath, and then copy the /com/ folder from the MinimalComps to this folder, so the Accordion class would be at C:\FlashLibraries\com\bit101\components\Accordion.as. (This is probably not worth the effort, though; if you downloaded our imaginary Activetuts+ library, it'd sit in C:\FlashLibraries\com\tutsplus\active\, which means that the /com/ folder would contain both a /bit101/ folder and a /tutsplus/ folder. That's not a problem, but it does get messy, and can make it very difficult to delete a single library later on.)


How to Set a Global Classpath

In Flash CS3, click Edit | Preferences, then click the ActionScript category, and select ActionScript 3.0 Settings. You'll see a list of folders. Click the Plus sign to add a new one; you can type the location in, or press the target to browse to it.

In later versions of Flash Professional, there's a little more to it. Click Edit | Preferences, then choose the ActionScript category and click ActionScript 3.0 Settings as before. The entry form is a little different:

This time, use the Source path section to set the global classpaths. Use the Plus sign to add a new entry, and the folder icon to browse to the folder.

If you use a different development environment, the global classpath settings will be somewhere else. For example, in FlashDevelop, select Project | Properties, then the Classpaths tab, and click Edit Global Classpaths....


Project or Document-Level Classpaths

What do you do if the developer of the library releases a new version? You might download it to a global classpath, overwriting the previous version, and start using it in your latest project. But then if you open one of your older projects -- one which used the previous version of the library -- you'll run into all sorts of incompatibility problems.

You could solve this by having one folder for each version of the library: C:\FlashLibraries\MinimalComps\v1\, C:\FlashLibraries\MinimalComps\v2\, C:\FlashLibraries\MinimalComps\v2.5\, C:\FlashLibraries\MinimalComps\v3\, ... and so on. Then, whenever you opened a project, you'd create a new global classpath as the folder for to the version of the library that your project needs, and delete all the others.

That works, but it's a horrible workflow. Instead, you can set a classpath that's specific to one project.


How to Set a Project or Document-Level Classpath

In Flash Professional CS3 and above, once you've opened a FLA, click File | Publish Settings, then select the Flash tab, and click Settings next to ActionScript 3.0. In Flash CS3, the dialog looks like this:

Just as when setting a global classpath, you can use the Plus button to add a new entry, and the Target icon to browse to a folder. In later versions of Flash, the dialog has more to it:

Don't worry about the other tabs; just use the Source path tab to add your desired classpath.

Again, different development environments will store this settings in different places. To add a project classpath in FlashDevelop, select Project | Properties, then the Classpaths tab, and click Add Classpath....


Relative Paths

Imagine you're building a Flash game which has slightly different versions for different game portals and a separate level editor. Your folder structure might look like this:

C:\MyAwesomeGame\game_core\
C:\MyAwesomeGame\game_kongregate\
C:\MyAwesomeGame\game_newgrounds\
C:\MyAwesomeGame\levelEditor\

Now suppose you want to use MinimalComps in all versions of your game, and in your level editor -- not just any old version of MinimalComps, but specifically the latest version, in each project. Meanwhile, you have another project which is written with an old version of MinimalComps, so you don't want to use a global classpath.

You can create a new folder inside your base game folder:

C:\MyAwesomeGame\libraries\

...and then copy the root folder of the library directly to it, so the Accordion class would be at C:\MyAwesomeGame\libraries\com\bit101\components\Accordion.as.

Now, you know that you can set a project or document-level classpath in each of the different game versions, and the level editor, to point to C:\MyAwesomeGame\libraries\, but what if you need to share all of the game files with someone else -- perhaps a whole team? They'll either have to make sure their folder structure matches yours exactly, or go through each of the projects and alter the classpaths to match their computer, every time they get the latest version. What a pain!

Instead, you can use a relative classpath. Assuming the main code directory of the level editor is /levelEditor/, then if you set a classpath of ../libraries/ it will look in the correct folder. Why? Because ../ means "the directory above the current one".

This means that you can use ../libraries/ for all versions of your game, and they'll all point to the same directory. And then, when you share the code with your team mates, you can give them the entire /MyAwesomeGame/ folder and it will contain everything they need. There's less for you to remember to do -- no need to change the classpaths or copy each new version of the library to the various different folders -- and so there's much less chance of making a simple error. Great!

(You could take this even further and put all of the code that the various different versions of the game share in the folder C:\MyAwesomeGame\shared\... but that's getting away from the topic of this article!)

You can nest the special ../ directory, too: ../../ goes up two directories instead of just one, and so on. You can also use ./ to refer to "the current directory".


SWC Files

Like I said, a SWC file is basically a zip file containing ActionScript classes and other such data. For instance, in my FlashDevelop guide I explained how to export library assets, created in Flash Professional, as a SWC so that they could be used in another workflow. It's possible to do the same with purely code-based classes.

I won't explain how to create such a SWC here, but I'll explain the two main benefits for developers of libraries:

  1. The entire library (including graphical assets) can be contained in a single file.
  2. The contents of the individual classes (i.e. the AS files) cannot be viewed or modified.

You still have the choice of using the SWC library in a single project, in all your projects, or shared between a few of them, though the means for including them in your projects are slightly different than when you have the actual class files.


Using SWC Libraries in Your Projects

Flash Professional CS3 has some major restrictions when it comes to using SWC libraries: it can't use SWCs that are merely a collection of class files. If the SWC contains components, you can move it to your /Components/ directory on your hard drive, and then (within Flash) drag it from the Components panel to your library or stage. This directory is at C:\Program Files\Adobe\Adobe Flash CS3\{language}\Configuration\Components\ by default in Windows, and Macintosh HD / Applications / Adobe Flash CS3 / Configuration / Components by default on Mac OS X.

You can copy SWC components to the equivalent folders in Flash Professional CS4+ if you want to access them through the Components panel. For SWCs that are made up of code classes you can also set them as a global classpath or a document or project-level classpath.

To set a global classpath, click Edit | Preferences, then choose the ActionScript category and click ActionScript 3.0 Settings as before. You'll see this dialog:

Add the locations of your SWCs to the Library path. As the dialog suggests, you can put several SWCs in the same folder and just point to that folder.

(The External library path box can be used to specify SWC libraries that should be loaded at runtime, rather than when the component is compiled. If you've got huge amounts of code and assets shared between your projects, you can reduce the loading time for your users by putting all the shared resources in a SWC file and using it as an external library; users will then only have to download it once and will then be able to use it in each of your other projects. This is probably not what you want to do with libraries you've downloaded, though!)

To set a document-level SWC in Flash Pro CS4 and above, once you've opened a FLA, click File | Publish Settings, then select the Flash tab, and click Settings next to ActionScript 3.0. Switch to the Library path tab. The dialog looks like this:

You can use relative paths here, just like when you've got the individual class files.

Different development environments will have different ways to import SWCs. For info on using SWCs in FlashDevelop, see my guide.

I hope that helps! Now, when a tutorial says, "download this library", you should know exactly what to do :) Let me know if anything's unclear and I'll clarify it for you.

Related Posts
  • Code
    Android SDK
    Integrating Google Play Services on Android85ude preview image@2x
    By integrating your Android apps with Google Play Services, you can access Google services, such as Maps, Drive, and Google+. In this tutorial, we will go through the process of integrating Google Play Services with Android apps.Read More…
  • Code
    Web Development
    Using Polymer to Create Web ComponentsPolymer wide retina preview
    Polymer will help you to easily create Web Components for your web apps, using a similar syntax to HTML.Read More…
  • Computer Skills
    Electronics
    Building a Wireless Sensor Network in Your HomeSensors
    Your environment is full of all sorts of fun and useful data, but getting it all together can be a challenge. In this tutorial you will learn how to use Arduino and Raspberry Pi technology to create inexpensive, wireless sensor nodes that report their data back to the Internet of Things. Read More…
  • Computer Skills
    App Training
    Alfred Workflows for IntermediatesAlfred400
    Welcome back! Since you are reading this, you must have enjoyed the beginner's tutorial. Great! Now, let’s dig a little deeper by making a workflow that will help manage our Downloads folder, as well as a Projects Manager.Read More…
  • Code
    Creative Coding
    Creating a TextMate Bundle to Easily Package Your WordPress ProjectTextmate bundle 400
    If you've developed a WordPress theme or plugin, then you know how fast your codebase can grow in just a short amount of time. You start off with just a few PHP, JavaScript and CSS files. Then you find yourself creating image assets and adding them to your codebase together with their Photoshop file counterparts. After a while you'll be including other third-party PHP libraries as well. Then when you're finally ready to ship your WordPress project, you'll end up having a web of multiple file types like *.php, *.css, *.scss, *.js, *.min.js, *.png and *.psd, maybe you'll have some hidden files like .DS_Store. You would eventually need to clean your codebase up before zipping them all up for your users. Normally, this just means that you duplicate your files, then scan each and every directory deleting all the unwanted files. You'd then archive your project then perhaps use a third party app to remove the hidden files. This article will teach you on how to automate this packaging process by building a TextMate Bundle that would do everything for us with a single shortcut key. [tip]This article teaches about some tips regarding TextMate, an awesome code editor for Macs. You can find more information on TextMate from MacroMate's website[/tip]Read More…
  • Code
    iOS SDK
    Objective-C Succinctly: Introduction0e5ds8 preview image@2x
    Objective-C is the programming language behind native Apple applications. The language was originally designed in the 1980s as a way to add object-oriented capabilities to the ANSI C programming language, and it has since been used to create everything from command-line tools to Mac programs to mobile apps. You can think of Objective-C as Apple's version of the C# programming language.Read More…