archives | wasted potential

Writing a JSFL component for Flash AS3

On March 8, 2011

In case you don’t know, JSFL is a javascript library used to create components for the Flash IDE. So, if you have repetitive tasks that you want to automate, you can create a component that does it for you. Once you have your component debugged, you can actually package it and distribute it as an MXP file for others to use. For example, one of my favorite components is the Preloader Shuffle component that I used to use back in my AS2 days (it seems to be unavailable now). I recently made a component to Rename a class package throughout all the files in a project. It’s essentially a glorified find-and-replace script for multiple FLA and Actionscript files. You can get it here.

I never needed to write a custom component until recently. At work, I have a generic Flash AS3 application that works as a good starting point for new projects. It usually needs pretty heavy modification, but having a simple setup with the preloader, flashvars, error tracking, analytics, and basic pages already set up saves hours of coding on each new Flash project. The one downside is that I have placed all of the classes in a package called “com.sampleclient.” So, I have to rename this class package in all of the Actionscript class files and update all of the linkages in the FLAs. This takes about 20 minutes each time. So, I decided to write a JSFL component to do all of this renaming for me.

Well, the reality of JSFL is that it’s one of the many poorly documented features of Flash. So, actually creating this component took a lot longer than I expected. I’m posting this in the hope that it might save someone else a little time. The finished MXP component is available here. All of the source files that I used to create it are here. Here are a few tips for you if you are thinking of going down this rabbit-hole:

You will need some links to help you get started. I probably referenced a few dozen different blogs and forums to get this component working, but here are a few of the most helpful links I found:

An indispensible tutorial on creating and packaging an MXP component can be found here.
Most components will need the FLfile object. Here is a good reference for it.
The comprehensive API specification for JSFL is here (warning: this is a large PDF file).

There are some more links at the bottom of this post that I found helpful.

It’s only worth the trouble to create a component if you really plan to use it a lot. I would estimate that it took me over 12 hours to get this component working the way I wanted. So, I will have to use it on at least 36 projects before it starts to actually pay my time back. Most of this development time was spent on the JSFL learning curve. It’s not as simple as it looks.

JSFL is poorly documented, so you will spent a lot of your development time trying to figure out what to type into Google to get the information you need. First, you’ll spend 20 minutes or so trying to get the name of a command that does what you want. Only then can you actually figure out how to make that command work. The links in this post can help you in your snipe hunt.

You have to get creative. For my component, it was crashing if I tried to run it without opening an FLA file. It needed an open FLA file to get the Document DOM. My solution was to have the component open a blank FLA file when it started so it would have a valid DOM. It seems obvious now, but it took me a while to figure that out.

There are some things that you just can’t do. My component opens every FLA file within a given folder and searches it for a class package name. Then it saves and closes the file. But what if that file is already open in the IDE? Is there any way to leave that file open? Nope. The JSFL component has no way of knowing that the file was already open, so I just have to close all FLAs when I’m finished with them.

Other people’s code is EXTREMELY helpful. That’s why I’m posting my source code here. Feel free to pick it apart and learn from it. Just don’t put your name on it and pass it off as your own work please. If you can make improvements to this, I will be happy to update the component and give you full credit. This component does have one bug that I know about: After moving all of the actionscript files to the new class package folder, it should delete the old folder, but it doesn’t. I don’t know why.

Anyway, good luck! If you have any useful components that you have built, feel free to send them my way.

In case you missed it, you can download the source files here.

Flash AS3: Rename Class Package component (MXP)

By Andy

On February 2, 2011

In Actionscript/AS3, Flash

I recently had a need for a Flash tool that would search through all of the files in a project and rename a class package reference everywhere that it showed up. The reason is simple: I have a generic Flash project that I use as a starting point for all of my Flash builds. It has a lot of basic features built in, such as error handling, preloading, analytics, basic page and navigation setup, etc. It saves me several hours of coding on each new Flash project. The only downside is that all of the AS3 class files are in a package called “com.sampleclient.” So, I spend about 20 minutes renaming this class package reference in the FLAs and the Actionscript files every time I start a new project.

Well, I created a handy component to automate the process and I thought I’d give it away for other people to use. Simply download and install the MXP file found here. Once you’ve done that and restarted Flash, you will see a new entry in your Commands menu cleverly called “Rename Class Package.” Click it and it will open the following dialog box:

Enter the old package name (the one you want to rename) and the new package name (the new name you want it to have). Uncheck the box if you want it to prompt you each time it tries to save changes to an FLA file. Click OK and a file browser dialog will open:

