Accessing Dreamweaver's JavaScript API

Macromedia's Dreamweaver is one of the most popular visual HTML editing tools. And for good reason -- it's powerful, accessible, and it generates pretty good code. During Dreamweaver's evolution, Macromedia has added some interesting new features -- most notable for our purposes is the enhanced JavaScript functionality.

Not only the application is scriptable, it (almost) supports the DOM Level 1 spec and defines its own JavaScript-API with more than 400 different functions. It's also possible to customize the menus and incorporate new commands into it.

In this column I'm going to show you how to get inside of Dreamweaver and manipulate the functions defined by the JavaScript-API. As an example of the mischief you can create once using Dreamweaver commands, I'll give you step by step instructions for adding word count capability to the application.

Enhancing the editor

If you're a regular reader of the Essential JavaScript column, you might be familiar with my article, Document Mathematics: Count Your Words, where I explained how to access a document's content and count the words in it.

Actually, working in Dreamweaver is what gave me the inspiration to write the "Count Your Words" article because I wanted to do a word count while working on an HTML document, but couldn't. So, today I'll explain a bit about Dreamweaver's configuration mechanism, how commands work, and how to implement and incorporate your own word count function. Then you'll be able to count the number of words you've selected or those from the complete document.

What you'll need

To follow the examples, you'll need either Dreamweaver or Dreamweaver Ultradev version 3 or later. Since all configuration files are simple plain text, you can just use Dreamweaver to make the necessary changes. You can download a free 30-day trial version at Macromedia's Dreamweaver download page.

Dreamweaver commands

A command basically lets you work inside of Dreamweaver. You can access and manipulate documents and work with all the others functions defined by the JavaScript-API. Dreamweaver commands are nothing more than just simple HTML documents, which are stored in Dreamweaver_Home/Configuration/Commands/ and are selectable via the Commands menu.

The body part of a document contains, if necessary, a GUI for the command and the head defines or imports the JavaScript code needed. In order to control commands, Dreamweaver defines a Command-API which consists only of four functions that are called in a special order every time a command is invoked.

So, let's see what happens internally when you invoke a command by selecting it in the Commands menu?

The Commands-API

When you select and open the Commands menu, Dreamweaver reads all the command files that are defined for this menu. The menu and its items are defined in a separate configuration file, menu.xml, which is explained in greater detail in the next section.

To determine if a command is suitable for a document or its selection, the function canAcceptComand() is called, and it returns either true or false. In case of the latter, the menu item is grayed out. If you want your command to be always selectable, just leave this function.

To receive arguments, the function receiveArguments() is called. This function receives its arguments either from the attribute property of the selected menu item or from dreamweaver.runCommand(), which is the calling function.

To create the buttons on the right of the dialogue, the function commandButtons() is called in the next step. Here you can create a array of button text and action strings, which must be returned from this function. To make l10n easier, you can use one the symbolic variables defined in Dreamweaver_Home/Configuration/Shared/MM/Scripts/CMN/localtext.js. You can leave this function if your own command doesn't depend on arguments.

In order to become displayed, the HTML document must contain a form element. If it has one, the function windowDimension() is called, which is expected to return a string containing a comma delimited width and height pair. If this function can't be found, the size of the dialogue is determined by the document's content.

In the last step, the functions defined in the document's body onload event handler are called, just as in any other HTML document. Now the command is prepared and ready to work. After completing its task, it's closed by a simple window.close() call.

We created an example file for you containing the needed skeleton with all functions of the Commands-API.

Now, let's see how a command is integrated into one of Dreamweaver's menus.