Developing an effective Fireworks workflow

Adobe Fireworks CS3 includes a rich extensibility model that allows advanced users to create sophisticated custom panels (Flash panels) using a combination of JavaScript and Adobe Flash. In fact, many of the panels that ship with Fireworks—including the Align panel and the new Path panel—are Flash panels. Because the Fireworks engineering team has exposed practically every aspect of Fireworks through a JavaScript extensibility model, you're really only limited by your imagination (and technical abilities, of course).

This article is designed to give you an understanding of the entire Flash panel development process by presenting a workflow I refined through developing the Fireworks to XAML Exporter. I show you how JavaScript and Flash work together to call native Fireworks methods and guide you through the creation of a simple custom panel. By the end of this article you should see "the big picture" of this process and be ready to take a deep dive into the Extending Fireworks documentation.

Establishing a development workflow can make the process of coding, testing, and deployment an enjoyable experience. The steps I show you separate the code from the UI as much as possible. I expand upon the following process in detail in the sections that follow:

1. Create the JSF command file.
2. Create the Flash UI.
3. Import the JSF command text into Flash.
4. Execute JSF commands in Flash using MMExecute().
5. Export the Flash SWF and test it within Fireworks.

Creating a simple command

Let's start by creating a simple JSF command. We can do this by performing a few actions within Fireworks and then saving the steps displayed in the History panel (select Windows > History) as a command:

1. Draw a rectangle on the Stage and change its fill color.
2. Select the steps you just performed in the History panel then click the Save icon.
3. When prompted for a command name, enter Draw Rect (see Figure 1).

You should now see the command you just saved listed in the main toolbar's Commands menu. Try deleting your rectangle and executing the command you just created (select Commands > Draw Rect). If you saved the correct steps in your History panel, a new rectangle should appear with the same specifications as the one you previously created.

What just happened?

Fireworks created a new JSF (JavaScript Fireworks) file and saved it to a special directory on your hard drive. The file contains JavaScript code that performs the actions you selected in the History panel. Fireworks sees this new file and displays it in the list of commands in the Commands menu. When you select the command from the menu, the JavaScript within this file is interpreted by Fireworks. This behavior should be familiar to anyone who has created a macro in a program like Microsoft Word.

Where is the command stored?

Fireworks commands that are saved from the History panel are stored in your user profile folder:

(Windows) C:\Documents and Settings\<User Name>\Application Data\Macromedia\Fireworks 8\Commands

(Mac OS) Macintosh HD:Users:<User>:Library:Application Support:Macromedia:Fireworks 8:Commands

Fireworks commands that are accessible to all users are stored in the following location:

(Windows) C:\Program Files\Macromedia\Fireworks 8\Configuration\Commands

(Mac OS) Macintosh HD:Applications:Macromedia:Fireworks 8:Configuration:Commands

Likewise, command panels are stored in similar locations:

(Windows) C:\Documents and Settings\<User Name>\Application Data\Macromedia\Fireworks 8\Command Panels

(Mac OS) Macintosh HD:Users:<User>:Library:Application Support:Macromedia:Fireworks 8:Command Panels

and here:

(Windows) C:\Program Files\Macromedia\Fireworks 8\Configuration\Command Panels

(Mac OS) Macintosh HD:Applications:Macromedia:Fireworks 8:Configuration:Command Panels

Editing and understanding the JSF

Browse to your Commands folder and open the file you just created using your text editor of choice. (The lightweight Notepad++ is a great choice that provides syntax highlighting.) If you followed the earlier steps and created a new rectangle, you should see something similar to the following code:

The first line calls the addNewRectanglePrimitive method of the Fireworks Document Object Model (DOM) and passes two parameters, a Rectangle object and a corner roundness value:

The second line calls the setFillColor method and passes a hexadecimal color value. The setFillColor method, like most available methods, performs operations on the currently selected element(s) on the Stage. Because a new rectangle was just created, that same rectangle is now selected and the setFillColor method behaves as expected.

Experiment with the values passed to addNewRectanglePrimitive and setFillColor, save Draw Rect.jsf and rerun the command within Fireworks. You have now performed an action that you will perform countless times if you proceed with Fireworks extension development.

Now that you know the JavaScript works within Fireworks, you can create a command panel in the Flash authoring environment that executes the same JSF code you just created in Fireworks.

