Extending Dreamweaver with its JavaScript API

Welcome back to the second part of our Dreamweaver series. We talked about configuration issues in part one, and today we'll move forward by dissecting the first custom command to determine the document's number of words and characters.

The goal of this column is to help you get comfortable working with Dreamweaver's APIs before we get into creating more sophisticated solutions up the road. While this week's example is relatively simple, our work will become a little more complex in the next column, as we'll continue to explore the Dreamweaver JavaScript-APIs and build a tree-style menu widget along our way, which will let you create your site navigation with a simple click. But, let's finish our own custom command first.

What you'll need

In order to follow along with this article, you'll need Dreamweaver or Dreamweaver UltraDev version 3 or later. You can download a free 30-day evaluation copy of Dreamweaver 4 at Macromedia.

Additional resources

It's a good idea to download the following documentation to help you follow this article. The definitive reference for Dreamweaver's JavaScript API and configuration issues is Macromedia's Extending Dreamweaver 3, which is available in a few languages at the Support Center. The reference for the latest version, Dreamweaver 4, is currently only available in English, but is nevertheless better reading because it has links to all functions.

Working with documents

Accessing a window or document is quite easy when you're hosted inside a browser. You get a reference to a window via the frames array from properties such as "opener" or a variable. Dreamweaver must naturally take a different approach, so, in order to find the active document, you'd write:

var doc = dreamweaver.getActiveWindow();

In contrast to the method's name, it returns a DOM document rather than a window object. The dreamweaver object is one of two generic objects inside Dreamweaver (you can also access it via the shortcut dw). It contains properties like appVersion and methods to operate on the application itself, rather than on documents. Another way to access a document is getDocumentDom(), a method of the dreamweaver object:

var doc = dreamweaver.getDocumentDom("document");

This method expects one argument, which determines the document to access -- document points to the active document, parent points to the parent frameset, and parent.frames[number] or parent.frames["framename"] points to a frame of the same frameset of the active document.

Accessing the current document works just like it does in a browser. When your code is running as a command, the current document is the dialogue shown.

The Document Object Model

Dreamweaver 3 introduced a lot of new features. One of them is a new and enhanced Document Object Model, which is a mixture of Netscape's homegrown DOM and a subset of DOM Level 1.

Those new to the world of the DOM can refer to a previous Essential JavaScript column for an introduction to the basics of the DOM. If you're already familiar with Netscape's or the W3C's DOM, you won't find a lot of surprises. The DOM Level 1 implementation is not complete, but it is good enough to let you access and manipulate every element. Unfortunately, the handy getElementById() method is missing in contrast to the DOM Level 1 specification. This makes accessing the DOM tree a little harder sometimes, but you can find a utility method that can be used as a workaround inside the library's archive file.

So, after finding the needed document (see above), you can access its document structure through DOM's documentElement property. To access its HTML content, you can use either the innerHTML or outerHTML property. The latter also contains the tags that make up the element:

var docRoot = doc.documentElement;
var html = docRoot.outerHTML;

The next step will tell you why I accessed outerHTML instead of innerHTML.

Accessing a selection

Retrieving a document's selection is not part of the DOM specs, so we need to use proprietary methods, which are all extensions of the document object. To access the current selection you write:

var sel = doc.getSelection();

The getSelection() method returns an array of pairs of byte offsets. Depending on the selection, the array has at least two fields -- a start offset followed by an end offset. More complex selections are expressed in more than one pair. The offsets are expressed in bytes beginning from the start of the selection, and can be extracted easily with a simple substring() call (see the the full source code). Additionally, the method getSelectedNode() can be used to retrieve the node which contains the selection.

To make the command more flexible, we check the extracted text's length. If it's zero, we assume the user wants to apply the command to the whole document instead to a selection.

Dreamweaver's Selection API also allows you to select or substring, an element, or a table programmatically.