Web DevCenter    
 Published on Web DevCenter (http://www.oreillynet.com/javascript/)
 See this if you're having trouble printing code examples

Essential JavaScript

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.

Comment on this articleLet's talk about using Dreamweaver's JavaScript functionality ... what's your experience?
Post your comments

Also in Essential JavaScript:

Extending Dreamweaver: Let Dreamweaver Create Your Menus

Extending Dreamweaver with its JavaScript API

Creating Themes with CSS and JavaScript

Parsing and DOM-Tree Building With JavaScript

Document Mathematics: Count Your Words

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.

  Related Reading:
DreamWeaver 4: The Missing Manual

DreamWeaver 4: The Missing Manual
By Dave McFarland
July 2001 (est.)
0-596-00097-9, Order Number: 0979
420 pages (est.), $24.95 (est.)

Menu configuration

Earlier versions of Dreamweaver stored its menu structure in a set of HTML documents. Beginning in version 3, the complete menu structure is stored in one XML file, Dreamweaver_Home/Configuration/Menus/menu.xml. This file defines menubars and shortcut lists that are associated to the different Dreamweaver windows by their ID. For instance, the shortcut list and menubar of the main document window are identified by DWMainWindow.

So, open this file and search for a menubar element with ID DWMainWindow, this menubar holds all menus displayed in sequential order like File, Edit, etc. in menu elements. The name attribute of a menu element defines the name displayed. Adding an underscore in front of a letter causes this item be become selectable with the keyboard when selecting the menu via the "Alt" key.

Inside each menu you can find two different types of elements, either a menuitem or menuseparator element. Since menu.xml pretends to be an XML document (which it's not, as it lacks a document element), you have to take care to close those elements properly when you create new ones, i.e. use a slash before the closing bracket to create a well-formed element.

Creating a new menu item

Creating a new entry for our command is a very straight-forward task. Use the Commands menu for this task. Search for the menu with ID DWMenu_Commands. You're free to create a new menuitem like the one below wherever you want inside the menu element:

<menuitem name="Count W_ords" key="Cmd+Alt+o" file="Commands/CountWords.htm" />

Screen shot of reloading the extensions in Dreamweaver.
Figure 1. Reloading extensions in Dreamweaver

The key attribute creates a hotkey combination for the item. The file attribute points to the command file to be loaded. You can also specify JavaScript code directly in an item by using the command attribute. Additionally, the enabled and checked attributes can be used to describe the behavior.

Setting the enabled attribute value to false causes this menu item be become grayed out and unselectable. The checked attribute can be used to add a checkmark in front of the item with an attribute value of true. Both attributes can only be used if you don't use a file-based command and if they can also contain JavaScript code.

Make sure you create a well-formed document, and when you're finished, just save the file. In case you messed up menu.xml, you can find a default version in the same menu, menu.bak, which just needs to be saved over your edited file to restore the default behavior.

Before you can reload the configuration files, make sure that your command file is in place or you'll get an error. You'll find a the recent version of the file in our JavaScript library. Just download it and save the file in your Dreamweaver_Home/Configuration/Commands/ folder as CountWords.htm.

In order to have Dreamweaver reload its configuration, you can restart the application. Much easier is the following trick.

Reloading the configuration

Fortunately you don't have to restart Dreamweaver every time you change something in your configs. Simply open the objects palette (Ctrl-F2), and click the small triangle on the upper right while holding the Ctrl key (see Figure 1).

You'll find a new menu item at the bottom, Reload Extensions. Selecting it causes Dreamweaver to read the configuration files again, and recreate all configurable items like objects, menus, commands, etc.

Get the example files for this article -- plus information and files for other scripts -- in our JavaScript library.

To work with the new command, just select it via the Commands menu, or use the hotkeys if they are available. To count all of the words, don't select any text and you'll get a count for the entire document. Otherwise, make a selection and call the command for a count of a specific area.

What's next?

We're finished with the first part of this series. In the next column I'll explain the tools needed to access Dreamweaver and it's documents: the JavaScript-API. We'll cover the basics and differences of the implemented object model, explain today's solution, and highlight some other interesting features. Stay tuned!

Claus Augusti is O'Reilly Network's JavaScript editor.

Read more Essential JavaScript columns.

Return to the JavaScript and CSS DevCenter.

Copyright © 2009 O'Reilly Media, Inc.