It's a good practice to determine that the JSF works in Fireworks before trying to execute it from within Flash; otherwise, when a problem occurs, you won't know whether the source of the error is the JSF itself or an error with your Flash panel. If you had hand-coded instead of saving directly from the History panel, for instance, you would have been able to identify problems with the code immediately.

Creating a document and adding a button

Start by creating a new Flash document. Set the document width to 250px and the height to 300px. Add a Button component to the Stage and give it an instance name of executeJSF_btn. Set its Label property to Execute JSF.

Importing and executing JSF

Flash panels execute JavaScript via the MMExecute() command in ActionScript. When an exported SWF is run inside Fireworks as a Flash panel, MMExecute() passes the JavaScript directly to Fireworks. Fireworks executes the JavaScript and returns the resulting value to Flash (if any):

The JavaScript passed to MMExecute() is passed as a string, which means you must escape quotation marks and potentially double-escape text that has already been escaped in JavaScript strings. That sounds more confusing than it actually is. The example below executes the setFillColor() line of code in Flash using MMExecute():

Notice that the entire string is wrapped with quotation marks and the inner quotes surrounding #99cc33 have been escaped: \"#99cc33\". For single lines of JavaScript, this method of execution works well. As your JavaScript grows in complexity, however, escaping large sequences of code becomes laborious and introduces the potential for error.

Save yourself a headache by creating a new TextField on the Stage. Change its text type to Dynamic Text and give it an instance name of jsfCode_txt (see Figure 2).

Move this TextField off the Stage so that it is not visible at runtime, and then copy and paste the contents of the Draw Rect command directly into this TextField. The Fireworks JavaScript is now available to you directly within the Flash document; you don't have to worry about escaping quotes or other characters.

Adding the onRelease event handler

Now add the necessary ActionScript to execute the Fireworks JavaScript when executeJSF_btn is clicked:

1. Create a new layer in the Timeline.
2. Change the layer name to actions.
3. Lock the layer.
4. Open the Actions panel and add the following code to frame 1 of the Actions layer:

Publishing and testing the SWF

In order to test your new Command panel, export the Flash file as a SWF to your Fireworks "Command Panels" folder (location mentioned in the earlier section, "Creating a Simple Command"). Export your current file as Draw Rect.swf. Because this is the first time you are exporting the file, you will have to restart Fireworks in order to see the new Command panel in the Window menu of Fireworks. For subsequent exports, you can just close the panel in Fireworks and reopen it to see your latest version.

Once you've restarted Fireworks, open the new panel from the main menu: Window > Draw Rect. You should now see your Execute JSF button in a new panel. With a new or existing document open, click the button. A new rectangle should appear on the Stage, just as it does when you select Draw Rect from the Commands menu.

Congratulations! You've now created your first custom Flash panel for Fireworks!

Tip: Change the output path for your SWF file in File > Publish Settings to the Command Panels folder. Use Alt+F+B to quickly publish, all from the comfort of your keyboard.

This simple example illustrates an effective workflow for developing Flash panels. You started by creating a JSF command and testing that command within Fireworks. When you knew it was performing as expected, you copied the JSF into a Flash TextField. You then added code to execute the JSF when a button was clicked within Flash.

Now that we've covered the basics, let's dig a little deeper into the process and look at ways you can refine and enhance your workflow.

The Fireworks Developer Toolbox (FDT) is a simple application I created while working on the Fireworks to XAML Exporter (see Figure 3). It reduces the repetitive steps in the development cycle and simplifies the translation from JSF command to Flash panel. The FDT performs two functions:

• JSF file synchronization
• JSF file conversion to an AS file in the form of a single variable

You may be wondering why those two functions even need to be performed. What files need to be synchronized and why should JSF be converted to Actionscript?

Synchronizing files

In larger projects, it's a good idea to use a source control application. This lets you track changes as they are made and helps to prevent accidental code loss. I have a folder dedicated to the current version that I am working on that contains the JSF source file, the Flash panel FLA, and any additional assets required by the FLA, such as source images and ActionScript files.

Rather than edit the JSF file located in my project folder and then copy/paste that file into the Commands folder for testing, I use FDT to synchronize the two files. FDT watches for changes made to my main JSF file and then automatically copies the file to the Commands folder when I save the changes. I can then immediately test the updated command in Fireworks.

