Macromedia DREAMWEAVER MX User Manual

Extending Dreamweaver

Trademarks

Add Life to the Web, Afterburner, Aftershock, Andromedia, Allaire, Animation PowerPack, Aria, Attain, Authorware,
Authorware Star, Backstage, Bright Tiger, Clustercats, Cold Fusion, Contribute, Design in Motion, Director, Dream Templates,
Dreamweaver, Drumbeat 2000, EDJE, EJIPT, Extreme 3D, Fireworks, Flash, Fontographer, FreeHand, Generator, HomeSite,
JFusion, JRun, Kawa, Know Your Site, Knowledge Objects, Knowledge Stream, Knowledge Track, LikeMinds, Lingo, Live
Effects, MacRecorder Logo and Design, Macromedia, Macromedia Action!, Macromedia Flash, Macromedia M Logo & Design,
Macromedia Spectra, Macromedia xRes Logo and Design, MacroModel, Made with Macromedia, Made with Macromedia Logo
and Design, MAGIC Logo and Design, Mediamaker, Movie Critic, Open Sesame!, Roundtrip HTML, Shockwave, Sitespring,
SoundEdit, Titlemaker, UltraDev, Web Design 101, what the web can be, and Xtra are either registered or trademarks of
Macromedia, Inc. and may be registered in the United States or in other jurisdictions including internationally. Other product
names, logos, designs, titles, words or phrases mentioned within this publication may be trademarks, servicemarks, or tradenames
of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally.

Third-Party Information

This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not
responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your
own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia
endorses or accepts any responsibility for the content on those third-party sites.

Third Party Software Notices and/or Additional Terms and Conditions can be found at www.macromedia.com/go/thirdparty/.

Opera ® browser Copyright © 1995-2002 Opera Software ASA and its suppliers. All rights reserved.

Apple Disclaimer

APPLE COMPUTER, INC. MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE
ENCLOSED COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY
PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME
STATES. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH
SPECIFIC LEGAL RIGHTS. THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM
STATE TO STATE.

Copyright © 1997-2003 Macromedia, Inc and its licensors. All rights reserved. This manual may not be copied,
photocopied, reproduced, translated, or converted to any electronic or machine-readable form in whole or in part without
prior written approval of Macromedia, Inc. Part Number ZDW70M300

Acknowledgments

Senior Management: Sheila McGinn

Project Management: Robert Berry

Writing: Robert Berry, David Jacowitz

Editing Management: Lisa Stanziano

Editing: Mary Kraemer, Noreen Maher

Production Management: Patrice O’Neill

Media Design and Production: Adam Barnett, Aaron Begley, Chris Basmajian, John Francis, Jeff Harmon

Special thanks to Jay London, Jeff Schang, Lori Hylan-Cho, Hisami Scott, Sam Mathews, Jake Cockrell, Russ Helfand, Randy
Edmunds, George Comninos, Rosana Francescato, Charles Nadeau, and the entire Dreamweaver engineering and QA teams.

First Edition: September 2003
Macromedia, Inc.

600 Townsend St.
San Francisco, CA 94103

CONTENTS

CHAPTER 1: Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Background. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Installing an extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Additional resources for extension writers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

What’s new in Extending Dreamweaver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Documentation Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Macromedia Press. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Removed Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Errata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Conventions used in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

PART I: Overview

CHAPTER 2: Extending Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Types of Dreamweaver extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Other ways to extend Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Configuration folders and extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Multiuser Configuration folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Running scripts at startup or shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Extension APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

How Dreamweaver processes JavaScript in extensions. . . . . . . . . . . . . . . . . . . . 26

Displaying Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Localizing an extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

XML String files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Localizable Strings with Embedded Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Working with the Extension Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Customizing Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

About customizing Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

About customizing Dreamweaver in a multiuser environment . . . . . . . . . . . . . 29

About mm_deleted_files.xml tag syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Reinstalling and uninstalling Dreamweaver in a multiuser environment . . . . . . 32

Customizing default documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Customizing page designs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Customizing the appearance of dialog boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

3

Changing the default file type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Customizing the interpretation of third-party tags . . . . . . . . . . . . . . . . . . . . . . 34

Working with browser profiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

About browser-profile formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Creating and editing a browser profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Changing FTP mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Extensible document types in Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Opening a document in Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

CHAPTER 3: User Interfaces for Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Designing an extension user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Dreamweaver HTML rendering control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Using custom UI controls in extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Editable select lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Database controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Adding a variable grid control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Adding tree controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Manipulating content within a tree control . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

A color button control for extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Adding Flash content to Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

A simple Flash dialog box example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

CHAPTER 4: The Dreamweaver Document Object Model. . . . . . . . . . . . . . . . . . 67

Which document DOM? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

The Dreamweaver DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Objects, properties, and methods of the Dreamweaver DOM . . . . . . . . . . . . . 68

Properties and methods of the document object . . . . . . . . . . . . . . . . . . . . . . . 71

Properties and methods of HTML tag objects . . . . . . . . . . . . . . . . . . . . . . . . . 72

Properties and methods of text objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Properties and methods of comment objects . . . . . . . . . . . . . . . . . . . . . . . . . . 74

The dreamweaver and site objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

CHAPTER 5: Customizing Code View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Code Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

The CodeHints.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Code Hints tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Code coloring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Code coloring files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Scheme block delimiter coloring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Scheme processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Editing schemes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Code coloring examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Code validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

<css-support> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

<property> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

