The Dreamweaver API

[ LiB ]

Dreamweaver extensions are constructed following the Dreamweaver application programming interface (API), which consists of all the procedures, file construction specifications, custom functions, and formatting instructions that determine how and when commands will be processed and dialog boxes will appear, and so on. Learning how to write your own extensions means becoming familiar with the API. The official "dictionary" that explains and documents the API is Macromedia's Extending Dreamweaver manual. This manual comes in PDF format on the Dreamweaver application CD-ROM; you also can download the PDF from the Macromedia website (www.macromedia.com/support/dreamweaver/).

How Extensions are Constructed

Each extension (object, behavior, command, inspector, floating panel, report, translator, and so on) consists of one or more files in the Configuration folder. The file types are as follows :

Every rule has an exception. Although most extensions exist in HTML and JS files, it is possible to create simple extensions that exist solely as command lines built into menus .xml . How that works is beyond the scope of this chapter.

• HTML file Each extension begins with an HTML file. Every command, object, and behavior has one HTML file that is the extension. Form elements, placed in the body, become the extension's user interface.

• JS file Each extension gains its functionality through JavaScript . The script functions can be placed in the head of the main HTML file. More frequently, they are found in JS files linked to the HTML file. Complex extensions might link to several JS files.

• GIF files Icons, buttons , and any other graphic elements that appear in the user interface are created from GIF images, which are also stored in the Configuration folder.

In addition to these files, each extension might have an entry in one of the XML files, such as menus.xml or insertbar.xml , that Dreamweaver uses to populate many of its interface elements.

How Extensions are Processed

For each extension type, the Dreamweaver API has a procedure that determines how the extension's JavaScript instructions will be processed. This procedure often involves custom JavaScript functions that Dreamweaver executes automatically at certain times (on startup, when the user clicks something, and so on).

How Extensions Talk to Dreamweaver

How does an extension tell Dreamweaver to open a new document, insert or edit document contents, or whatever else you want it to do? The API includes a variety of predefined JavaScript objects, each of which contains various methods (functions) that you use to communicate with different parts of the program:

• The Dreamweaver ( dw ) object This object contains dozens of methods to control application-wide behavior. Some sample methods are dw.openDocument() , dw.browseForFileURL() , dw.openWithExternalEditor() , and dw.undo() . This object also contains child objects representing different parts of the application, each of which has its own set of methods, such as dw.cssStylePalette.edit-SelectedStyle() and dw.historyPalette.startRecording() .

• The Document ( dom ) object This object contains hundreds of methods, controlling all aspects of document editing. Document object methods and properties can be used to manipulate the selection ( dom.getSelectedNode() , dom.setSelection() ), can change any document property ( dom.body. bgcolor ="000000" ), and can access and edit any item in a document ( dom.deleteTableRow() ).

• The Site object This object contains methods for working with sites and the Site panel. Site methods let you get and put files ( site.get() , site.put() ), perform sitewide file-management chores ( site.findLinkSource() , site.locateInSite() ), and work with the Site panel itself ( site.editColumns(), site.setFocus() ).

In addition to these main objects, other custom JavaScript objects give you access to specific areas of Dreamweaver, such as working with web servers (the MMHttp object), working with Flash and Fireworks ( SWFFile, FWLaunch ), working with Design Notes ( MMNotes ), and so on. All these objects, methods, and properties are detailed in the Extending Dreamweaver manual, mentioned earlier.

[ LiB ]