The Dreamweaver API

The Dreamweaver API is a set of custom JavaScript functions and objects that can be used to communicate with the program and extend its functionality, and a set of procedures for processing those instructions.

Parts of the API

The API puts three kinds of entities at your disposal for working with extensions, each with its own rules for use and purpose within the whole. They are extension-specific functions and procedures; custom JavaScript objects for use with all extensions; and custom form elements for creating dialog box and panel interfaces.

Extension-Specific Functions and Procedures

Each kind of extension (object, behavior, and so on) has its own procedures and functions, some required and some optional. Some of these functions are called automatically and need be defined only in the extension file. The first thing you'll need to know about creating any extension is how to work with its required functions and procedures. In this book, we'll cover that information for each extension type as we come to it.

Custom Dreamweaver Objects

In addition to these custom functions, the API includes several custom objects, providing hundreds of methods and properties. Usually, these must be explicitly called on and can be used with any extension type. (The Extending Dreamweaver manual devotes 300 of its 500 pages to a dictionary reference of these objects.) The most generally useful of these objects are the dreamweaver object, the site object, and the object representing the current document's DOM. Other objects include the MMHttp object (for working with Web servers), the DWFile object (for working with file input and output operations), the MMNotes object (for working with design notes), and the FWLaunch object (for working with Fireworks). Some sample methods will give you the idea of what these objects can accomplish :

 dw.quitApplication()  dw.openDocument()  dw.setUpFindReplace()  site.checkLinks()  site.recreateCache()  site.defineSites()  dom.loadTracingImage()  dom.setRulerUnits()  dom.setSelection() 

If you examine the source code for any of the files in the Configuration folder, you'll see these and other object methods used extensively to control the program.

Custom Form Input Tags

All user input, whether through dialog boxes, inspectors, or floating panels, is handled by HTML forms. In addition to the standard form input tags (text, button, checkbox, and so on), the Dreamweaver API includes two custom input types: a color control button and a tree control structure. Color control is provided through the <mmcolorbutton> tag, which creates a color swatch and pop-up color palette like that seen in various inspectors and dialog boxes throughout Dreamweaver (see Figure 1.2). Tree structures are provided through <mm:treecontrol> , <mm:treecolumn> , and <mm:treenode> tags, and create an expandable data hierarchy such as that found in the Edit: Keyboard Shortcuts dialog box and the Tag Inspector's tree view (see Figure 1.3). We'll be using both of these custom input elements in the course of the exercises in this book.

Figure 1.2. The Property inspector, showing the color button and popup color swatches palette.

Figure 1.3. The Tag Inspector and Keyboard Shortcut Editor, both of which use tree control structures.

Working with the API

Every extension-writing task you perform will involve working with the API. The main purpose of this book is to familiarize you with it. Extending Dreamweaver means writing JavaScript and putting all of your scripting knowledge to work, but the particular requirements and possibilities of the Dreamweaver API may be confusing if you're used to writing scripts for browsers to use. In particular, be aware of the following:

• Procedures are important. As mentioned earlier, each extension type has its own procedures. These procedures often involve functions that are automatically called without function calls, and forms that are automatically processed without requiring event handlers or submit buttons . It's important to know which actions to specify and which to leave to the Dreamweaver automatic procedures.

• Extensions can include local as well as API functions. In addition to the supplied functions and objects of the API, extensions may also include "local" functions that are not part of the API. These functions won't be called in any API procedure, so they must be explicitly defined and called, as in any JavaScript file. The standard extension files include many local functions created by the Macromedia engineers ; most have "MM_" affixed to the beginning of the function name. When you're writing extensions, you can create any local function you need, as long as you explicitly define and call it. You are also free to copy and re-use Macromedia's local functions as local functions in your own code, although if you alter them Macromedia asks that you remove the "MM" from the function name .

• Take advantage of shared files. Dreamweaver ships with a variety of JS files that are called on as external JavaScript source links in different extensions. (These files are stored in the Shared folder, inside the Configuration folder.) You are free to link to these files as you write your own extensions. The contents of these files are not part of the API; rather, they're tools that the Macromedia programmers used to work with the API, and that you can also use. You're also free to create your own shared files; Macromedia recommends that you store those files inside the Shared folder, in a folder with your company name. We'll be accessing and creating shared files in the course of the exercises in this book.