Fireworks

Keep a Fireworks JavaScript Reference Handy
Many Fireworks commands go beyond what you can retrieve from the History panel. When you create custom scripts, it is always a good idea to keep the Extending Fireworks documentation open and available for quick reference (available from the Help menu in Fireworks 8). Chances are good that you will need it - and need it often.

I suggest downloading the PDF version (ZIP, 1.2 MB) instead of the Help system. I find that searching within the PDF is more accurate than searching through Help. Plus you get to have every page open and easily accessible, unlike the segmented Help system. Be sure to keep up with the Fireworks 8 LiveDocs for any corrections and suggestions made by other Fireworks users.

Reuse Your Scripts
When you work with Fireworks scripts, you may find that some scripts come in use over and over again. Keep a repository of these scripts so that you can easily reuse them if needed. If you are using Dreamweaver to write your scripts, make use of Dreamweaver's code snippets feature. For more information about the Snippets feature in Dreamweaver, see Working with Code Snippets in the Dreamweaver LiveDocs.

Publish Your Panel SWF Directly to the Command Panels Folder
By default Flash publishes a SWF in the same folder that the FLA is located. For Fireworks to recognize a SWF as a panel, however, it needs to exist within the Command Panels folder located in the Fireworks installation folder. To avoid the hassle of manually putting it there yourself, you can instruct Flash to publish the SWF directly to that folder. There are two ways to do this:

• Save your panel FLA within the Command Panels folder so that each time the SWF is published, it is automatically published to that folder as well.
• Recommended: Save your panel FLA wherever you want but adjust your FLA's publish settings (in Flash choose File > Publish Settings) by selecting the Command Panels folder as the destination folder for your published SWF (see Figure 7).

Because Fireworks requires a panel SWF to reside in the Command Panels folder during startup, it's a good idea to publish your SWF immediately after creating your FLA, followed by a restart of Fireworks. That will make Fireworks recognize your SWF as a panel immediately. Then you can republish your SWF as needed to update that panel. Each time you publish, all you need to do is close and reopen the panel to reload the newest version of the SWF used by that panel.

Note: There are two ways to get rid of a panel in Fireworks: closing it and hiding it. When you reopen a panel, if it was hidden, it will not reload the SWF. The SWF is only reloaded if the panel is reopened after having been closed. To close a panel you must either right-click its title bar and select Close Panel Group or click the close button available to the panel when it's undocked. Hiding a panel happens when you reselect the panel name in the Windows menu when it is already opened. For undocked panels, hiding a panel in this manner makes it appear as though the panel were closed.

Test Incrementally
If you are dealing with a fairly complex panel - or one including many operations or options - it will be helpful to test each part of the panel separately. This lets you isolate problems as they occur and helps you deal with them more effectively. Attempting to debug a panel when you don't know what's causing the problem is much more aggravating.

Debugging Fireworks Commands
Flash has quite a few tools to help developers debug panels specifically designed for it. Fireworks, on the other hand, has nothing of the sort. In fact, if you're lucky Fireworks will probably tell you simply that an error occurred by issuing an alert. This can make Fireworks scripts quite difficult to debug.

There's a two-step process involved when Fireworks receives a Fireworks JavaScript command. First it evaluates the script and then it executes the script. A problem can occur at either step - and either step can produce an error alert. Such alerts, however, will not always be invoked if the script is run from within a Flash panel - a reason why testing outside of the panels themselves can be beneficial.

When Fireworks encounters a problem with evaluation, no script will be executed and an error will be immediately issued. This usually means there's been a syntax error such as mismatched brackets ( {} ) or a misuse of operators. There will be no indication of where the error occurs. It will be left up to you to find out where that is (see Figure 8). More advanced external script editors like Dreamweaver 8 should help you find such errors, thanks to features such as color coding. The following example will create an error in Fireworks due to an error in script evaluation:

function copy () {
    fw.getDocumentDOM().clipCopy();

copy();

The problem with the above script is that the copy function block was not closed with an ending bracket ( } ). As a result, Fireworks kills the command and issues an error before anything even gets to be executed.

Getting a script to evaluate correctly is half the battle. An error can still occur if there is a problem with execution. If that happens, Fireworks will issue an alert directly after reaching the problematic code. Problems in execution usually result from attempting to use a variable or function that does not exist or calling a native Fireworks method with incorrect arguments. The following example will create an error in Fireworks due to an error in script execution:

function copy () {
    fw.getDocumentDOM().clipCopy(); } copie();

Now the copy function is correctly defined here but when it is called at the bottom of the script, it's misspelled. Because the copie function doesn't actually exist, there is an error when Fireworks attempts to call it, which kills the script and issues the error alert.

Although the error message for both the previous examples is the same ("Could not run the script. An error occurred."), there is a slight advantage in dealing with errors resulting from execution. That advantage is the simple fact that code prior to the faulty code is correctly executed before Fireworks issues the error. This allows you to find out at least how far a script has gone before reaching bad code, or even if it manages to execute any code at all. The most common indicator is a simple JavaScript alert. Consider the following script:

alert("Defining copy function");
function copy () {
    fw.getDocumentDOM().clipCopy(); }
    alert("Calling copy function");
    copie(); alert("Script Complete");

When you run this script in Fireworks, you get three alert messages, "Defining copy function," "Calling copy function," and the inevitable error, "Could not run the script. An error occurred." The fact that "Defining copy function" is alerted tells you immediately that the script was evaluated correctly and that there are no errors with the syntax. Seeing "Calling copy function" tells you that copy was defined correctly and that it is about to be called within the script. Given that the error message is seen instead of the "Script Complete" alert indicates that there was something wrong with the call to the copy function. Upon closer inspection, the spelling error can be identified and corrected.

The previously mentioned Command Prompt extension is a great way to help test scripts in Fireworks. Keep in mind, however, that because the Command Prompt extension is a custom SWF panel, it may fail to provide some Fireworks error alerts when it encounters a problem in the script. Including your own alerts when using the Command Prompt is nonetheless beneficial in determining whether a script is correctly interpreted or whether or not it is executed completely and successfully by Fireworks.

Fireworks actually provides a means to help you debug SWF panels as they send the script to the application. It provides two Fireworks JavaScript methods - fw.enableFlashDebugging() and fw.disableFlashDebugging() - that let you turn debugging mode on and off for commands sent to Fireworks. Don't get too excited, though. All that this debugging includes is an alert of the script being sent to Fireworks from a call to MMExecute. Chances are that you, being the panel developer, already know what that script is so using these methods may only help so much. Calling fw.enableFlashDebugging turns on this alert feature, while fw.disableFlashDebugging turns it off.

Here are some things to consider when debugging:

• Check the spelling of functions and variable names. Capitalization counts.
• Remember that MMExecute uses a string for Fireworks JavaScript commands, so watch for quotes and character-escaping when sending a string from Flash to Fireworks. For example, this code will not work:
• MMExecute("alert("Hello");");
• The open quote in the alert text actually closes the quote string used in MMExecute. Instead, you can use single quotes or escape nested double quotes with the backslash character:
• MMExecute("alert(\"Hello\");");
• Try to use functions as much as possible. This helps you more easily find where a problem may exist and facilitates code reuse.

If you find something that isn't working right, and you think it should, check the Fireworks LiveDocs. You'll find corrections to the Help documentation there and possibly solutions to whatever problem you may be encountering. Also feel free to ask questions in the Extending Fireworks Forum.

Now that you have a better understanding of debugging and improvements that can be made to your workflow, it's time to start with a new, slightly more complex example: the Mirror panel.