<value>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Changing default HTML formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

4 Contents

PART II: Extension APIs

CHAPTER 6: Insert Bar Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

How object files work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

The Insert bar definition file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Insertbar.xml tag hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Insert bar definition tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Insert bar definition tag attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Modifying the Insert bar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Adding objects to the Insert bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Adding objects to the Insert menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

The Objects API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

canInsertObject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

displayHelp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

isDomRequired() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

insertObject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

objectTag() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

windowDimensions() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

A simple Insert Object example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

CHAPTER 7: Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

How commands work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Adding commands to the Commands menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

The Commands API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

canAcceptCommand() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

commandButtons() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

isDomRequired() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

receiveArguments(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

windowDimensions() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

A simple Command example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Creating the UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Writing the JavaScript code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Running the command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

CHAPTER 8: Menus and Menu Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

About the menus.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

<menubar>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

<menu> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

<menuitem>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

<separator>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

<shortcutlist> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

<shortcut> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Changing menus and menu items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Changing the name of a menu item or menu . . . . . . . . . . . . . . . . . . . . . . . . . 152

Changing keyboard shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Contents 5

Menu Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Modifying the Commands menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

How menu commands work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

The Menu Commands API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

canAcceptCommand() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

commandButtons() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

getDynamicContent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

isCommandChecked() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

receiveArguments(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

setMenuText() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

windowDimensions() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

A simple menu command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Creating the menu items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Writing the JavaScript code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Placing the command file in the Menu folder . . . . . . . . . . . . . . . . . . . . . . . . . 164

A dynamic menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Creating the dynamic menu items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Writing the JavaScript code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

CHAPTER 9: Toolbars. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

How toolbars work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

How toolbars behave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

How toolbar commands work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

The toolbar definition file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

<toolbar> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

<include/> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

<itemtype/> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

<itemref/>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

<separator/> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Toolbar item tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

<button> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

<checkbutton> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

<radiobutton> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

<menubutton> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

<dropdown>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

<combobox>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

<editcontrol> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

<colorpicker> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Item tag attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

id="unique_id". . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

showIf="script". . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

image="image_path" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

disabledImage="image_path" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

overImage="image_path" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

tooltip="tooltip string" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

label="label string" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

width="number" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

menuID="menu_id" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

colorRect="left top right bottom". . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

6 Contents

file="command_file_path" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

domRequired="true" or "false" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

enabled="script" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

checked="script". . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

value="script" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

update="update_frequency_list". . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

command="script" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

arguments="argument_list" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

The toolbar command API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

canAcceptCommand() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

getCurrentValue(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

getDynamicContent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

getMenuID() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

getUpdateFrequency() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

isCommandChecked() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

isDOMRequired() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

receiveArguments(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

showIf() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

A simple toolbar command file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Creating the text box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Writing the JavaScript code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Placing the files in the Toolbars folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

CHAPTER 10: Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

How site reports work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

How stand-alone reports work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

The Reports API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

processFile() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

beginReporting() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

endReporting(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

commandButtons() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

configureSettings() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

windowDimensions() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

CHAPTER 11: Tag Libraries and Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Tag library file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

The Tag Chooser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Creating a new tag editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Tag editor APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

inspectTag() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

validateTag(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

applyTag() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Contents 7

CHAPTER 12: Property Inspectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

How Property inspector files work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

The Property inspector API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

canInspectSelection() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

displayHelp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

inspectSelection() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

CHAPTER 13: Floating Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

How floating panel files work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

The Floating panel API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

displayHelp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

documentEdited() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

getDockingSide() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

initialPosition(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

initialTabs() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

isATarget() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

isAvailableInCodeView() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

isResizable() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

selectionChanged(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Script Editor: a floating panel extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

Creating the floating panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

Writing the JavaScript code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Saving the file in the Floaters folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Creating a menu item. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

CHAPTER 14: Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

How Behaviors work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Inserting multiple functions in the user’s file. . . . . . . . . . . . . . . . . . . . . . . . . . 236

The Behaviors API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

applyBehavior() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

behaviorFunction(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

canAcceptBehavior(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

displayHelp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

deleteBehavior() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

identifyBehaviorArguments() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

inspectBehavior() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

windowDimensions() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

What to do when an action requires a return value . . . . . . . . . . . . . . . . . . . . . 243

CHAPTER 15: Server Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Dreamweaver architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

How the Server Behavior API functions are called . . . . . . . . . . . . . . . . . . . . . . . . 251

The Server Behavior API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

analyzeServerBehavior() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

applyServerBehavior(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

canApplyServerBehavior(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

copyServerBehavior() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

8 Contents

deleteServerBehavior() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

displayHelp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

findServerBehaviors() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

inspectServerBehavior() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

pasteServerBehavior() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Server behavior implementation functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

dwscripts.findSBs(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

dwscripts.applySB() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

dwscripts.deleteSB() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Editing EDML files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

Regular expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

Notes about EDML structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Group EDML file tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

<group> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

<group> attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

<title>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

<groupParticipants> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

<groupParticipants> attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

<groupParticipant>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

<groupParticipant> attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Participant EDML files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

<participant> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

<participant> attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

<quickSearch> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

<insertText> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

<insertText> attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

<searchPatterns>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

<searchPatterns> attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

<searchPattern> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

<searchPattern> attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

<updatePatterns> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

<updatePattern> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

<updatePattern> attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

<delete> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

<delete> attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

<translator> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

<searchPatterns>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

<translations> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

<translation> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

<translation> attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

<openTag> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

<attributes> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

<attribute> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

<display> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

<closeTag> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Server behavior techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Finding server behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Updating server behaviors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

Deleting server behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Avoiding conflicts with share-in-memory JavaScript files . . . . . . . . . . . . . . . . 292

Contents 9

CHAPTER 16: Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

How data sources work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

The Data Sources API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

addDynamicSource() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

deleteDynamicSource(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

displayHelp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

editDynamicSource() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

findDynamicSources() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

generateDynamicDataRef() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

generateDynamicSourceBindings() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

inspectDynamicDataRef() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

A simple data source example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Creating the data source definition file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Creating the EDML file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Creating the JavaScript file that implements the Data Sources API functions . 301

Creating the supporting command files for user input . . . . . . . . . . . . . . . . . . 303

Using the new data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

CHAPTER 17: Server Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

How data formatting works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

The Formats.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

The Edit Format List Plus (+) menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

When the data formatting functions are called . . . . . . . . . . . . . . . . . . . . . . . . . . 309

The Server Formats API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

applyFormat(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

applyFormatDefinition() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

deleteFormat() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

formatDynamicDataRef(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

inspectFormatDefinition() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

CHAPTER 18: Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

How to customize the Component panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Component panel files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Component panel API functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

getComponentChildren() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

getContextMenuId(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

getCodeViewDropCode(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

getSetupSteps(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

setupStepsCompleted(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

handleDesignViewDrop(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

handleDoubleClick() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

toolbarControls() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

10 Contents

CHAPTER 19: Server Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

How customizing server models works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

The Server Model API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

canRecognizeDocument(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

getFileExtensions() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

getLanguageSignatures() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

getServerExtension(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

getServerInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

getServerLanguages() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

getServerModelExtDataNameUD4() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

getServerModelDelimiters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

getServerModelDisplayName(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

getServerModelFolderName(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

getServerSupportsCharset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

getVersionArray() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

CHAPTER 20: Data Translators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

How data translators work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

The Data Translator API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

getTranslatorInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

translateMarkup(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

liveDataTranslateMarkup(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

Determining what kind of translator to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

Adding a translated attribute to a tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

Inspecting translated attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

Locking translated tags or blocks of code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

A simple block/tag translator example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Finding bugs in your translator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

CHAPTER 21: C-Level Extensibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

How integrating C functions works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

C-level extensibility and the JavaScript interpreter. . . . . . . . . . . . . . . . . . . . . . . . 355

Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

The C-level API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

typedef JSBool (*JSNative)(JSContext *cx, JSObject *obj,

unsigned int argc, jsval *argv, jsval *rval) . . . . . . . . . . . . . . . . . . . . . . . . . . 356

JSBool JS_DefineFunction(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

char *JS_ValueToString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

JSBool JS_ValueToInteger() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

JSBool JS_ValueToDouble(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

JSBool JS_ValueToBoolean() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

JSBool JS_ValueToObject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

JSBool JS_StringToValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

JSBool JS_DoubleToValue(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

JSVal JS_BooleanToValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

JSVal JS_IntegerToValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

JSVal JS_ObjectToValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

char *JS_ObjectType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Contents 11

JSObject *JS_NewArrayObject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

long JS_GetArrayLength() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

JSBool JS_GetElement(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362

JSBool JS_SetElement() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362

JSBool JS_ExecuteScript() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363

JSBool JS_ReportError() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363

File Access and Multiuser Configuration API . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

JS_Object MM_GetConfigFolderList() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

JSBool MM_ConfigFileExists() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

int MM_OpenConfigFile() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

JSBool MM_GetConfigFileAttributes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

JSBool MM_SetConfigFileAttributes(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

JSBool MM_CreateConfigFolder(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

JSBool MM_RemoveConfigFolder() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

JSBool MM_DeleteConfigFile(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

Calling a C function from JavaScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

PART III: Appendix

APPENDIX A: The Shared Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

The Shared folder contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

The Common folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

The MM folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

Other folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

Using the Shared folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

12 Contents

CHAPTER 1

Introduction

This book describes the Macromedia Dreamweaver MX 2004 framework and application
programming interface (API) that lets you build extensions to Dreamweaver. Extensions typically
perform the following types of tasks:

• Automating changes to the user’s current document, such as inserting HTML, CFML, or

JavaScript; changing text or image properties; or sorting tables

• Interacting with the application to automatically open or close windows, open or close

documents, change keyboard shortcuts, and more

• Connecting to data sources, which lets Dreamweaver users create dynamic, data-driven pages

• Inserting and managing blocks of server code in the current document

You might want to write an extension to handle a commonly used, and therefore repetitive, task.
Such an extension could be useful to many web developers. On the other hand, you might have a
unique requirement that you can satisfy only by writing an extension for that specific situation. In
both cases, Dreamweaver provides an extensive set of tools that you can use to add to or customize
its functionality.

This book describes the API functions that Dreamweaver calls to implement the various objects,
menus, floating panels, server behaviors, and so on, that comprise the features of Dreamweaver.
To add an object, menu, floating panel, or other feature to Dreamweaver, you must code the
functions that the particular type of extension requires. This book describes the arguments that
Dreamweaver passes to these functions and also the values that Dreamweaver expects these
functions to return.

This book also explains how to customize Dreamweaver by editing and adding tags to various
HTML and XML files to add menu items or document types, and so on.

For information on the utility and general purpose JavaScript APIs that you can use to perform
various support operations in your Dreamweaver extensions, see the Dreamweaver API Reference.
If you plan to create extensions that work with databases, you might also want to review the
sections in Getting Started with Dreamweaver about making connections to databases.

13

Background

Most Dreamweaver extensions are written in HTML and JavaScript. This book assumes that you
are familiar with Dreamweaver, HTML, XML, and JavaScript programming. If you are
implementing C extensions, the book assumes that you know how to create and use C dynamic
linked libraries (DLLs). If you are writing extensions for building web applications, you should
also be familiar with server-side scripting on at least one platform, such as Active Server Pages
(ASP), ASP.net, PHP: Hypertext Preprocessor (PHP), ColdFusion, or Java Server Pages (JSP).

Installing an extension

As you become familiar with the process of writing extensions, you might want to explore the
extensions and resources that are available through the Macromedia Exchange website
(www.macromedia.com/exchange). Installing an existing extension introduces you to some of the
tools that you need to work with in your own extensions.

To install an extension, use the following procedure:

1 Download and install the Extension Manager, which is available on the Macromedia

Downloads website (www.macromedia.com/software/downloads).

2 Log on to the Macromedia Exchange website (www.macromedia.com/exchange).
3 From the available extensions, select one that you want to use. Click the Download link to

download the extension package.

4 Save the extension package in the Dreamweaver MX 2004/Downloaded Extensions folder of

your installed Dreamweaver folder.

5 In the Extension Manager, select File > Install Extension. In Dreamweaver, select

Commands > Manage Extensions to start the Extension Manager.
The Extension Manager automatically installs the extension from the Downloaded Extension

folder into Dreamweaver.

Some extensions need Dreamweaver to restart before you can use them. If you are running
Dreamweaver when you install the extension, you might be prompted to quit and restart
the application.

To view basic information on the extension after its installation, go to the Extension Manager
(Commands > Manage Extensions) in Dreamweaver.

Additional resources for extension writers

To communicate with other developers who are involved in writing extensions, you might want
to join the Dreamweaver extensibility newsgroup. You can access the website for this newsgroup
at www.macromedia.com/go/extending_newsgrp/.

14 Chapter 1: Introduction

What’s new in Extending Dreamweaver

Dreamweaver MX 2004 includes the following new features and interfaces that are extensible.

• New Insert Bar

The Insert Bar is now divided into separate categories (instead of tabs) for grouping various
objects, and also supports pop-up menus. This new grouping and functionality presents a less
cluttered user interface. Users can now group their favorite objects into a Favorites category for
their own quick reference. Extensions can be added to their own category or pop-up menu and
grouped with other existing objects. See Chapter 6, “Insert Bar Objects,” on page 113.

• Extensible code coloring

Lets you add new keywords to an existing code coloring scheme or create a new one. If you
develop new JavaScript functions to use in your client-side script, for example, you can add the
names of these functions to the keywords section so that they display in the color that is
specified in Preferences. You can also add new code coloring schemes for a new document type.
For more information, see Chapter 5, “Customizing Code View,” on page 77.

• The cssimport and cssmedia tags support code coloring rules for the @import and @media

functions of the

Chapter 5, “Customizing Code View,” on page 77.

style element in a cascading style sheet. For more information, see

• API support for Flash Elements (SWC files).

Extension developers can add their own Flash Elements to the Insert Bar, Insert menu, or other
Toolbars so users can insert them into documents by simply clicking a button or menu option.
See “Flash Integration” in the Dreamweaver API Reference.

• Enhanced support for “code behind” pages can be found in the CodeBehindMgr.js file in the

Dreamweaver Configuration/Shared/Common folder. See Appendix A, “The Shared folder

contents,” on page 375.

• Integration of Customizing Dreamweaver content.

Material formerly available only as a separate document download from the Macromedia
website is now integrated into this book.

Documentation Changes

Extending Dreamweaver MX has been divided into two books: Extending Dreamweaver and the
Dreamweaver API Reference. Extending Dreamweaver describes how to build various types of

Dreamweaver extensions, including the functions that you must write to create each type. It also
describes how to customize Dreamweaver by modifying some of its configurable HTML and
XML files. The Dreamweaver API Reference describes the two APIs that let you perform various
supporting tasks in your Dreamweaver extensions.

The Extending Dreamweaver book is designed to serve the user who wants to learn how to build a
Dreamweaver extension. The Dreamweaver API Reference is designed to serve the experienced
Dreamweaver programmer who wants to quickly locate the right function to accomplish a
particular task. Dividing the material into two books also clarifies the distinction between the
extension API functions that an extension author must code, and which Dreamweaver calls, and
the JavaScript and Utility API functions that a programmer can call to accomplish various tasks
from within an extension.

Extending Dreamweaver includes the following improvements to help new extension authors to
get started.

What’s new in Extending Dreamweaver 15

• New and updated examples

New examples have been added for the Insert Bar, Components, Data Sources, Flash
Integration, and the Shared folder. The examples in the Commands, Menu Commands,
Toolbars, and Floating Panels chapters have been updated with graphics and explanations to
make them easier to understand.

• New organization

Some material has been reorganized to improve clarity. The JavaScript API functions in the
Dreamweaver API Reference, for example, have been organized into chapters that designate
which part of Dreamweaver the functions affect.

• Description of Shared folder contents (see Appendix A)

The Dreamweaver Configuration/Shared folder holds several files and subfolders containing
HTML and JavaScript code that implement various Dreamweaver features and user interfaces.
These files are in the Shared folder because the HTML and JavaScript code are commonly
useful. Appendix A briefly describes what is contained in the most useful files and subfolders
inside the Configuration/Shared folder.

• Revised Components chapter

The Components chapter has been revised for clarity and depth, including more
function examples.

For information on the new functions that have been added to the Utility API and the JavaScript
API, see the Dreamweaver API Reference.

Macromedia Press

Improve your Dreamweaver skills with books from Macromedia Press. Check out the latest
content written by the experts. See www.macromedia.com/go/dw2004_help_mmp.

Removed Features

In Dreamweaver MX 2004, several features have been removed. As a result, the following material
has been removed from Extending Dreamweaver:

• References to the Dreamweaver 4 style workspace

• The JavaScript Debugger chapter

For information on all the features that have been removed from Dreamweaver, see Using
Dreamweaver. For information on the functions that have been removed from the Utility and
JavaScript APIs, see the Dreamweaver API Reference.

Errata

A current list of known issues can be found in the Extensibility section of the Dreamweaver
Support Center (www.macromedia.com/go/extending_errata).

16 Chapter 1: Introduction

Conventions used in this guide

The following typographical conventions are used in this guide:

• Code font indicates code fragments and API literals, including class names, method names,

function names, type names, scripts, SQL statements, and both HTML and XML tag and
attribute names.

• Italic code font indicates replaceable items in code.

• The continuation symbol (¬) indicates that a long line of code has been broken across two or

more lines. Due to margin limits in this book’s format, what is otherwise a continuous line of
code must be split. When copying the lines of code, eliminate the continuation symbol, and
type the lines as one line.

• Curly braces ({ }) that surround a function argument indicate that the argument is optional.

• Function names that have the prefix dreamweaver. as in dreamweaver.funcname, can be

abbreviated to

dreamweaver. prefix when defining the function and in the index. Many examples use the

shorter

The following naming conventions are used in this guide:

dw.funcname when you are writing code. This manual uses the full

dw. prefix, however.

• You—the developer who is responsible for writing extensions

• The user—the person using Dreamweaver

• The visitor—the person who views the web page that the user created

Conventions used in this guide 17

18 Chapter 1: Introduction

PART I

Overview

Learn the fundamental concepts of the Macromedia Dreamweaver MX 2004 interface and how
to customize and extend Dreamweaver to suit your web development needs. These fundamental
concepts include the Dreamweaver folders, extension APIs, Dreamweaver interface components,
the Dreamweaver Document Object Model (DOM), and Dreamweaver document types.

Chapter 2: Extending Dreamweaver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Chapter 3: User Interfaces for Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Chapter 4: The Dreamweaver Document Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Chapter 5: Customizing Code View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

PART I

CHAPTER 2

Extending Dreamweaver

The following features of Macromedia Dreamweaver MX 2004 let you create extensions:

• An HTML parser (also called a renderer), which makes it possible to design user interfaces

(UIs) for extensions using form fields, layers, images, and other HTML elements.
Dreamweaver has its own HTML parser.

• A tree of folders that organize and store the files that implement and configure Dreamweaver

elements and extensions.

• A series of application programming interfaces (APIs) that provide access to Dreamweaver

functionality through JavaScript.

• A JavaScript interpreter, which executes the JavaScript code in extension files. Dreamweaver

uses the Netscape JavaScript version 1.5 interpreter. For more information about changes
between this version of the interpreter and previous versions, see “How Dreamweaver processes

JavaScript in extensions” on page 26.

Types of Dreamweaver extensions

The following list describes the types of Dreamweaver extensions that are documented in
this guide:

Insert Bar object extensions create changes in the Insert bar. An object is typically used to

automate inserting code into a document. It can also contain a form that gathers input from the
user and JavaScript that processes the input. Object files are stored in the Configuration/Objects
folder.

Command extensions can perform almost any specific task, with or without input from the user.

Command files are typically invoked from the Commands menu, but they can also be called from
other extensions. Command files are stored in the Configuration/Commands folder.

Menu Command extensions expand the Command API to accomplish tasks related to calling a

command from a menu. The Menu Commands API also lets you create a dynamic submenu.

Toolbar extensions can add elements to existing toolbars or create new toolbars in the

Dreamweaver UI. New toolbars appear below the default toolbar. Toolbar files are stored in the
Configuration/Toolbars folder.

Report extensions can add custom site reports or modify the set of prewritten reports that come

with Dreamweaver. You can also use the Results Window API to create a stand-alone report.

21

Tag Library and Editor extensions work with the associated tag library files. Tag Library and

Editor extensions can modify attributes of existing Tag Dialogs, create new Tag Dialogs, and add
tags to the tag library. Tag Library and Editor extension files are stored in the Configuration/
TagLibraries folder.

Property Inspector extensions appear in the Property inspector panel. Most of the inspectors in

Dreamweaver are part of the core product code and cannot be modified, but custom Property
inspector files can override the built-in Dreamweaver Property inspector interfaces or create new
ones to inspect custom tags. Inspectors are stored in the Configuration/Inspectors folder.

Floating Panel extensions add floating panels to the Dreamweaver UI. Floating panels can

interact with the selection, the document, or the task. They can also display useful information.
Floating panel files are stored in the Configuration/Floaters folder.

Behavior extensions let users add JavaScript code to their documents. The JavaScript code

performs a specific task in response to an event when the document is viewed in a browser.
Behavior extensions appear on the Plus (+) menu of the Dreamweaver Behaviors panel. Behavior
files are stored in the Configuration/Behaviors/Actions folder.

Server Behavior extensions add blocks of server-side code (ASP, JSP, or ColdFusion) to the

document. The server-side code performs tasks on the server when the document is viewed in a
browser. Server behaviors appear on the Plus (

+) menu of the Dreamweaver Server Behaviors

panel. Server behavior files are stored in the Configuration/Server Behaviors folder.

Data source extensions let you build a connection to dynamic data stored in a database. Data

source extensions appear on the Plus (

+) menu of the Bindings panel. Data source extension files

are stored in the Configuration/Data Sources folder.

Server Format extensions let you define formatting for dynamic data.

Component extensions let you add new types of components to the Components panel.

Components is the term that Dreamweaver uses to refer to some of the more popular and modern
encapsulation strategies, including web services, JavaBeans, and ColdFusion components (CFCs).

Server model extensions let you add support for new server models. Dreamweaver supports the

most common server models (ASP, JSP, ColdFusion, PHP, and ASP.NET). Server model
extensions are needed only for custom server solutions, different languages, or a customized
server. Server model files are stored in the Configuration/ServerModels folder.

Data translator extensions convert non-HTML code into HTML that appears in the Design

view of the document window. These extensions also lock the non-HTML code to prevent
Dreamweaver from parsing it. Translator files are stored in the Configuration/Translators folder.

Other ways to extend Dreamweaver

You can also extend the following elements of Dreamweaver to expand its capabilities or tailor it
to your needs.

Document types define how Dreamweaver works with different server models. Information

about document types for server models is stored in the Configuration/DocumentTypes folder.

Code snippets are reusable blocks of code that are stored as code snippet (CSN) files in the

Dreamweaver Configuration/Snippets folder and which Dreamweaver makes accessible in the
Snippets panel. You can create additional code snippet files and install them into the Snippets
folder to make them available.

22 Chapter 2: Extending Dreamweaver

Code Hints are menus that offer a typing shortcut by displaying a list of strings that potentially

complete the string you are typing. If one of the strings in the menu matches the string that you
started to type, you can select it to insert it in place of the string that you are typing. Code Hints
menus are defined in the codehints.xml file in the Configuration/CodeHints folder, and you can
add new code hints menus to it for new tags or functions that you have defined.

Menus are defined in the menus.xml file in the Configuration/Menus folder. You can add new

Dreamweaver menus for your extensions by adding the menu tags for them to the menus.xml file.

Configuration folders and extensions

The folders and files that are stored in the Dreamweaver Configuration folder contain the
extensions that come with Dreamweaver. When you write an extension, you must save the files in
the proper folder for Dreamweaver to recognize them. If you download and install an extension
from the Macromedia Exchange website (www.macromedia.com/exchange), the Extension
Manager automatically saves the extension files to the proper folders.

You can use the files in the Dreamweaver Configuration folder as examples, but these files are
generally more complex than the average extension that is available on the Macromedia Exchange
website. For more information on the contents of each subfolder within the Configuration folder,
see the Configuration_ReadMe.htm file.

Configuration folders and extensions 23

The Configuration/Shared folder does not correspond to a specific extension type. It is the central
repository for utility functions, classes, and images that are used by more than one extension. The
files in the Configuration/Shared/Common folder are designed to be useful to a broad range of
extensions. These files are useful as examples of JavaScript techniques and as utilities. Look here
first for the functions that perform specific tasks, such as creating a valid Document Object
Model (DOM) reference to an object, testing whether the current selection is inside a particular
tag, escaping special characters in strings, and more. If you create common files, you should create
a separate subfolder in the Configuration/Shared/Common folder, which is shown in the
following figure, and store them there.

Configuration/Shared/Common/Scripts folder structure

For more information about the Shared folder, see Appendix A, “The Shared Folder,”

on page 375.

24 Chapter 2: Extending Dreamweaver

Multiuser Configuration folders

For the multiuser operating systems of Windows XP, Windows 2000, and Macintosh OS X,
Dreamweaver creates a separate Configuration folder for each user in addition to the
Dreamweaver Configuration folder. Any time Dreamweaver or a JavaScript extension writes to
the Configuration folder, Dreamweaver automatically writes to the user Configuration folder
instead. This practice lets each Dreamweaver user customize configuration settings without
disturbing the configuration settings of other users. For more information, see “About

customizing Dreamweaver in a multiuser environment” on page 29 and “File Access and

Multiuser Configuration API” in the Dreamweaver API Reference.

Running scripts at startup or shutdown

If you place a command file in the Configuration/Startup folder, the command runs as
Dreamweaver starts up. Startup commands load before the menus.xml file, before the files in the
ThirdPartyTags folder, and before any other commands, objects, behaviors, inspectors, floating
panels, or translators. You can use startup commands to modify the menus.xml file or other
extension files. You can also show warnings, prompt the user for information, or call the

dreamweaver.runCommand() function. However, from within the Startup folder, you cannot call

a command that expects a valid DOM.

Similarly, if you place a command file in the Configuration/Shutdown folder, the command runs
as Dreamweaver shuts down. From the shutdown commands, you can call

dreamweaver.runCommand() function, show warnings, or prompt the user for information, but

you cannot stop the shutdown process.

For more information about commands, see Chapter 7, “Commands,” on page 135. For
more information about the

dreamweaver.runCommand() function, see the Dreamweaver

API Reference.

Extension APIs

The extension APIs provide you with the functions that Dreamweaver calls to implement each
type of extension. You must write the bodies of these functions as described for each extension
type and specify the return values that Dreamweaver expects.

If you are a developer who wants to work directly in the C programming language, there is a
C extensibility API that lets you create dynamic link libraries (DLLs). The functionality that is
provided in these APIs wraps your C DLLs in JavaScript so that your extension can work
seamlessly in Dreamweaver.

The documentation of extension APIs outlines what each function does, when Dreamweaver calls
it, and what value Dreamweaver expects it to return.

See the Dreamweaver API Reference for information about the Utility API and the JavaScript API,
which provide functions that you can use to perform specific tasks in your extensions.

Extension APIs 25

How Dreamweaver processes JavaScript in extensions

Dreamweaver checks the Configuration/extension_name folder during startup. If it encounters an
extension file within the folder, Dreamweaver processes the JavaScript by completing the
following steps:

• Compiling everything between the beginning and ending SCRIPT tags

• Executing any code within SCRIPT tags that is not part of a function declaration

Note: This procedure is necessary during startup because some extensions might require global
variables to initialize.

Dreamweaver performs the following actions for any external JavaScript files that are specified in
the

SRC attributes of SCRIPT tags:

• Reads in the file

• Compiles the code

• Executes the procedures

Note: If any JavaScript code in your extension file contains the string “</SCRIPT>”, the
JavaScript interpreter reads the string as an ending
string literal error. To avoid this problem, break the string into pieces and concatenate them like
this:

"<' + '/SCRIPT>".

SCRIPT tag and reports an unterminated

Dreamweaver executes code in the onLoad event handler (if one appears in the BODY tag) when
the user selects the command or action from a menu for the Command and Behavior action
extension types.

Dreamweaver executes code in the

onLoad event handler on the BODY tag if the body of the

document contains a form for object extensions.

Dreamweaver ignores the

onLoad handler on the BODY tag in the following extensions:

• Data translator

• Property inspector

• Floating panel

For all extensions, Dreamweaver executes code in other event handlers (for example,

onBlur="alert('This is a required field.')") when the user interacts with the form

fields to which they are attached.

Dreamweaver supports the use of event handlers within links. Event handlers in links must use
syntax, as shown in the following example:

<a href=”#” onMouseDown=alert(‘hi’)>link text</a>

Plug-ins (set to play at all times) are supported in the BODY of extensions. The

document.write() statement, Java applets, and ActiveX controls are not supported

in extensions.

26 Chapter 2: Extending Dreamweaver

Displaying Help

The

displayHelp() function, which is part of several extension APIs, causes Dreamweaver to do

the following two things when you include it in your extension:

• Add a Help button to the interface.

• Call displayHelp() when the user clicks the Help button.

You must write the body of the

displayHelp() function determines how your extension displays Help. You can call the
dreamweaver.browseDocument() function to open a file in a browser or devise a custom way to

display Help such as displaying messages in another layer in alert boxes.

The following example uses the

dreamweaver.browseDocument():

// The following instance of displayHelp() opens a browser to display a file
// that explains how to use the extension.
function displayHelp() {

var myHelpFile = dw.getConfigurationPath() + "ExtensionsHelp/myExtHelp.htm";
dw.browseDocument(myHelpFile);

}

displayHelp() function to display Help. How you code the

displayHelp() function to display Help by calling

Localizing an extension

Use the following techniques to make it easier to translate your extensions into local languages.

• Separate extensions into HTML and JavaScript files. The HTML files can be replicated and

localized; the JavaScript files will not be localized.

• Do not define display strings in the JavaScript files (check for alerts and UI code). Extract all

localizable strings into separate XML files in the Dreamweaver Configuration/Strings folder.

• Do not write JavaScript code in the HTML files except for required event handlers. This

eliminates the need to fix a bug multiple times for multiple translations after the HTML files
are replicated and translated into other languages.

XML String files

Store all strings in XML files in the Dreamweaver Configuration/Strings folder. If you install
many related extension files, this lets you share all strings in a single XML file. If applicable, this
also lets you refer to the same string from both C++ and JavaScript extensions.

You could create a file called myExtensionStrings.xml. The following example shows the format
of the file:

<strings>

<!-- errors for feature X -->
<string id="featureX/subProblemY" value="There was a with X when you did Y.
Try not to do Y!"/>
<string id="featureX/subProblemZ" value="There was another problem with X,
regarding Z. Don't ever do Z!"/>

</strings>

Localizing an extension 27

Now your JavaScript files can refer to these translatable strings by calling the dw.loadString()
function, as shown in the following example:

function initializeUI()
{
...
if (problemYhasOccured)
{
alert(dw.loadString("featureX/subProblemY");
}
}

You can use slash (/) characters in your string identifiers, but do not use spaces. Using slashes, you
can create a hierarchy to suit your needs, and include all the strings in a single XML file.

Note: Files that begin with cc in the Configuration/Strings folder are Contribute files. For example,
the file ccSiteStrings.xml is a Contribute file.

Localizable Strings with Embedded Values

Some display strings have values embedded in them. You can use the
display these strings. You can find the

errMsg() function, which is similar to the printf()

errMsg() function to

function in C, in the string.js file in the Configuration/Shared/MM/Scripts/CMN folder. Use the
placeholder characters percent sign (
and then pass the string and variable names as arguments to

<string id="featureX/fileNotFoundInFolder" value="File %s could not be found

in folder %s."/>

%) and s to indicate where values should appear in the string

errMsg(). For example:

The following example shows how the string, along with any variables to embed, is passed to the

alert() function.

if (fileMissing)
{

alert( errMsg(dw.loadString("featureX/fileNotFoundInFolder"),fileName,

folderName) );

}

Working with the Extension Manager

If you create extensions for others users, you must package them according to the guidelines on
the Macromedia Exchange website (www.macromedia.com/exchange) under the Help > How to
Create an Extension category. After you have written and tested an extension in the Extension
Manager, select File > Package Extension. After the extension is packaged, you can submit it to
the Exchange from the Extension Manager by selecting File > Submit Extension.

The Extension Manager comes with Dreamweaver. Details about its use are available in its Help
files and on the Macromedia Exchange website.

28 Chapter 2: Extending Dreamweaver

Customizing Dreamweaver

You can customize Dreamweaver in many ways, which lets you work in a manner that’s familiar,
comfortable, and efficient for you. This section describes advanced methods for customizing
Dreamweaver, with a focus on editing configuration files.

About customizing Dreamweaver

There are several general approaches to customizing Dreamweaver. Some of these approaches are
covered in Dreamweaver Help (Help > Using Dreamweaver). These approaches let you customize
your workspace. You can also change settings in dialog boxes in Dreamweaver. You can set
preferences in a variety of areas, including accessibility, code coloring, fonts, highlighting, and
previewing in browsers, using the Preferences panel (Edit > Preferences). You can also change
keyboard shortcuts, using the Keyboard Shortcut Editor (Edit > Keyboard Shortcuts).

The following list describes some of the ways you can customize Dreamweaver by editing
configuration files:

• Rearrange the objects in the Insert bar, create new tabs to reorganize the objects, or add new

objects. See “Modifying the Insert bar” on page 119.

• Change the names of menu items, add new commands to menus, and remove existing

commands from menus. See “About customizing Dreamweaver” on page 29.

• Change browser profiles or create new ones. See “Working with browser profiles” on page 39.

• Change how third-party tags (including ASP and JSP tags) appear in the Document window’s

Design view. See “Customizing the interpretation of third-party tags” on page 34.

About customizing Dreamweaver in a multiuser environment

You can customize Dreamweaver even in a multiuser operating system such as Windows 2000,
Windows XP, or Mac OS X. Dreamweaver prevents any user’s customized configuration from
affecting any other user’s customized configuration. To accomplish this goal, the first time you
run Dreamweaver in a multiuser operating system that it recognizes, Dreamweaver copies various
configuration files into a user Configuration folder for you. When you customize Dreamweaver
using dialog boxes and panels, the application modifies your user Configuration files instead of
modifying the Dreamweaver Configuration files. To customize Dreamweaver by editing a
configuration file in a multiuser environment, edit the appropriate user Configuration file, rather
than editing the files in the Dreamweaver Configuration folder. To make a change that affects
most users, you can edit a Dreamweaver Configuration file, but users who already have
corresponding user-configuration files will not see the change. In general, if you want to make a
change that affects all the users, it’s best to create an extension and install it using the
Extension Manager.

Note: In older operating systems (Windows 98, Windows ME, and Mac OS 9.x), a single set of
Dreamweaver Configuration files is shared by all users, even if the operating system is configured to
support multiple users.

The location of the user’s Configuration folder depends on the user’s platform.

For Windows 2000 and Windows XP platforms:

<drive>:\Documents and Settings\<username>\ ¬

Application Data\Macromedia\Dreamweaver MX 2004\Configuration

Note: In Windows XP, this folder may be inside a hidden folder.

Customizing Dreamweaver 29

For Mac OS X platforms:

<drive>:Users:<username>:Library:Application Support: ¬

Macromedia:Dreamweaver MX 2004:Configuration

Note: To install extensions that all users can use in a multiuser operating system, you must be logged
in as

Administrator (Windows) or root (Mac OS X).

Dreamweaver copies only some of the configuration files into your user Configuration folder the
first time you run the application. (The files that it copies are specified in the version.xml file in
the Configuration folder.) When you customize Dreamweaver from within the application (for
example, when you modify one of the predesigned code snippets in the Snippets panel),
Dreamweaver copies the relevant files into your user Configuration folder. The version of a file in
your user Configuration folder always takes precedence over the version in the Dreamweaver
Configuration folder. To customize a configuration file that Dreamweaver has not copied into
your user Configuration folder, first copy the file from the Dreamweaver Configuration folder to
the corresponding location inside your user Configuration folder. Then edit the copy in your user
Configuration folder.

Deleting configuration files in a multiuser environment

When you do something within Dreamweaver in a multiuser operating system that would delete
a configuration file (such as when you delete a predesigned snippet from the Snippets panel),
Dreamweaver creates a file in your user Configuration folder called mm_deleted_files.xml. When
a file is listed in mm_deleted_files.xml, Dreamweaver behaves as if that file doesn’t exist.

Note: The mm_deleted_files.xml file isn’t created until you take an action that would cause a
configuration file t

To deactivate a configuration file:

1 Quit Dreamweaver.
2 Using a text editor, edit mm_deleted_files.xml in your user Configuration folder; add an item

o be deleted.

tag to that file, giving the path (relative to the Dreamweaver Configuration folder) of the
configuration file to deactivate.

Note: Do not edit mm_deleted_files.xml in Dreamweaver.

3 Save and close mm_deleted_files.xml.
4 Start Dreamweaver again.

30 Chapter 2: Extending Dreamweaver