Simply find the folder that contains your project. You want the folder you choose to contain both the FLAs and the Actionscript class files. It then gives you a final double-check dialog:

I added this because I found myself clicking through without paying attention and specifying my entire C: drive as the project folder. So, this is one last verification to prevent that sort of thing.

It then recursively searches all files in that folder (and all of its subfolders). It does a find-and-replace for that package name in all actionscript files. It also moves all of the files in the old package to a new folder that reflects the new package name. Then it opens all FLAs and updates all linkages, base classes and document classes. Please note that it does NOT search timeline code for references to a class package. You shouldn’t be putting anything like that on the timeline anyway.

Once it has finished, it lets you know which files were updated (in case you’re interested):

It also ignores Subversion folders in the project folder. So, if you use Subversion for your flash projects, it should play nice. The current version of this component does not work with the XFL format, however. Sorry. I tried adding that functionality,but the script ran out of memory and crashed every time. I think it choked on all of the extra files and folders that are created by an XFL file.

This component does have one bug. After moving all of the Actionscript files to the new package folder, it should delete the old package folder, but it doesn’t. I don’t know why, but if I figure it out, I’ll update the component.

Hopefully, this will save you some time as well. If you want more details on how I built this, I will be posting info and source files soon. If you have any feedback for me, leave it in the comments. Thanks.

Flash CS5: TLF textfield bugs (or TLF WTF?)

By Andy

On January 4, 2011

In Actionscript/AS3, Flash

So, I just upgraded to Flash CS5 and I have to say that it sucks slightly less than CS4. The IDE layout changes are for the better (unlike CS4) and it *seems* faster. But, I ran into a weird bug with one of the new features in Flash CS5: The new TLF textfield causes problems with externally loaded SWFs.

Here’s the scenario: I have a main SWF that loads another SWF at runtime. I’m using some code that I cut-and-pasted from another project to load the SWF, so I know it works. But, in my new CS5 project, it throws runtime errors whenever I try to access a public function of the loaded SWF. It can’t access any of the public methods and it keeps telling me they don’t exist. I try loading a different SWF and no problems. Huh?

In my debugging, I also noticed that when I traced the numChildren of my loaded SWF, it was wrong. It said I had 2 children when I could see that there were 4. I added another one to the timeline. It still said there were 2 children. Even weirder is that when I traced these 2 children, Flash told me that one of them was a Loader (it wasn’t). Again, I tried the same test on another SWF and it was ok.

The problem turned out to be 2 textfields that were in my loaded SWF. Flash CS5 set them as TLF Text when I created them. This is apparently the new default. The TLF text fields were breaking my loaded SWF. If I removed them, everything went back to normal. I changed the textfields from TLF Text to Classic Text and everything worked. I probably spent over an hour tracking this down.

Once I figured out what was causing the issue, I did some Googling and found this:
Flash CS5 TLF Engine Causes Errors With Loaded SWFs.

Anyway, this is a long winded way of saying be careful about using the TLF Text in Flash CS5. Oh, and…
Adobe, you suck.

Flash AS3: Stop using “Automatically Declare Stage Instances”

By Andy

On December 27, 2010

In Actionscript/AS3, Flash

If you are compiling in the Flash IDE, you need to turn OFF the “Automatically Declare Stage Instances” option. It’s simple to do… go to File>Publish Settings, then click on the “Flash” tab and click the “Settings” button next to the Actionscript 3.0 dropdown. Simply uncheck the box and you’re done. It’s a crutch that is turned on by default in Flash and using it is a bad idea. Here are 4 quick reasons not to use it:

No more mystery variables in your classes. If you ever have to hand off your work to someone else, it’s really helpful to have all stage instances declared in your classes:
```
public var foo_mc:MovieClip //foo_mc is a stage instance
```
It’s just a courtesy to other developers who might have to deal with your code.
It fixes SOME inheritance problems. Flash is a little funny about class inheritance and it sometimes chokes on things that seem like they should be valid subclassing to me. But, I have found that I have a lot less trouble with it since I started explicitly declaring all stage instances.
Your code will integrate better with a Flex environment. I don’t use Flex (now FlashBuilder) much, but I do sometimes build fancy schmancy animated components for use with Flex. You have to declare all stage instances in your class variable declarations for this to work. You might never have to deal with this, but why not create a workflow that is more portable?
ASDocs requires it. If you want to create documentation for your classes using ASDocs, you must have all of your stage instances declared. Otherwise, it throws an error on each one that you didn’t declare.

I’m sure there are even more reasons than this, but those are the ones that I’ve found. Leaving “Automatically Declare Stage Instances” turned on is lazy, so knock it off.