Introduction To Developing Fireworks Extensions (They’re Just JavaScript!)

From the drop-down menu, I can select between viewing the contents of four objects:

• fw.selection An array of currently selected elements on the canvas
• fw The Fireworks object
• dom The DOM of the currently active document (which we will discuss next)
• dom.pngText A property of the currently active document (available for us to write to so that we can save data to the current document and retrieve it even after restarting Fireworks)

Document DOM

In the DOM Inspector panel, we can switch to the documentDOM and explore its state. We can also access the documentDOM via JavaScript with the getDocumentDOM() method, as we did with the “Move” command:

fw.getDocumentDOM().moveSelectionBy({x:10, y:10}, false, false);

The getDocumentDOM() method invocation returns only the DOM object of the currently active document, rather than the entire Fireworks DOM, and allows us to manipulate that document via its properties and methods. For example, the moveSelectionBy() method (which the History panel taught us about) does the work of moving elements around the document’s canvas.

Selection Bias

Acting on the current selection is a common pattern when developing Fireworks extensions. It mirrors the way that the user selects elements on the canvas with the mouse, before performing some action on that selection.

fw.getDocumentDOM().moveSelectionBy({x:10, y:10}, false, false);

The document DOM’s moveSelectionBy() function takes a JavaScript object as a parameter:

{x:10, y:10}

Given an origin in the top-left corner, this tells Fireworks to move the selected object by x pixels to the right and by y pixels down.

The other two boolean parameters (false, false) indicate to move (as opposed to copy) the selection and to move the entire element (as opposed to a sub-selection, if any exists).

Like the moveSelectionBy() method, many other Document DOM methods act on the current selection (cloneSelection() and flattenSelection(), to name two).

Expand Your Horizons (And The Canvas)

Using what we have learned so far, let’s write a simple command that will expand the size of our canvas.

Canvas Size

To increase the size of the canvas, we need to know the current size. Our panel can call the JavaScript below to access the canvas’ current dimensions:

  var = canvasWidth = fw.getDocumentDOM().width;
  var = canvasHeight = fw.getDocumentDOM().height;

Now, let’s see how to change these dimensions.

Setting The Canvas’ Size

To set the canvas’ size, we call the setDocumentCanvasSize() method of the Document DOM.

fw.getDocumentDOM().setDocumentCanvasSize({left:0, top:0, right:200, bottom:200});

The method takes a “bounding rectangle” as a parameter:

{left:0, top:0, right:200, bottom:200}

The size of the rectangle will determine the new size of the canvas:

right - left = 200
bottom - top = 200

Here, the rectangle is bounded by the object; therefore, the canvas is 200 × 200 pixels.

Increasing The Canvas’ Size: A Simple Command

Let’s create a simple command that will double the canvas’ size automatically.

Instead of going through the Modify → Canvas → Canvas Size menu and then figuring out a width and height to input and then pressing “OK” whenever we want to increase the canvas’ size, we can combine the two code samples from above to create a quick shortcut to double the canvas’ size.

The code might look something like this:

// Double Canvas Size command, v.0.1 :)
var newWidth = fw.getDocumentDOM().width * 2;
var newHeight = fw.getDocumentDOM().height * 2;
fw.getDocumentDOM().setDocumentCanvasSize({left:0, top:0, right: newWidth, bottom: newHeight});

I’m working on a Mac, so to make this command available from the “Commands” menu in Fireworks, I could save the code above as double_size.jsf in the following location:

/Users/<MYUSERNAME>/Library/Application Support/Adobe/Fireworks CS6/Commands/double_size.jsf

(Check the beginning of the article to see where to save your .jsf commands if you are on a different OS.)

I leave it as an exercise for you to write and save a simple command that cuts the canvas’ size in half.

Conclusion

We’ve covered quite a few things in this article:

• With the help of the History panel, we’ve seen the JavaScript that makes Fireworks run.
• We’ve broken down the JavaScript code needed to move a text element on the canvas, learned about the Fireworks DOM and seen how to manipulate it.
• We’ve gone over how the Console panel executes and tests our JavaScript code. We’ve learned how to debug an extension by logging to the JavaScript console object that the panel introduces into Fireworks’ global namespace.
• We’ve covered the DOM Inspector panel and how to use it to check the properties and values of various parts of the Fireworks DOM.
• We’ve written a simple command to change the canvas’ size automatically.

Another great way to learn more about Fireworks extensions is by deconstructing other extensions. Because Fireworks commands are simple JavaScript files, you could learn a lot by studying the code of other developers. I’d especially recommend the extensions created by the following people:

• John Dunning
• Matt Stow
• Aaron Beall
• Trevor McCauley
• Ale Muñoz

(The Project Phoenix extensions, recently rebooted by Linus Lim, are also worth mentioning. They include Font List, Super Nudge, Auto Save, Rename, Transform, Alignment Guides, Perspective Mockups, Retina Scaler, Layer Commands, Used Fonts and many others.)

Finally, below you’ll find an incomplete list of resources to help you along the way. If you think I’ve missed something important (or if you have any questions), let me know in the comments. I’d be happy to help.

Other Resources

• “Extending Fireworks,” Adobe. This is the official guide to developing extensions for Fireworks CS5 and CS6 (including the “Fireworks Object Model” documentation).
• “Adobe Fireworks JavaScript Engine Errata,” John Dunning. Dunning breaks down the quirks of the JavaScript interpreter that ships with Fireworks. Something not working as it should? Check it here. The list is pretty extensive!
• Fireworks Console, John Dunning. This is a must-have if you write Fireworks extensions!
• DOM Inspector (panel), Aaron Beall.

Further Reading

• Developing A Design Workflow In Adobe Fireworks
• Switching From Adobe Fireworks To Sketch: Ten Tips And Tricks
• The Present And Future Of Adobe Fireworks
• The Power of Adobe Fireworks: What Can You Achieve With It?

(al, mb, ml, mrn)