I use a third-party tool to optimize the JavaScript before converting it to ActionScript. This tool requires that my file have a .js extension instead of the .jsf extension recognized by Fireworks. Because FDT can copy to multiple files, I can keep this .js file in sync with the other two files with no additional work required on my part.

Converting to ActionScript

In the earlier section, "Creating a Flash UI," JavaScript was copied directly into a Flash TextField for execution using MMExecute(). While this works really well and eliminates the need to escape the text manually with backslashes, it ultimately becomes a laborious step and introduces the potential for human error.

The TextField approach can be eliminated entirely and replaced with a more elegant solution. FDT converts a specified JSF file into an ActionScript file that can be included in Flash using #include (see Figure 4). FDT escapes the contents of the JSF file and assigns that content to a single variable name you specify.

Modifying the previous Flash example to take advantage of this updated workflow requires only two steps:

1. Add #include "jsfCodeFileName.as" to your actions layer.
2. Change the variable name passed to MMExecute() to that specified in FDT: MMExecute(jsfCode);

Additionally, FDT enables you to specify whether or not ActionScript should be generated automatically after file synchronization, saving yet another manual step.

Using FDT, you can edit your main JavaScript source file, save it, jump to Fireworks, test that the changes you made work correctly, and then jump to Flash and republish it (Alt+F+B, remember?). Then return to Fireworks, close and reopen your panel, and test your updated file. After you've done this a couple of times, you'll be flying through the process.

When you begin creating Fireworks extensions, you spend a large percentage of your time learning and deciphering the Fireworks Object Model. You do this by reading through the Extending Fireworks documentation; examining the source files of existing panels; reading articles, blogs, and forum postings; and experimenting with your own JSF. The first tool I list in this section, the FWAPI_Inspector panel, removes a lot of the guesswork from the learning phase by displaying the properties of selected items as a tree of elements in a Fireworks panel.

The second tool listed, the Infragistics Alignment Manager, speeds the second phase of development: creating your Flash user interface. You can quickly define how items are positioned and scaled as your panel is resized—something you must take into account when creating custom panels for Fireworks.

FWAPI_Inspector panel

The Fireworks to XAML Exporter is a panel whose function is quite large in scope. It recurses through the entire tree of elements and translates those elements and their properties to the corresponding XAML equivalents. Being able to quickly see an element's property tree drastically reduces the amount of time spent reading through the Extending Fireworks documentation.

Fortunately, Aaron Beall has written a panel that displays the property tree of the currently selected element on the Stage (see Figure 5). You can see the values for each property and even edit the properties that aren't read-only. The source for this panel is included in the ZIP file accompanying this article. You can also download the latest version of the SWF from Aaron directly.

Infragistics Alignment Manager

When creating Fireworks panels, you must be aware that the user can resize the panel, just like any other panel you encounter in Fireworks. If you have elements hidden off the Stage, they may be exposed when the panel is resized. You can take care of this problem by adding the following ActionScript to frame 1 of the Actions layer in your movie's main Timeline:

The first property tells Flash not to scale/stretch its content when resized; the second property tells Flash to anchor its content to the top left (TL) corner of the Flash Player window.

For more complex scenarios where you want certain elements to stretch when scaled and other elements not to stretch or to float in some particular way, you could manually handle the Stage.onResize event and perform the necessary calculations yourself, or you could use the freely available Alignment Manager from Infragistics (design.infragistics.com to download). This Flash extension does all the alignment work for you; it lets you set horizontal and vertical alignment properties and assign margins as well (see Figure 6).

Where to go from here

You should now have an understanding of an effective Fireworks extension development process and have some new tools in your arsenal to enhance the process. Dig into the Extending Fireworks documentation (accessible within Fireworks by selecting Help > Extending Fireworks) to get a better understanding of what you can achieve with JavaScript, Flash, and Fireworks. (Hint: it's a lot!)

There are additional articles in the Developer Center and elsewhere that dive deeper into the Fireworks DOM and specific panel scenarios. Start with some of the articles listed below and then continue your quest by browsing the Fireworks Developer Center:

• Creating Fireworks Panels – Part 1
• Creating Fireworks Panels – Part 2
• FireworksGuru Forum