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

About mm_deleted_files.xml tag syntax

The mm_deleted_files.xml file contains a structured list of items that describe configuration files
that Dreamweaver is to ignore. These items are described by XML tags, which you can edit in a
text editor.

The following sections describe the syntax of the mm_deleted_files.xml tags. Optional attributes
are marked in the attribute lists with curly braces (

{}); all attributes not marked with curly braces

are required.

<deleteditems>

Description

Container tag holding a list of items that Dreamweaver should treat as deleted.

Attributes

None.

Contents

This tag must contain one or more item tags.

Container

None.

Example

<deleteditems>
<!-- item tags here -->
</deleteditems>

<item>

Description

Specifies a configuration file that Dreamweaver should ignore.

Attributes

name

• name The path to the configuration file, relative to the Configuration folder. In Windows, use

a backslash (\) to separate parts of the path; on the Macintosh, use a colon (:).

Contents

None (empty tag).

Container

This tag must be contained in a deleteditems tag.

Example

<item name="snippets\headers\5columnwith4links.csn" />

Customizing Dreamweaver 31

Reinstalling and uninstalling Dreamweaver in a multiuser environment

After you install Dreamweaver, if you later reinstall it or upgrade to a later version, Dreamweaver
automatically makes backup copies of existing user configuration files, so that if you’ve
customized those files, you can still access the changes you made. When you uninstall
Dreamweaver from a multiuser system (which you can do only if you have administrative
privileges), Dreamweaver can remove each user Configuration folder for you.

Customizing default documents

The DocumentTypes/NewDocuments folder contains a default (blank) document of each type
that you can create using Dreamweaver. When you create a new blank document by selecting
File > New and selecting an item from the Basic Page, Dynamic Page, or Other categories,
Dreamweaver bases the new document on the appropriate default document in this folder. To
change what appears in a default document of a given type, edit the appropriate document in
this folder.

Note: If you want all the pages in your site to contain common elements (such as a copyright notice)
or a common layout, it’s better to use templates and library items than to change the default
documents. For more information on templates and library items, see Dreamweaver Help (Help >
Using Dreamweaver).

Customizing page designs

Dreamweaver provides a variety of predesigned cascading style sheets, framesets, and page designs.
You can create pages based on these designs by selecting File > New.

To customize the available designs, edit the files in BuiltIn/css, BuiltIn/framesets,

BuiltIn/Templates, and BuiltIn/TemplatesAccessible folders.

Note: The designs listed in the Page Designs and Page Designs (Accessible) categories are
Dreamweaver template files; for more information on templates, see Dreamweaver Help (Help >
Using Dreamweaver).

You can also create custom page designs by adding files to the subfolders of the BuiltIn folder. To
make a description of the file appear in the New Document dialog box, create a Design Notes file
(in the appropriate _notes folder) that corresponds to the page design file.

Customizing the appearance of dialog boxes

The dialog box layouts for objects, commands, and behaviors are specified as HTML forms; they
reside in HTML files in the Configuration folder within the Dreamweaver application folder. You
edit these forms as you would edit any form in Dreamweaver. For more information, see
Dreamweaver Help (Help > Using Dreamweaver).

Note: Remember that in a multiuser operating system, you should edit copies of configuration files in
your user Configuration folder rather than editing Dreamweaver configuration files. For more
information, see “Multiuser Configuration folders” on page 25.

32 Chapter 2: Extending Dreamweaver

To change the appearance of a dialog box:

1 In Dreamweaver, select Edit > Preferences, and then select the Code Rewriting category.
2 Unselect the Rename Form Items when Pasting option.

Unselecting this option ensures that form items retain their original names when you copy and
paste them.

3 Click OK to close the Preferences dialog box.
4 On your disk, find the appropriate HTM file in the Configuration/Objects, Configuration/

Commands, or Configuration/Behaviors folders.

5 Make a copy of the file somewhere other than the Configuration folder.
6 Open the copy in Dreamweaver, edit the form, and save it.
7 Quit Dreamweaver.
8 Copy the changed file back to the Configuration folder in place of the original. (It’s a good idea

to first make a backup of the original, so you can restore it later if needed.)

9 Restart Dreamweaver to see the changes.

You should change only the appearance of the dialog box, not how it works; it must still contain
the same types of form elements with the same names, so that the information Dreamweaver
obtains from the dialog box can still be used in the same way.

For example, the Comment object takes text input from a text area in a dialog box and uses a
simple JavaScript function to turn that text into an HTML comment and insert the comment
into your document. The form that describes the dialog box is in the Comment.htm file in the
Configuration/Objects/Invisibles folder. You can open that file and change the size and other
attributes of the text area, but if you remove the
name

attribute, the Comment object does not work properly.

textarea tag entirely, or change the value of its

Changing the default file type

By default, Dreamweaver shows all the file types it recognizes in the File > Open dialog box. You
can use a pop-up menu in that dialog box to limit the display to certain types of files. If most of
your work involves a specific file type (such as ASP files), you can change the default display.
Whatever file type is listed on the first line of the Dreamweaver Extensions.txt file becomes
the default.

Note: If you want to see all file types in the File > Open dialog box (even the files Dreamweaver can’t
open), you must select All Files (*.*). This is different from All Documents, which shows only the files
Dreamweaver can open.

To change the Dreamweaver default File > Open file type:

1 Make a backup copy of the Extensions.txt file in the Configuration folder.
2 Open Extensions.txt in Dreamweaver or in a text editor.
3 Cut the line corresponding to the new default and paste it at the beginning of the file so it

becomes the first line of the file.

4 Save the file.
5 Restart Dreamweaver.

To see the new default, select File > Open, and look at the pop-up menu of file types.

Customizing Dreamweaver 33

To add new file types to the menu in the File > Open dialog box:

1 Make a backup copy of the Extensions.txt file in the Configuration folder.
2 Open Extensions.txt in Dreamweaver or a text editor.
3 Add a new line for each new file type. In capital letters, enter the filename extensions that the

new file type can have, separated by commas; then add a colon and a brief descriptive phrase to
show in the pop-up menu for file types that appears in the File > Open dialog box. For example,
for JPEG files, enter the following:

JPG,JPEG,JFIF:JPEG Image Files

4 Save the file.
5 Restart Dreamweaver.

To see the changes, select File > Open, and click the pop-up menu of file types.

Customizing the interpretation of third-party tags

Server-side technologies such as ASP, ColdFusion, JSP, and PHP use special non-HTML code in
HTML files; servers create and serve HTML content based on that code. When Dreamweaver
encounters non-HTML tags, it compares them with information in its third-party tag files, which
define how Dreamweaver reads and displays non-HTML tags.

For example, ASP files contain—in addition to regular HTML—ASP code for the server to
interpret. ASP code looks almost like an HTML tag, but is marked by a pair of delimiters: it
begins with

<% and ends with %>. The Dreamweaver Configuration/ThirdPartyTags folder

contains a file named Tags.xml, which describes the format of various third-party tags, including
ASP code, and defines how Dreamweaver displays that code. Because of the way ASP code is
specified in Tags.xml, Dreamweaver doesn’t try to interpret anything between the delimiters;
instead, in the Document window’s Design view, it simply displays an icon indicating ASP code.
Your own tag database files can define how Dreamweaver reads and displays your tags. Create a
new tag database file for each set of tags, to tell Dreamweaver how to display the tags.

Note: This section explains how to define the way Dreamweaver displays a custom tag, but doesn’t
describe how to provide a way to edit the content or properties of a custom tag. For information on
how to create a Property inspector to inspect and change the properties of a custom tag, see

Chapter 12, “Property Inspectors,” on page 217.

Each tag database file defines the name, type, content model, rendering scheme, and icon for one
or more custom tags. You can create any number of tag database files, but all of them must reside
in the Configuration/ThirdPartyTags folder to be read and processed by Dreamweaver. Tag
database files have the .xml file extension.

Tip: If you are working on several unrelated sites at once (for example, as a freelance developer), you
can put all the tag specifications for a particular site in one file. Then simply include that tag database
file with the custom icons and Property inspectors that you hand over to the people who will maintain
the site.

You define a tag specification with an XML tag called tagspec. For example, the following code
describes the specification for a tag named

<tagspec tag_name="happy" tag_type="nonempty" render_contents="false"

content_model="marker_model" icon="happy.gif" icon_width="18"
icon_height="18"></tagspec>

34 Chapter 2: Extending Dreamweaver

happy:

You can define two kinds of tags using tagspec: normal HTML-style tags and string-delimited
tags. String-delimited tags start with one string and end with another string; they’re like empty
HTML tags (such as

happy tag example is a normal HTML-style tag; it starts with an opening <happy> tag, contains

data between opening and closing tags, and ends with a closing
string-delimited tag, the tag specification would include the

img) in that they don’t surround content and don’t have closing tags. The

</happy> tag. (If the tag were a

start_string and end_string

attributes.) An ASP tag is a string-delimited tag; it starts with the string <% and ends with the
string

%>, and it has no closing tag.

The following information describes the attributes and valid values for the

tagspec tag.

Attributes marked with an asterisk (*) are ignored for string-delimited tags. Optional attributes
are marked in the attribute lists with curly braces (

{}); all attributes not marked with curly braces

are required.

<tagspec>

Description

Provides information about a third-party tag.

Attributes

tag_name

, {tag_type}, {render_contents}, {content_model}, {start_string},

{end_string}, {detect_in_attribute}, {parse_attributes}, icon, icon_width,
icon_height, {equivalent_tag}, {is_visual}, {server_model}

• tag_name is the name of the custom tag. For string-delimited tags, tag_name is used only to

determine whether a given Property inspector can be used for the tag. If the first line of the
Property inspector contains this tag name with an asterisk on each side, then the inspector can
be used for tags of this type. For example, the tag name for ASP code is
inspectors that can examine ASP code should have

*ASP* on the first line. For information on

ASP; Property

the Property inspector API, see Chapter 12, “Property Inspectors,” on page 217.

• tag_type determines whether the tag is empty (as with img), or whether it contains anything

between its opening and closing tags (as with
(nonstring-delimited) tags. It’s ignored for string-delimited tags because they’re always empty.
Valid values are

"empty" and "nonempty".

code). This attribute is required for normal

• render_contents determines whether the contents of the tag should appear in the Document

window’s Design view or whether the specified icon appears instead. This attribute is required
for nonempty tags and ignored for empty tags. (Empty tags have no content.) This attribute
applies only to tags that appear outside of attributes; the contents of tags that appear inside the
values of attributes of other tags are not rendered. Valid values are

"true" or "false".

Customizing Dreamweaver 35

• content_model describes what kinds of content the tag can contain and where in an HTML

file the tag can appear. Valid values are
and

"script_model":

■ block_model specifies that the tag can contain block-level elements such as div and p, and

that the tag can appear only in the body section or inside other body-content tags such as

div, layer, or td.

■ head_model specifies that the tag can contain text content and that it can appear only in the

HEAD section.

■ marker_model specifies that the tag can contain any valid HTML code, and that it can

appear anywhere in an HTML file. The HTML validator in Dreamweaver ignores tags that
are specified as marker_model. However, the validator doesn’t ignore the contents of such a
tag; so even though the tag itself can appear anywhere, the contents of the tag may result in
invalid HTML in certain places. For example, plain text can’t appear (outside of a valid head
element) in the head section of a document, so you can’t place a marker_model tag that
contains plain text in the head section. (To place a custom tag containing plain text in the
head section, specify the tag’s content model as head_model instead of marker_model.) Use
marker_model for tags that should be displayed inline (inside a block-level element such as
p or div—for example, inside a paragraph). If the tag should be displayed as a paragraph of
its own, with line breaks before and after it, don’t use this model.

■ script_model lets the tag exist anywhere between the opening and closing HTML tags of a

document. When Dreamweaver encounters a tag with this model, it ignores all of the tag’s
content. Used for markup (such as certain ColdFusion tags) that Dreamweaver
shouldn’t parse.

"block_model", "head_model", "marker_model",

• start_string specifies a delimiter that marks the beginning of a string-delimited tag. String

delimited tags can appear anywhere in the document where a comment can appear.
Dreamweaver does not parse tags or decode entities or URLs between

end_string. This attribute is required if end_string is specified.

start_string and

• end_string specifies a delimiter that marks the end of a string-delimited tag. This attribute is

required if

start_string is specified.

• detect_in_attribute indicates whether to ignore everything between start_string and

end_string (or between opening and closing tags if those strings are not defined) even when

those strings appear inside attribute names or values. You should generally set this to

"true"

for string-delimited tags; the default is "false". For example, ASP tags sometimes appear
inside attribute values, and sometimes contain quotation marks ("); because the ASP tag
specification specifies

detect_in_attribute="true", Dreamweaver ignores the ASP tags,

including the internal quotation marks, when they appear inside attribute values.

• parse_attributes indicates whether to parse the attributes of the tag. If this is set to "true"

(the default), Dreamweaver parses the attributes; if it’s set to
everything until the next closing angle bracket that appears outside quotation marks. For
example, this attribute should be set to

"false" for a tag such as cfif (as in <cfif a is 1>,

which Dreamweaver cannot parse as a set of attribute name/value pairs).

"false", Dreamweaver ignores

• icon specifies the path and filename of the icon associated with the tag. This attribute is

required for empty tags, and for nonempty tags whose contents do not appear in the
Document window’s Design view.

• icon_width specifies the width of the icon in pixels.

• icon_height specifies the height of the icon in pixels.

36 Chapter 2: Extending Dreamweaver

• equivalent_tag specifies simple HTML equivalents for certain ColdFusion form-related

tags. Not intended for use with other tags.

• is_visual indicates whether the tag has a direct visual effect on the page. For example, the

ColdFusion tag

"true"); the ColdFusion tag cfset is specified as having is_visual set to "false". Visibility

for server markup tags is controlled by the Invisible Elements category of the Preferences dialog
box; visibility for visual server markup tags can be set independent of visibility for nonvisual
server markup tags.

cfgraph doesn’t specify a value for is_visual (so the value defaults to

• server_model if specified, indicates that the tagspec tag applies only on pages belonging to

the specified server model. If server_model is not specified, the
pages. For example, the delimiters for ASP and JSP tags are the same, but the
JSP specifies a server_model of

"JSP", so when Dreamweaver encounters code with the

appropriate delimiters on a JSP page, it displays a JSP icon. When it encounters such code on a
non-JSP page, it displays an ASP icon.

Contents

None (empty tag).

Container

None.

Example

<tagspec tag_name="happy" tag_type="nonempty" render_contents="false"

content_model="marker_model" icon="happy.gif" icon_width="18"
icon_height="18"></tagspec>

How custom tags appear in the Design view

tagspec tag applies on all

tagspec tag for

How custom tags appear in the Design view of the Document window depends on the values of
the

tag_type and render_contents attributes of the tagspec tag. (See “Customizing the

interpretation of third-party tags” on page 34.) If the value of

specified in the

render_contents is "false", the icon appears as it would for an empty tag. The following

example shows how an instance of the

<p>This is a paragraph that includes an instance of the <code>happy</code>
tag (<happy>Joe</happy>).</p>

icon attribute appears. If the value of tag_type is "nonempty" but the value of

happy tag defined earlier might appear in the HTML:

tag_type is "empty", the icon

Because render_contents is set to "false" in the tag specification, the contents of the happy
tag (the word Joe) are not rendered; instead the start and end tags and their contents appear as a
single icon.

For nonempty tags that have a

render_contents value of "true", the icon does not appear in

the Design view; instead, the contents between the opening and closing tags (such as the text
between the tags in

tags</mytag>

<mytag>This is the contents between the opening and closing

) appears. If View > Invisible Elements is enabled, the content is highlighted using
the third-party tag color specified in Highlighting preferences. (Highlighting applies only to tags
defined in tag database files.)

Customizing Dreamweaver 37

To change the highlighting color of third-party tags:

1 Select Edit > Preferences, and select the Highlighting category.
2 Click the Third-Party Tags color box to display the color picker.
3 Select a color, and click OK to close the Preferences dialog box. For information about selecting

a color, see Dreamweaver Help (Help > Using Dreamweaver).

Avoiding rewriting third-party tags

Dreamweaver corrects certain kinds of errors in HTML code; for details, see Dreamweaver Help
(Help > Using Dreamweaver). By default, Dreamweaver refrains from changing HTML in files
with certain filename extensions, including .asp (ASP), .cfm (ColdFusion), .jsp (JSP), and .php
(PHP). This default is set so that Dreamweaver does not accidentally modify the code contained
in any such non-HTML tags. You can change the Dreamweaver default rewriting behavior so that
it rewrites HTML when it opens such files, and you can add other file types to the list of types
that Dreamweaver does not rewrite.

Dreamweaver encodes certain special characters by replacing them with numerical values when
you enter them in the Property inspector. It’s usually best to let Dreamweaver perform this
encoding because the special characters are more likely to display correctly across platforms and
browsers. However, because such encoding can interfere with third-party tags, you may want to
change the Dreamweaver encoding behavior when you’re working with files containing
third-party tags.

To allow Dreamweaver to rewrite HTML in more kinds of files:

1 Select Edit > Preferences, and select the Code Rewriting category.
2 Select either of the following options:

■ Fix Invalidly Nested and Unclosed Tags

■ Remove Extra Closing Tags

3 Do one of the following:

■ Delete one or more extensions from the list of extensions in the Never Rewrite Code: In

Files with Extensions option.

■ Deselect the Never Rewrite Code: In Files with Extensions option. (Deselecting this option

lets Dreamweaver rewrite HTML in all types of files.)

To add file types that Dreamweaver should not rewrite:

1 Select Edit > Preferences, and select the Code Rewriting category.
2 Select either of the following options:

■ Fix Invalidly Nested and Unclosed Tags

■ Remove Extra Closing Tags

3 Make sure the Never Rewrite Code: In Files with Extensions option is selected, and add the new

file extensions to the list in the text field.

If the new file type doesn’t appear in the file-types pop-up menu in the File > Open dialog box,
you might want to add it to the Configuration/Extensions.txt file. For details, see “Changing the

default file type” on page 33.

38 Chapter 2: Extending Dreamweaver

To turn off Dreamweaver encoding options:

1 Select Edit > Preferences, and select the Code Rewriting category.
2 Deselect either or both Special Characters options.

For information on the other Code Rewriting preferences, see Dreamweaver Help
(Help > Using Dreamweaver).

Working with browser profiles

Browser profiles are the files Dreamweaver uses to check your documents when you run a target
browser check (see Dreamweaver Help [Help > Using Dreamweaver]). Each profile contains
information about the HTML tags and attributes that a particular browser supports. A browser
profile can also contain warnings, error messages, and suggestions for tag substitutions.

Browser profiles are stored in the Configuration/BrowserProfiles folder in the Dreamweaver
application folder. You can edit existing profiles or create new ones using Dreamweaver or a text
editor. It is not necessary to quit Dreamweaver before editing or creating browser profiles.

About browser-profile formatting

Browser profiles follow a specific format. To avoid parsing errors during target browser checks,
follow these rules when editing or creating profiles:

• The first line is reserved for the name of the profile. It must be followed by a single carriage

return. The name on this line appears in the Target Browser Check dialog box and in the target
check report. It must be unique.

• The second line is reserved for the designator PROFILE_TYPE=BROWSER_PROFILE.

Dreamweaver uses this line to determine which documents are browser profiles. Do not change
or move this line.

• Two hyphens (--) at the beginning of a line indicate a comment (that is, the line is ignored

during the target check process). A comment must start at the beginning of a line—you can’t
put two hyphens in the middle of a line.

• You must use a space in the following places:

■ Before the closing angle bracket (>) on the !ELEMENT line

■ After the opening parentheses in a list of values for an attribute

■ Before a closing parentheses in a list of values

■ Before and after each pipe (|) in a list of values.

• You must include an exclamation point (!) without a space before each of the following words:

ELEMENT, ATTLIST, Error, and msg (ELEMENT, !ATTLIST, !Error, !msg ).

• You can include !Error, !Warning, and !Info within the !ELEMENT or the !ATTLIST area.

• !msg messages can contain only plain text.

• HTML comments (!---->) cannot be listed as tags in browser profiles because they interfere

with parsing. Dreamweaver does not report an error for comments because all browsers
support them.

Working with browser profiles 39

The following example shows the syntax for a tag entry:

<!ELEMENT htmlTag NAME="tagName ">
<!ATTLIST htmlTag
unsupportedAttribute1 !Error !msg="The unsupportedAttribute1
attribute of the htmlTag tag is not supported.Try using
supportedAttribute1 for a similar effect."
supportedAttribute1
supportedAttribute2 (validValue1 |validValue2 |validValue3 )
unsupportedAttribute2 !Error !msg="Don’t ever use the
unsupportedAttribute2 attribute of the htmlTag tag!"
>

The elements shown in this syntax are defined as follows:

• htmlTag is the tag as it appears in an HTML document.

• tagName is an explanatory name for the tag; for example, the name for the HR tag is

“Horizontal Rule.” The
messages; if you do not supply a name,

NAME attribute is optional. If specified, tagName is used in error

htmlTag is used in error messages.

• unsupportedAttribute is an attribute that is not supported. Any tags or attributes not

specifically mentioned as supported attributes are assumed to be unsupported. Specify
unsupported tags or attributes only when you want to create a custom error message.

• supportedAttribute is an attribute that is supported by htmlTag. Only tags listed without

an

!Error designation are considered to be supported by the browser.

• validValue indicates a value that is supported by the attribute.

The following example shows an entry for the
Navigator 3.0:

<!ELEMENT APPLET Name="Java Applet">
<!ATTLIST APPLET
Align (top |middle |bottom |left |right |absmiddle |
absbottom |baseline |texttop )
Alt
Archive
Class !Warning !msg="This browser ignores the CLASS attribute for the APPLET
tag."
Code
Codebase
Height
HSpace
ID !Warning !msg="This browser ignores the ID attribute for the APPLET tag.
Use NAME instead."
Name
Style !Warning !msg="This browser ignores the STYLE attribute for the APPLET
tag."
VSpace
Width
>

APPLET tag that would be accurate for Netscape

40 Chapter 2: Extending Dreamweaver

Creating and editing a browser profile

You can create a browser profile by modifying an existing profile. For example, to create a profile
for a future version of Microsoft Internet Explorer, you can open the profile for the most recent
version of Internet Explorer that has a profile, add any new tags or attributes introduced in the
new version, and save it as a profile for the new version.

Note: Before you create a browser profile for a new version of a browser, check the Macromedia
Exchange for Dreamweaver site at www.macromedia.com/exchange/dreamweaver to see if
Macromedia has supplied a browser profile that you can download and install using the
Extension Manager.

To create or edit a browser profile:

1 Open an existing profile for editing.

If you’re creating a new profile, open the profile that most closely resembles the profile you
want to create, and save the file under a new filename.

2 If you’re creating a new profile, change the name that appears on the first line of text in the file.

(Two profiles cannot have the same name.)

3 Add any new tags or attributes that you know are supported by the browser, using the syntax

shown in “About browser-profile formatting” on page 39.
If you don’t want to receive error messages about a particular unsupported tag, add it to the list

of supported tags. If you do this, save the profile in a separate file with a new filename (such as
Browsername x.x limited). Giving this alternate profile a new name preserves the original
profile with only the tags that are truly supported.

4 Delete any tags or attributes that are not supported by the browser.

This step is probably unnecessary if you are creating a profile for a new version of Netscape
Navigator or Internet Explorer because browsers rarely drop support for tags.

5 Add any custom error messages according to the syntax shown in “About browser-profile

formatting” on page 39.

The profiles that come with Dreamweaver list all supported tags for the specified browsers. To
add a custom error message to a tag, type

!msg = "message" after !Error. The following

example shows information that appears in the Netscape Navigator 3.0 profile (along with
other attributes not shown here):

<!ELEMENT HR name="Horizontal Rule">
<!ATTLIST HR
COLOR !Error
>

To add a custom error message enter !msg= and then your error message in quotation marks
("):

<!ELEMENT HR name="Horizontal Rule">
<!ATTLIST HR
COLOR !Error !msg="Internet Explorer 3.0 supports the COLOR tag in
horizontal rules,but Netscape Navigator 3.0 does not."
>

6 You can use !Error for all error situations, or you can use !Warning or !Info to indicate that

a tag will be ignored but will not actually cause an error.

Working with browser profiles 41

Changing FTP mappings

The FTPExtensionMap.txt file (Windows) and the FTPExtensionMapMac.txt file (Macintosh)
map filename extensions to FTP transfer modes (ASCII or BINARY).

Each line in each of the two files includes a filename extension (such as GIF) and either the word
ASCII or the word BINARY, to indicate which of the two FTP transfer modes should be used
when transferring a file with that extension. On the Macintosh, each line also includes a creator
code (such as DmWr) and a file type (such as TEXT); when you download a file with the given
filename extension, Dreamweaver assigns the specified creator and file type to the file.

If a file that you are transferring doesn’t have a filename extension, Dreamweaver uses the
BINARY transfer mode.

Note: Dreamweaver cannot transfer files in Macbinary mode. If you need to transfer files in
Macbinary mode, you must use another FTP client.

The following example shows a line (from the Macintosh file) that indicates that files with an
.html extension should be transferred in ASCII mode:

HTML DmWr TEXT ASCII

In both the FTPExtensionMap.txt file and FTPExtensionMapMac.txt file (Macintosh), all
elements on a given line are separated by tabs. The extension and the transfer mode are in
uppercase letters.

To change a default setting, edit the file in a text editor.

To add information about a new filename extension:

1 Edit the extension-map file in a text editor.
2 On a blank line, enter the filename extension (in uppercase letters) and press Tab.
3 On the Macintosh, add the creator code, a tab, the file type, and another tab.
4 Enter ASCII or BINARY to set an FTP transfer mode.
5 Save the file.

Extensible document types in Dreamweaver

XML provides a rich system for defining complex documents and data structures. Dreamweaver
uses several XML schemas to organize information about server behaviors, tags and tag libraries,
components, document types, and reference information.

When you create and work with extensions in Dreamweaver, there are many instances in which
you can create or modify existing XML files to manage the data that your extension uses. In many
cases, you can copy an existing file from the appropriate subfolder within the Configuration
folder to use as a template.

42 Chapter 2: Extending Dreamweaver

Document type definition file

The central component of extensible document types is the document type definition file. There
might be several definition files, all of which are located in the Configuration/DocumentTypes
folder. Each definition file contains information about at least one document type. For each
document type, essential information such as server model, color coding style, descriptions, and
so forth, is described.

Note: Do not confuse Dreamweaver document type definition files with the XML document type
definition (DTD). Document type definition files in Dreamweaver contain a set of
elements, each of which defines a predefined collection of tags and attributes that are associated
with a document type. When Dreamweaver starts, it parses the document type definition files and
creates an in-memory database of information regarding all defined document types.

documenttype

Dreamweaver provides an initial document type definition file. This file, named
MMDocumentTypes.xml, contains the document type definitions provided by Macromedia:

Document type Server model Internal type File extensions Previous server

model

ASP.NET C# ASP.NET-

Csharp

ASP.NET VB ASP.NET-VB Dynamic aspx, ascx

ASP JavaScript ASP-JS Dynamic asp

ASP VBScript ASP-VB Dynamic asp

ColdFusion ColdFusion Dynamic cfm, cfml UltraDev 4

ColdFusion Component Dynamic cfc

JSP JSP Dynamic jsp

PHP PHP Dynamic php, php3

Library Item DWExtension lbi

ASP.NET C# Template DWTemplate axcs.dwt

ASP.NET VB Template DWTemplate axvb.dwt

ASP JavaScript
Template

ASP VBScript Template DWTemplate aspvb.dwt

ColdFusion Template DWTemplate cfm.dwt

HTML Template DWTemplate dwt

JSP Template DWTemplate jsp.dwt

PHP Template DWTemplate php.dwt

HTML HTML htm, html

ActionScript Text as

CSharp Text cs

Dynamic aspx, ascx

ColdFusion

DWTemplate aspjs.dwt

Extensible document types in Dreamweaver 43

Document type Server model Internal type File extensions Previous server

model

CSS Text css

Java Text java

JavaScript Text js

VB Text vb

VBScript Text vbs

Text Text txt

EDML XML edml

TLD XML tld

VTML XML vtm, vtml

WML XML wml

XML XML xml

If you need to create a new document type, you can either add your entry to the document
definition file that Macromedia provides (MMDocumentTypes.xml) or add a custom definition
file to the Configuration/DocumentTypes folder.

Note: The NewDocuments subfolder resides in the Configuration/DocumentTypes folder. This
subfolder contains default pages (templates) for each document type.

Structure of document type definition files

The following example shows what a typical document type definition file might look like:

<?xml version="1.0" encoding="utf-8"?>
<documenttypes

xmlns:MMString="http://www.macromedia.com/schemes/data/string/">
<documenttype
id="dt-ASP-JS"
servermodel="ASP-JS"
internaltype="Dynamic"
winfileextension="asp,htm, html"
macfileextension=asp, html"
previewfile="default_aspjs_preview.htm"
file="default_aspjs.htm"
priorversionservermodel="UD4-ASP-JS" >
<title>
<loadString id="mmdocumenttypes_0title" />
</title>
<description>
<loadString id="mmdocumenttypes_0descr" />
</description>
</documenttype>
...
</documenttypes>

Note: Color coding for document types is specified in the XML files that reside in the Configuration/
CodeColoring folder.

44 Chapter 2: Extending Dreamweaver

In the previous example, the loadstring element identifies the localized strings that
Dreamweaver should use for the title and description for ASP-JS type documents. For more
information about localized strings, see “Localized strings” on page 50.

The following table describes the tags and attributes that you can use within a document type
definition file.

Element Type

Required Description Tag Attribute

documenttype

(root)

id

servermodel

Yes Parent node.

Yes Unique identifier across all document type

definition files.

No Specifies the associated server model

(case-sensitive); by default, the following
values are valid:

ASP.NET C#
ASP.NET VB
ASP VBScript
ASP JavaScript
ColdFusion
JSP
PHP MySQL

A call to the getServerModelDisplayName()
functions returns these names. The server
model implementation files are located in the
Configuration/ServerModels folder.

Extension developers can create new server
models extending this list.

Extensible document types in Dreamweaver 45

Element Type

internaltype

dynamicid

winfileextension

Required Description Tag Attribute

Yes A broad classification of how Dreamweaver

treats a file. The

internaltype identifies

whether the Design view is enabled for this
document and handles special cases such as
Dreamweaver templates or extensions.

The following values are valid:

Dynamic
DWExtension

DWTemplate (has special display regions)
HTML

HTML4
Text

XHTML1

(Code view only)

XML

(has special display regions)

(Code view only)

All server model-related document types
should map to

HTML. Script files (such as CSS, JS, VB, and

CS) should map to

internaltype is DWTemplate, you should also

If
specify

Dynamic. HTML should map to

Text.

dynamicid. If you omit dynamicid in this

case, the new blank template that the New
Document dialog box creates is not a
recognized document type by the Server
Behavior or Bindings panel. Instances of this
template are simply an HTML template.

No A reference to the unique identifier of a

dynamic document type. This attribute is
meaningful only when

DWTemplate. This attribute lets you associate a

internaltype is

dynamic template with a dynamic
document type.

Yes The file extension that is associated with the

document type on Windows. You specify
multiple file extensions by using a comma­separated list. The first extension in the list is
the extension that Dreamweaver uses when
the user saves a

documenttype document.

If two nonserver model-associated document
types have the same file extension,
Dreamweaver recognizes the first one as the
document type for the extension.

46 Chapter 2: Extending Dreamweaver

title

(subtag)

description

(subtag)

Element Type

macfileextension

previewfile

file

priorversionservermodel

Required Description Tag Attribute

Yes The file extension that is associated with the

document type on the Macintosh. You specify
multiple file extensions by using a comma­separated list. The first extension in the list is
the extension that Dreamweaver uses when
the user saves a

documenttype document.

If two nonserver model-associated document
types have the same file extension,
Dreamweaver recognizes the first one as the
document type for the extension.

No The file that is rendered in the Preview area of

the New Document dialog box.

Yes The file that is located in the DocumentTypes/

NewDocuments folder that contains template
content for new

documenttype documents.

No If this document’s server model has a

Dreamweaver UltraDev 4 equivalent, specify
the name of the older version of the
server model.

UltraDev 4 ColdFusion is a valid prior
server model.

Yes The string that appears as a category item

under Blank Document in the New Document
dialog box. You can place this string directly in
the definition file or point to it indirectly for
localization purposes. For more information
on localizing this string, see “Localized

strings” on page 50.

Formatting is not allowed, so HTML tags
cannot be specified.

No The string that describes the document type.

You can place this string directly in the
definition file or point to it indirectly for
localization purposes. For more information
on localizing this string, see “Localized

strings” on page 50.

Formatting is allowed, so HTML tags can be
specified.

Note: When the user saves a new document, Dreamweaver examines the list of extensions for the
current platform that are associated with the document type (

macfileextension). Dreamweaver selects the first string in the list and uses it as the default file

winfileextension and

extension. To change this default file extension, you must reorder the extensions in the comma­separated list so the new default is listed first.

Extensible document types in Dreamweaver 47

When Dreamweaver starts, it reads all document type definition files and builds a list of valid
document types. Dreamweaver treats any entries within the definition files that have nonexistent
server models as nonserver model document types. Dreamweaver ignores entries that have bad
contents or IDs that are not unique.

If, while scanning the Configuration/DocumentTypes folder, Dreamweaver finds no document
type definition files or if any of the definition files appear to be corrupt, Dreamweaver closes with
an error message.

Dynamic templates

You can create templates that are based on dynamic document types. These templates are called
dynamic templates. The following two elements are essential to defining a dynamic template:

• The value of the internaltype attribute for the new document type must be DWTemplate.

• The dynamicid attribute must be set, and the value must be a reference to the identifier of an

existing dynamic document type.

The following example defines a dynamic document type:

<documenttype
id="PHP_MySQL"
servermodel="PHP MySQL"
internaltype="Dynamic"
winfileextension="php,php3"
macfileextension="php,php3"
file="Default.php">
<title>PHP</title>
<description><![CDATA[PHP document]]></description>
</documenttype>

Now, you can define the following dynamic template, which is based on this PHP_MySQL dynamic
document type:

<documenttype
id="DWTemplate_PHP"
internaltype="DWTemplate"
dynamicid="PHP_MySQL"
winfileextension="php.dwt"
macfileextension="php.dwt"
file="Default.php.dwt">
<title>PHP Template</title>
<description><![CDATA[Dreamweaver PHP Template document]]></description>
</documenttype>

When a Dreamweaver user creates a new blank template of type DWTemplate_PHP,
Dreamweaver lets the user create PHP server behaviors in the file. Furthermore, when the user
creates instances of the new template, the user can create PHP server behaviors in the instance.

In the previous example, when the user saves the template, Dreamweaver automatically adds a
.php.dwt extension to the file. When the user saves an instance of the template, Dreamweaver
adds the .php extension to the file.

48 Chapter 2: Extending Dreamweaver

Document extensions and file types

By default, Dreamweaver shows all the file types it recognizes in the File > Open dialog box.
After creating a new document type, extension developers need to update the appropriate
Extensions.txt file. If the user is on a multiuser system (such as Windows XP, Windows 2000, or
Mac OS X), the user has another Extensions.txt file in their Configuration folder. The user must
update the Extensions.txt file because it is the instance that Dreamweaver looks for and parses.

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.

For Mac OS X platforms:

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

Macromedia:Dreamweaver MX 2004:Configuration

If Dreamweaver cannot find the Extensions.txt file in the user’s Configuration folder,
Dreamweaver looks for it in the Dreamweaver Configuration folder.

Note: On multiuser platforms, if you edit the copy of Extensions.txt that resides in the Dreamweaver
Configuration folder and not the one in the user’s Configuration folder, Dreamweaver is not aware of
the changes because Dreamweaver parses the copy of the Extensions.txt file in the user’s
Configuration folder, not the file in the Dreamweaver Configuration folder.

Suppose you want to create a new document extension. To create a new document extension, you
can either add the new extension to an existing document type or create a new document type.

To add a new extension to an existing document type:

1 Edit MMDocumentTypes.xml.
2 Add the new extension to the winfileextension and macfileextension attributes of the

existing document type.

To add a new document type:

1 Make a backup copy of the Extensions.txt file in the Configuration folder.
2 Open Extensions.txt in Dreamweaver or a text editor.
3 Add a new line for each new file type. In capital letters, enter the filename extensions that the

new file type can have, separated by commas; then add a colon and a brief descriptive phrase to

show in the pop-up menu for file types that appears in the File > Open dialog box.

For example, for JPEG files, enter

4 Save the Extensions.txt file.
5 Restart Dreamweaver.

JPG,JPEG,JFIF:JPEG Image Files

To see the changes, select File > Open and click the pop-up menu of file types.

Extensible document types in Dreamweaver 49

To change the Dreamweaver default File > 0pen file type:

1 Make a backup copy of the Extensions.txt file in the Configuration folder.
2 Open Extensions.txt in Dreamweaver or a text editor.
3 Cut the line that corresponds to the new default, and paste it at the beginning of the file, to

make it the first line of the file.

4 Save the Extensions.txt file.
5 Restart Dreamweaver.

To see the changes, select File > Open and click the pop-up menu of file types.

Localized strings

Within a document type definition file, the
display title and description for the document type. You can use the

<title> and <description> subtags specify the

MMString:loadstring

directive in the subtags as a placeholder for providing localized strings for the two subtags. This
process is similar to server-side scripting where you specify a particular string to use in your page
by using a string identifier as a placeholder. For the placeholder, you can use a special tag or you
can specify a tag attribute whose value is replaced.

To provide localized strings, perform the following steps:

1 Place the following statement at the beginning of the document type definition file:

<?xml version="1.0" encoding="utf-8"?>

2 Declare the MMString name space in the <documenttypes> tag:

<documenttypes

xmlns:MMString="http://www.macromedia.com/schemes/data/string/">

3 At the location in the document type definition file where you want to provide a localized string,

use the MMString:loadstring directive to define a placeholder for the localized string. You can

specify this placeholder in one of the following ways:

<description>

<loadstring>myJSPDocType/Description</loadstring>

</description>

or

<description>

<loadstring id="myJSPDocType/Description" />

</description>

In these examples, myJSPDocType/Description is a unique string identifier that acts as a

placeholder for the localized string. The localized string is defined in the next step.

4 In the Configuration/Strings folder, create a new XML file (or edit an existing file) that defines

the localized string. For example, the following code, when placed in the Configuration/Strings/

strings.xml file, defines the

<strings>

...

<string id="myJSPDocType/Description"

value=

"<![CDATA[JavaServer Page with <em>special</em> features]]>"

/>

...

</strings>

myJSPDocType/Description string:

50 Chapter 2: Extending Dreamweaver

Note: String identifiers, such as myJSPDocType/Description in the previous example, must be

unique within the application. Dreamweaver, when it starts, parses all XML files within the

Configuration/Strings folder and loads these unique strings.

Rules for document type definition files

Dreamweaver lets document types that are associated with a server model share file extensions.
For example: ASP-JS and ASP-VB can claim .asp as their file extension. (For information on
which server model gets preference, see “canRecognizeDocument()” on page 328.)

Dreamweaver does not let document types that are not associated with a server model share
file extensions.

If a file extension is claimed by two document types where one type is associated with a server
model and the other is not, the latter document type gets preference. Suppose you have a
document type called SAM, which is not associated with a server model, that has a file extension
of .sam, and you add this file extension to the ASP-JS document type. When a Dreamweaver user
opens a file that has a .sam extension, Dreamweaver assigns the SAM document type to it, not
ASP-JS.

Opening a document in Dreamweaver

When a user opens a file, Dreamweaver follows a series of steps to identify the document type
based on the file’s extension.

If Dreamweaver successfully finds a unique document type, Dreamweaver uses that type and
loads the associated server model (if any) for the document that the user is opening. If the user has
selected to use Dreamweaver UltraDev 4 server behaviors, Dreamweaver loads the appropriate
UltraDev 4 server model.

If the file extension maps to more than one document type, Dreamweaver performs the
following actions:

• If a static document type is among the list of document types, it gets preference.

• If all the document types are dynamic, Dreamweaver creates an alphabetical list of the server

models that are associated with these document types and then calls the

canRecognizeDocument() function in each server model (see “canRecognizeDocument()”

on page 328). Dreamweaver collects the return values and determines which server model

returned the highest valued positive integer. The document type whose server model returns

the highest integer is the document type that Dreamweaver assigns to the document being

opened. If, however, more than one server model returns the same integer, Dreamweaver goes

through the alphabetical list of those server models, picks the first in the list, and uses that

document type. For example, if both ASP-JS and ASP-VB claim an ASP document and if their

respective

document to ASP-JS (because, alphabetically, ASP-JS is first).

If Dreamweaver cannot map the file extension to a document type, Dreamweaver opens the
document as a text file.

canRecognizeDocument() functions return equal values, Dreamweaver assigns the

Extensible document types in Dreamweaver 51

52 Chapter 2: Extending Dreamweaver

CHAPTER 3

User Interfaces for Extensions

Most extensions are built to receive information from the user through a user interface (UI).
If you plan to submit your extension for Macromedia certification, you need to follow the
guidelines that are available within the Extension Manager files on the Macromedia Exchange
website (www.macromedia.com/exchange). These guidelines are not intended to limit your
creativity; their purpose is to ensure that certified extensions work effectively within the
Macromedia Dreamweaver MX 2004 UI and that the extension UI design does not detract from
its functionality.

Designing an extension user interface

Typically, you create an extension to perform a task that users encounter frequently. Certain parts
of the task are repetitive and by creating an extension, you can automate them. Some steps in the
task can change, or specific attributes of the code that the extension processes can change. To
receive user inputs for these variable values, you build a UI.

As an example, an extension can automate updates for a web catalog where users periodically need
to change values for image sources, item descriptions, and prices, but the procedures for taking
these values and formatting the information for display on the website remains the same. A simple
extension can automate the formatting while letting users manually input the new, updated values
for the three variables. An advanced extension can automate the process of pulling a set of values
for image sources, item descriptions, and prices directly from a database, with variables for time
intervals input by the user.

The purpose of your extension UI is to receive information that the user inputs to handle the
variable aspects of a repetitive task that the extension performs. Dreamweaver supports HTML
and JavaScript form elements as the basic building blocks for creating extension UI controls and
displays the UI using its own HTML renderer. Therefore, an extension UI can be as simple as an
HTML file that contains a two-column table with text descriptions and form input fields.

Most extension developers design their extension UI after coding most of the functionality of
their extension in JavaScript. After you begin writing code, it is often easy to discern what
variables are necessary and what form inputs can best handle them.

53

Consider the following basic guidelines when you design an extension UI:

• If you want a name for your extension, place the name in the title tag of your HTML file.

Dreamweaver displays the name in the extension title bar.

• Keep text labels on the left side of your UI, aligned right, with text boxes on the right side,

aligned left. This arrangement lets the user’s eyes easily locate the beginning of any text box.

Minimal text can follow the text box as explanation or units of measure.

• Keep checkbox and radio button labels on the right side of your UI, aligned left.

• For readable code, assign logical names to your text boxes. If you use Dreamweaver to create

your extension UI, you can use the Property inspector or the Quick Tag Editor

to the fields.

In a typical scenario, after you create the UI, test the extension code to see that it properly
performs the following UI-related tasks:

to assign names

• Getting the values from the text boxes

• Setting default values for the text boxes or gathering values from the selection

• Applying changes to the user document

Dreamweaver HTML rendering control

For versions through Dreamweaver 4, Dreamweaver rendered more space around form controls
than do Microsoft Internet Explorer and Netscape Navigator. Form controls in extension UIs are
rendered with extra space around them because Dreamweaver uses its HTML rendering engine to
display extension UIs.

Macromedia has improved form-control rendering to more closely match the browsers. To take
advantage of the rendering improvements, you must use one of three new
your extension files, as shown in the following example:

<!DOCTYPE HTML SYSTEM "-//Macromedia//DWExtension layout-engine 5.0//dialog">

DOCTYPE statements in

<!DOCTYPE HTML SYSTEM "-//Macromedia//DWExtension layout-engine5.0//floater">

<!DOCTYPE HTML SYSTEM "-//Macromedia//DWExtension layout-engine5.0//pi">

In most cases, DOCTYPE statements must go on the first line of a document. However, to avoid
conflicts with extension-specific directives that, in previous versions, were required to be on the
first line of a file (such as the comment at the top of a Property inspector file, or the

LOCATION=NONE

order as long as they appear before the opening

directive in a command), DOCTYPE statements and directives can now be in any

html tag.

In addition to letting you make extension UIs more closely match the built-in dialog boxes and
panels, the new

DOCTYPE statements also let you view your extensions in the Dreamweaver Design

view so that you can see them as they would appear when viewed by users.

54 Chapter 3: User Interfaces for Extensions

MENU-

The following examples show the Base Property inspector without the DOCTYPE statement, which
improves form-control rendering, and then with the

DOCTYPE statement.

The Base Property inspector as it appears in Design view without the

The Base Property inspector as it appears in Design view with the

DOCTYPE statement.

DOCTYPE statement (and after a few

adjustments to accommodate the new rendering).

Using custom UI controls in extensions

In addition to the standard HTML form elements, Dreamweaver supports custom controls to
help you create flexible, professional-looking interfaces, as described in the following list:

• Editable select lists (also known as combo boxes) that let you combine the functionality of a

select list with that of a text box

• Database controls that facilitate the display of data hierarchies and fields

• Tree controls that organize information into expandable and collapsible nodes

• Color button controls that let you add color picker interfaces to your extensions

Editable select lists

Extension UIs often contain pop-up lists that are defined using the
you can make pop-up lists in extensions editable by adding
To set a default value, set the editText attribute and the value that you want the select list to
display.

The following example shows the settings for an editable select list:

<select name="travelOptions" style="width:250px" editable="true"

editText="other (please specify)">
<option value="plane">plane</option>
<option value="car">car</option>
<option value=""bus">bus</option>
</select>

When you use select lists in your extensions, check for the presence and value of the editable
attribute. If no value is present, the select list returns the default value of
that the select list is not editable.

select tag. In Dreamweaver,

editable="true" to the select tag.

false, which indicates

Using custom UI controls in extensions 55

As with normal (noneditable) select lists, editable select lists have a selectedIndex property (see

“Objects, properties, and methods of the Dreamweaver DOM” on page 68). This property

returns -1 if the text box is selected.

To read the value of an active editable text box into an extension, read the value of the
property. The
box, the value of the
value has been specified for

Dreamweaver adds the following custom attributes for the

editText property returns the string that the user entered into the editable text

editText attribute, or an empty string if no text has been entered and no

editText.

select tag to control editable

editText

pop-up lists:

Attribute name Description Accepted Values

editable

editText

Note: Editable select lists are available in Dreamweaver.

Declares that the pop-up list has an editable
text area

Holds or sets text within the editable text area A string of any value

A Boolean value of true or false

The following example creates a command that contains an editable select list using common
JavaScript functions:

<html>
<head>

<title>Editable Dropdown Test</title>

<script language="javascript">

function getAlert()

{

var i=document.myForm.mySelect.selectedIndex;
if (i>=0){

alert ("selectedIndex: " + i);

alert("selected text " + document.myForm.mySelect.options[i].text);
}
else{

var i=document.myForm.mySelect_no.selectedIndex;

if (i>=0){

alert ("selectedIndex: " + i);
alert("selected text " +

}

else

}

}
function commandButtons()
{

return new Array("OK", "getAlert()", "Cancel", "window.close()");

}
</script>

</head>

document.myForm.mySelect_no.options[i].text);

alert("nothing is selected");

<body>
<div name="test">
<form name="myForm">
<table>
<tr>
<td>Editable DropDown with default text:</td>

56 Chapter 3: User Interfaces for Extensions

<td><select name="mySelect" editable="true" style="width:150px"

editText="Editable Text">
<option> opt 1 </option>
<option> opt 2 </option>
<option> opt 3 </option>
</select></td></tr>
<tr> <td>Editable DropDown without default text:</td>
<td><select name="mySelect_no" editable="true" style="width:150px">
<option value="1"> opt 1 </option>
<option value="2"> opt 2 </option>
<option value="3"> opt 3 </option>
</select></td></tr>
</table>

</form>
</div>

</body>
</html>

To use this sample, save it to the Dreamweaver Configuration/Commands folder as
EditableSelectTest.htm. Restart Dreamweaver, and select EditableSelectTest from the Commands
menu.

Database controls

Using Dreamweaver, you can extend the HTML

select tag to create a database tree control. You

can also add a variable grid control. The database tree control displays database schema, and the
variable grid control displays tabular information.

Using custom UI controls in extensions 57

The following figure shows an advanced Recordset dialog box that uses a database tree control
and a variable grid control:

Adding a database tree control

The database tree control has the following attributes:

Attribute name Description

name

control.style

type

connection

noexpandbuttons

showheaders

Name of the database tree control

Width and height, in pixels

Type of control

Name of the database connection that is defined in the Connection
Manager; if empty, the control is empty.

When this attribute is specified, the tree control does not draw the Plus (+) or
collapse Minus (-)
This attribute is useful for drawing multicolumn list controls.

When this attribute is specified, the tree control displays a header at the top
that lists the name of each column.

Any option tags that are placed inside the

58 Chapter 3: User Interfaces for Extensions

indicators or the associated arrows on the Macintosh.

select tag are ignored.

To add a database tree control to a dialog box, you can use the following sample code with
appropriate substitutions for quoted variables:

<select name="DBTree" style="width:400px;height:110px" ¬
type="mmdatabasetree" connection="connectionName" noexpandbuttons

showHeaders></select>

You can change the connection attribute to retrieve selected data and display it in the tree.
You can use the

DBTreeControl attribute as a JavaScript wrapper object for the new tag.

For more examples, see the DBTreeControlClass.js file in the Configuration/Shared/Common/
Scripts folder.

Adding a variable grid control

The variable grid control has the following attributes:

Attribute name Description

name

style

type

columns

columnWidth

Name of the variable grid control

Width of the control, in pixels

Type of control

Each column must have a name, separated by a comma

Width of each column, each separated by a comma. The columns are of
equal width if you do not specify widths.

The following example adds a simple variable grid control to a dialog box:

<select name="ParamList" style="width:515px;" ¬
type="mmparameterlist columns"="Name,SQL Data ¬
Type,Direction,Default Value,Run-time Value" size=6></select>

The following example creates a variable grid control that is 500 pixels wide, with five columns of
various widths:

<select name="ParamList" style="width:500px;" ¬
type=mmparameterlist columns="Name,SQL Data Type,Direction, ¬
Default Value,Run-time Value" columnWidth="100,25,11," size=6>¬
</select>

This example creates two blank columns that are 182 pixels wide. (The specified columns total

136. The total width of the variable grid control is 500. The remaining space after the first three
columns are placed is 364. Two columns remain; 364 divided by 2 is 182.)

This variable grid control also has a JavaScript wrapper object that should be used to access and
manipulate the variable grid control’s data. You can find the implementation in the
GridControlClass.js file in the Configuration/Shared/MM/Scripts/Class folder.

Using custom UI controls in extensions 59

Adding tree controls

Tree controls display data in a hierarchical format and let users expand and collapse nodes in the
tree. The

MM:TREECONTROL tag lets you create tree controls for any type of information; unlike the

database tree control that is described in “Adding a database tree control” on page 58, no
association with a database is required. The Dreamweaver Keyboard Shortcuts editor uses the tree
control, as shown in the following figure:

60 Chapter 3: User Interfaces for Extensions

Creating a tree control

The

MM:TREECONTROL tag creates a tree control and can use one or more tags to add structure, as

described in the following list:

• MM:TREECOLUMN is an empty, optional tag that defines a column in the tree control.

• MM:TREENODE is an optional tag that defines a node in the tree. It is a nonempty tag that can

contain only other

MM:TREECONTROL tags have the following attributes:

Attribute name Description

name

size

theControl

multiple

style

noheaders

MM:TREECOLUMN tags have the following attributes:

Attribute name Description

name

value

width

align

state

MM:TREENODE tags.

Name of the tree control

Optional. Number of rows that show in the control; default is 5 rows

Optional. If the number of nodes in the theControl attribute exceeds the
value of the size attribute, scrollbars appear

Optional. Allows multiple selections; default is single-selection

Optional. Style definition for height and width of tree control; if specified,
takes precedence over the

Optional. Specifies that the column headers should not appear

Name of the column

String to appear in column header

Width of the column in pixels (percentage not supported); default is 100

Optional. Specifies whether the text in the column should be aligned left,
right, or center; default is left

Specifies whether the column is visible or hidden

size attribute

For readability,

TREECOLUMN tags should follow immediately after the MM:TreeControl tag, as

shown in the following example:

<MM:TREECONTROL name="tree1">
<MM:TREECOLUMN name="Column1" width="100" state="visible">
<MM:TREECOLUMN name="Column2" width="80" state="visible">
...
</MM:TREECONTROL>

Using custom UI controls in extensions 61

The MM:TREENODE attributes are described in the following table:

Attribute name Description

name

value

state

selected

icon

Name of the node

Contains the content for the given node. For more than one column, this is a
pipe-delimited string. To specify an empty column, place a single space
character before the pipe (|).

Specifies that the node is expanded or collapsed with the strings

"expanded" or "collapsed".

You can select multiple nodes by setting this attribute on more than one tree
node, if the tree has a MULTIPLE attribute.

Optional. The index of built-in icon to use, starting with 0:
0 = no icon; 1 = DW document icon; 2 = Multidocument icon

For example, the following tree control has all its nodes expanded:

<mm:treecontrol name="test" style="height:300px;width:300px">

<mm:treenode value="rootnode1" state="expanded">
<mm:treenode value="node1" state="expanded"></mm:treenode>
<mm:treenode value="node3" state="expanded"></mm:treenode>
</mm:treenode>

<mm:treenode value="rootnode2" state="expanded">
<mm:treenode value="node2" state="expanded"></mm:treenode>
<mm:treenode value="node4" state="expanded"></mm:treenode>
</mm:treenode>

</mm:treecontrol>

Manipulating content within a tree control

Tree controls and the nodes within them are implemented as HTML tags. They are parsed by
Dreamweaver and stored in the document tree. These tags can be manipulated in the same way as
any other document node. For more information on

DOM functions and methods, see Chapter 4,

“The Dreamweaver Document Object Model,” on page 67.

Adding nodes To add a node to an existing tree control programmatically, set the innerHTML

property of the

HTML

property of a tree node creates a nested node.

MM:TREECONTROL tag or one of the existing MM:TREENODE tags. Setting the inner

The following example adds a node to the top level of a tree:

var tree = document.myTreeControl;
//add a top-level node to the bottom of the tree
tree.innerHTML = tree.innerHTML + ‘<mm:treenode name="node3"¬ value="node3">’;

Adding a child node

To add a child node to the currently selected node set the innerHTML

property of the selected node.

The following example adds a child node to the currently selected node:

var tree = document.myTreeControl;
var selNode = tree.selectedNodes[0];
//deselect the node, so we can select the new one
selnode.removeAttribute("selected");

62 Chapter 3: User Interfaces for Extensions

//add the new node to the top of the selected node’s children
selNode.innerHTML = '<mm:treenode name="item10" value="New item11" ¬ expanded

selected>' + selNode.innerHTML;

Deleting nodes

innerHTML or outerHTML properties.

To delete the currently selected node from the document structure, use the

The following example deletes the entire selected node and any children:

var tree = document.myTreeControl;
var selNode = tree.selectedNodes[0];
selNode.outerHTML = "";

A color button control for extensions

In addition to the standard input types such as text, checkbox, and button, Dreamweaver
supports

Specifying

mmcolorbutton, an additional input type in extensions.

<input type="mmcolorbutton"> in your code causes a color picker to appear in the

UI. You can set the default color for the color picker by setting a value attribute on the input tag.
If you do not set a value, the color picker appears grey by default and the value property of the
input object returns an empty string.

The following example shows a valid

<input type="mmcolorbutton" name="colorbutton" value="#FF0000">
<input type="mmcolorbutton" name="colorbutton" value="teal">

mmcolorbutton tag:

A color button has one event, onChange, which is triggered when the color changes.

You might want to keep a text box and a color picker synchronized. The following example
creates a text box that synchronizes the color of the text box with the color of the color picker:

<input type = "mmcolorbutton" name="fgcolorPicker"

onChange="document.fgcolorText.value=this.value">
<input type = "test" name="fgcolorText"

onBlur="document.fgColorPicker.value=this.value">

In this example, when the user changes the value of the text box and then tabs or clicks
elsewhere, the color picker updates to show the color that is specified in the text box. Whenever
the user selects a new color with the color picker, the text box updates to show the hex value for
that color.

Adding Flash content to Dreamweaver

Flash content (SWF files) can display in the Dreamweaver interface either as part of an object or
command. This Flash support is especially useful if you build extensions that use Flash forms,
animations, ActionScript or other Flash content.

Basically, you leverage the ability for Dreamweaver objects and commands to display dialogs
(see Chapter 6, “Insert Bar Objects,” on page 113 for more information about building objects
and Chapter 7, “Commands,” on page 135 for information about commands) using the
with the

object tag to embed your Flash content in a Dreamweaver dialog box.

Adding Flash content to Dreamweaver 63

form tag

A simple Flash dialog box example

In this example, you use Dreamweaver to create a new command that displays a SWF file called
myFlash.swf when the user clicks the command in the Commands menu. For specific
information about creating commands before trying this example, see the information about
commands in Extending Dreamweaver.

Note: This example assumes you already have a SWF file called myFlash.swf in the Configuration/
Commands folder of your Dreamweaver application installation folder. To test this with your own
SWF file, save the SWF file to the application Commands folder, and substitute your filename in all
instances of myFlash.swf.

In Dreamweaver, open a new basic HTML file (this will be your Command definition file).
Between the opening and closing

title tags, enter My Flash Movie so the head of your page

reads as follows:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>My Flash Movie</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>

Now, save the file as My Flash Movie.htm in the application Configuration/Commands folder
(but do not close the file yet). You save the file at this point so you can embed your Flash content
with a relative path, otherwise Dreamweaver will try to use an absolute path.

Back in the HTML document, between the opening and closing
closing

form tag. Then, within the form tags, use the Insert > Media > Flash menu option to add

body tags, add an opening and

your Flash content to the Command definition file. When prompted, select the SWF file in the
Commands folder, and click OK. Your Command definition file should now look like the
following example (of course, the

width and height attributes might differ, depending on your

SWF file properties):

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>My Flash Movie</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>

<body>
<body>
<form>
<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://

download.macromedia.com/pub/shockwave/cabs/flash/

swflash.cab#version=6,0,29,0" width="200" height="100">
<param name="movie" value="myFlash.swf">
<param name="quality" value="high">
<embed src="myFlash.swf" quality="high" pluginspage="http://

www.macromedia.com/go/getflashplayer" type="application/x-shockwave-flash"

width="200" height="100"></embed>
</object>
</form>
</body>
</html>

64 Chapter 3: User Interfaces for Extensions

Save the file again. Next, exit and restart Dreamweaver. Select the Command > My Flash Movie
menu option, and your Flash content appears in a Dreamweaver dialog box, as shown in the
following figure:

This example shows a simple implementation of Dreamweaver’s Flash content support. After you
are familiar with building objects and commands as well as more sophisticated forms, you can
integrate Flash content into your Dreamweaver extensions for a more dynamic user experience.
For more infomation, see Chapter 7, “Commands,” on page 135 about writing a

commandButtons() function to add buttons to the dialog box that displays your Flash content.

Adding Flash content to Dreamweaver 65

66 Chapter 3: User Interfaces for Extensions

CHAPTER 4

The Dreamweaver Document Object Model

In Macromedia Dreamweaver MX 2004, the Document Object Model (DOM) is a critically
important structure for extension builders. It lets you access and manipulate elements within a
user’s document and within the extension file.

A DOM defines the composition of documents that are created using a markup language. By
representing tags and

as objects and properties, the DOM lets programming languages access and manipulate
documents and their components.

The structure of an HTML document can be seen as a document tree. The root is the
and the two largest trunks are the
the

TITLE, STYLE, SCRIPT, ISINDEX, BASE, META, and LINK tags, and offshoots of the BODY tag

include headings (
elements, (

such as

WIDTH, HEIGHT, ALT, and others.

H1, H2, and so on), block-level elements (P, DIV, FORM, and so on), text-level

FONT, BR, IMG, and so on) and other element types. Leaves on these offshoots include

HEAD tag and the BODY tag. Offshoots of the HEAD tag include

In a DOM, the tree structure is preserved and presented as a hierarchy of parent nodes and child
nodes. The root node has no parent, and leaf nodes have no children. At each level within the
HTML structure, the HTML element can be exposed to JavaScript as a node. Using this
structure, you can access the document or any element within it.

In JavaScript, you can call any document object by name or by index, as described in the
following list:

• By name, as in document.myForm.myButton

• By index, as in document.forms[0].elements[1]

Objects with the same name are collapsed into an array. You can access a particular object in the
array by incrementing the index with zero as the origin (for example, the first radio button with
the name

document.myForm.myRadioGroup[0]).

myRadioGroup in the myForm document is referenced as

HTML tag,

67

Which document DOM?

It is important to distinguish between the DOM of the user’s document and the DOM of the
extension. The information in this chapter applies to both types of Dreamweaver documents, but
the way that you reference each DOM is different.

If you are familiar with JavaScript in browsers, you can reference objects in the active document
by writing

document. (for example, document.forms[0]), the same way that you reference

objects in extension files. To reference objects in the user’s document, however, you must call

dw.getDocumentDOM(), dw.createDocument(), or another function that returns a user

document object.

For example, to refer to the first image in the active document, you can write

dw.getDocumentDOM().images[0]. You can also store the document object in a variable and use

that variable in future references, as shown in the following example:

var dom = dw.getDocumentDOM(); //get the dom of the current document

var firstImg = dom.images[0];

firstImg.src = “myImages.gif”;

This kind of notation is common in files throughout the Configuration folder, especially in
command files. For more information about the

dreamweaver.getDocumentDOM() function in the Dreamweaver API Reference.

dw.getDocumentDOM() method, see the

The Dreamweaver DOM

The Dreamweaver DOM contains a subset of objects, properties, and methods from the World
Wide Web Consortium (W3C) (www.w3.org/TR/REC-DOM-Level-1/) DOM Level 1, which
are combined with some properties of the Microsoft Internet Explorer 4.0 DOM.

Objects, properties, and methods of the Dreamweaver DOM

The following table lists the objects, properties, methods, and events that the Dreamweaver
DOM supports. Some properties are read-only when they are accessed as properties of a specific
object. A bullet (•) indicates properties that are read-only when they are used in the listed context.

Object Properties Methods Events

window navigator •

document •
innerWidth •
innerHeight •
screenX •
screenY •

navigator platform • None None

68 Chapter 4: The Dreamweaver Document Object Model

alert()
confirm()
escape()
unescape()
close()
setTimeout()
clearTimeout()
setInterval()
clearInterval()
resizeTo()

onResize

Object Properties Methods Events

document

forms •

(an array of form

objects)

images • (an array of image

getElementsBy TagName()
hasChildNodes()

onLoad

objects)

layers • (an array of LAYER,
ILAYER,

positioned

and absolutely

DIV and SPAN

objects)

objects by name •

child
nodeType •

parentNode •
childNodes •
documentElement •
body •
URL •
parentWindow •

all tags/elements nodeType •

form

parentNode •
childNodes •
tagName •
attributes by name
innerHTML
outerHTML

In addition to the properties that
are available for all tags:

tags:elements • (an array of
button, checkbox, password,
radio, reset, select, submit,
text, file, hidden, image,

getAttribute()
setAttribute()
removeAttribute()
getElementsByTagName()
hasChildNodes()

Only those methods
available to all tags

None

and textarea objects)

mmcolorbutton
child objects by name •

layer

image

button
reset
submit

In addition to the properties that
are available for all tags:

visibility
left
top
width
height
zIndex

In addition to the properties that
are available for all tags:

src

In addition to the properties that
are available for all tags:

form •

Only those methods that
are available to all tags

Only those methods that
are available to all tags

In addition to the methods
that are available for all
tags:

blur()
focus()

None

onMouseOver
onMouseOut
onMouseDown
onMouseUp

onClick

The Dreamweaver DOM 69

Object Properties Methods Events

checkbox
radio

password
text
file
hidden
image (field)
textarea

select

option

mmcolorbutton

In addition to the properties that
are available for all tags:

checked
form •

In addition to the properties that
are available for all tags:

form •
value

In addition to the properties that
are available for all tags:

form •
options • (an array of option

objects)

selectedIndex

In addition to the properties that
are available for all tags:

text

In addition to the properties that

In addition to the methods
that are available for all
tags:

blur()
focus()

In addition to the methods
that are available for all
tags:

blur()
focus()
select()

In addition to the methods
that are available for all
tags:

blur() (Windows only)
focus() (Windows only)

Only those methods that
are available to all tags

None

onClick

onBlur
onFocus

onBlur

(Windows only)

onChange
onFocus

(Windows only)

None

onChange

are available for all tags:

name
value

array
boolean
date
function
math
number
object
string
regexp

text nodeType •

comment nodeType •

NodeList length • item()

NamedNodeMap length • item()

Matches Netscape Navigator

4.0

parentNode •
childNodes •
data

parentNode •
childNodes •
data

Matches Netscape
Navigator 4.0

hasChildNodes()

hasChildNodes()

None

None

None

None

None

70 Chapter 4: The Dreamweaver Document Object Model

Properties and methods of the document object

The following table details the properties and methods of the

document object that are taken

from DOM Level 1 and used in Dreamweaver. A bullet (•) marks read-only properties.

Property or method Return value

nodeType • Node.DOCUMENT_NODE

parentNode • null

parentWindow •

childNodes •

documentElement •

body •

URL •

getElementsByTagName(tagName)

hasChildNodes() true

The JavaScript object that corresponds to the document’s
parent window. (This property is not included in DOM Level 1;
however, Microsoft Internet Explorer 4.0 supports it.)

A NodeList that contains all the immediate children of the

document object. Typically the document has a single child,

the

HTML object.

The JavaScript object that corresponds to the HTML tag.
This property is shorthand for getting the value of

document.childNodes and extracting the HTML tag from

the

NodeList.

The JavaScript object that corresponds to the BODY tag. This
property is shorthand for calling

document.documentElement.childNodes and extracting the
BODY tag from the NodeList. For frameset documents, this

property returns the node for the outermost frameset.

The file://URL for the document or, if the file has not been
saved, an empty string.

A NodeList that can be used to step through tags of type

tagName (for example, IMG, DIV, and so on).

If the

tag argument is LAYER, the function returns all LAYER and

ILAYER tags and all absolutely positioned DIV and SPAN tags.

If the

tag argument is INPUT, the function returns all form

elements. (If a name attribute is specified for one or more

tagName objects, it must begin with a letter, which the HTML

4.01 specification requires, or the length of the array that this
function returns is incorrect.)

The Dreamweaver DOM 71

Properties and methods of HTML tag objects

Every HTML tag is represented by a JavaScript object. Tags are organized in a tree hierarchy,
where tag

content <y>y content</y> more x content.</x>

x is a parent of tag y, if y falls completely within x’s opening and closing tags (<x>x

). For this reason, your code should be

well-formed.

The following table lists the properties and methods of tag objects in Dreamweaver, along with
their return values or explanations. A bullet (•) marks read-only properties.

Property or method Return value

nodeType • Node.ELEMENT_NODE

parentNode •

childNodes •

tagName •

attrName

innerHTML

outerHTML

getAttribute(attrName)

getTranslatedAttribute(attrName)

setAttribute(attrName, attrValue)

removeAttribute(attrName)

The parent tag. If this is the HTML tag, the document
object returns.

A NodeList that contains all the immediate children of the tag.

The HTML name for the tag, such as IMG, A, or BLINK. This
value always returns in uppercase letters.

A string that contains the value of the specified tag attribute.

tag.attrName cannot be used if the attrName attribute is a

reserved word in the JavaScript language (for example,

class). In this case, use getAttribute() and setAttribute().

The source code that is contained between the opening tag
and the closing tag.For example, in the code

b>, World!</p>

, p.innerHTML returns <b>Hello</b>, World!.

<p><b>Hello</

If you write to this property, the DOM tree immediately
updates to reflect the new structure of the document. (This
property is not included in DOM Level 1, but Internet Explorer

4.0 supports it.)

The source code for this tag, including the tag. For the
previous example code,

b>, World!</p>

. If you write to this property, the DOM tree

p.outerHTML returns <p><b>Hello</

immediately updates to reflect the new structure of the
document. (This property is not included in DOM Level 1, but
Internet Explorer 4.0 supports it.)

The value of the specified attribute if it is explicitly specified;

null otherwise.

The translated value of the specified attribute or the same
value that

getAttribute() returns if the attribute’s value is not

translated. (This property is not included in DOM Level 1; it
was added to Dreamweaver 3 to support attribute
translation.)

Does not return a value. Sets the specified attribute to the
specified value: for example,

"image/roses.gif")

.

img.setAttribute("src",

Does not return a value. Removes the specified attribute and
its value from the HTML for this tag.

72 Chapter 4: The Dreamweaver Document Object Model

Property or method Return value

getElementsByTagName(tagName)

A NodeList that can be used to step through child tags of
type

tagName (for example, IMG, DIV, and so on).

tag argument is LAYER, the function returns all LAYER and

If the

ILAYER tags and all absolutely positioned DIV and SPAN tags.

tag argument is INPUT, the function returns all form

If the
elements. (If a name attribute is specified for one or more

tagName objects, it must begin with a letter, which the HTML

4.01 specification requires, or the length of the array that this
function returns is incorrect.)

hasChildNodes()

A Boolean value that indicates whether the tag has
any children.

hasTranslatedAttributes()

A Boolean value that indicates whether the tag has any
translated attributes. (This property is not included in
DOM Level 1; it was added to Dreamweaver 3 to support
attribute translation.)

Properties and methods of text objects

Each contiguous block of text in an HTML document (for example, the text within a
represented by a JavaScript object. Text objects never have children. The following table describes
the properties and methods of text objects that are taken from DOM Level 1 and used in
Dreamweaver. A bullet (•) marks read-only properties.

Property or method Return value

nodeType •

parentNode •

childNodes •

data

hasChildNodes() false

Node.TEXT_NODE

The parent tag

An empty NodeList

The actual text string. Entities in the text are represented as a
single character (for example, the text
returned as

Joseph & I).

Joseph & I is

P tag) is

The Dreamweaver DOM 73

Properties and methods of comment objects

A JavaScript object represents each HTML comment. The following table details the properties
and methods of comment objects that are taken from DOM Level 1 and are used in
Dreamweaver. A bullet (•) marks read-only properties.

Property or method Return value

nodeType •

parentNode •

childNodes •

data

hasChildNodes() false

Node.COMMENT_NODE

The parent tag

An empty NodeList array

The text string between the comment markers
(

<!-- and -->)

The dreamweaver and site objects

Dreamweaver implements the standard objects that are accessible through the DOM and adds
two custom objects:
APIs and in writing extensions. For more information on the methods of the

site objects, see the Dreamweaver API Reference.

dreamweaver and site. These custom objects are widely used within the

dreamweaver and

Properties of the dreamweaver object

The

dreamweaver object has two read-only properties, which are described in the following list:

• The appName property has the value "Dreamweaver".

• The appVersion property has a value of the form

"versionNumber.releaseNumber.buildNumber [languageCode] (platform)".

As an example, the value of the
Dreamweaver MX 2004 is
version is

Note: You can find the version and build number by selecting the Help > About menu item.

"7.0.XXXX [en] (MacPPC)".

appVersion property for the Swedish Windows version of

"7.0.XXXX [se] (Win32)"; the value for the English Macintosh

The appName and appVersion properties were implemented in Dreamweaver 3 and are not
available in earlier versions of Dreamweaver. You might want to check that the user of your
extension has Dreamweaver version 3 or later by checking for the existence of the

appName property.

appVersion or

To find the specific version of Dreamweaver, check first for the existence of appVersion and then
for the version number, as shown in the following example:

if (dreamweaver.appVersion && ¬
dreamweaver.appVersion.indexOf('3.01') != -1){

// execute code
}

74 Chapter 4: The Dreamweaver Document Object Model

The dreamweaver object has a property called systemScript that lets you query the language of
the user’s operating system. Use this property if you need to include special cases in your
extension code for localized operating systems, as shown in the following example:

if (dreamweaver,systemScript && (dreamweaver.systemScript.indexOf('ja')!=-1){

SpecialCase

}

The systemScript property returns the following values for localized operating systems:

Language Value

Japanese

Korean

TChinese

SChinese

ja

ko

zh_tw

zh_cn

Operating systems for all European languages return

'en'.

The site object

site object has no properties. For information about the methods of the site object, see the

The
Dreamweaver API Reference.

The Dreamweaver DOM 75

76 Chapter 4: The Dreamweaver Document Object Model

CHAPTER 5

Customizing Code View

Macromedia Dreamweaver MX 2004 uses two devices in Code view that help you enter code
quickly and make your code readable and accurate. These two devices are Code Hints and Code
Coloring. In addition, Dreamweaver validates your code for the target browsers that you specify
and allows you to change default HTML formatting.

You can customize Code Hints and Code Coloring by modifying the XML files that implement
them. You can add items to the Code Hints menus by adding entries to the CodeHints.xml file.
You can modify color schemes by modifying the code coloring style file, Colors.xml, or you can
change code coloring schemes or add new ones by modifying one of the code coloring syntax files,
such as CodeColoring.xml. You can also modify the cascading style sheet (CSS) profile file for
your target browser to affect how Dreamweaver validates CSS properties and values. You can also
change Dreamweaver’s default HTML formatting through the Preferences dialog box. The
following sections describe how to customize these features.

Code Hints

Code Hints are menus that Dreamweaver opens when you type certain character patterns in the
Code View. Code Hints offer a typing shortcut by providing a list of strings that potentially
complete the string you are typing. If the string you are typing appears in the menu, you can scroll
to it and press Enter or Return to complete your entry. For example, when you type
menu shows a list of tag names. Instead of typing the rest of the tag name, you can select the tag
from the menu to include it in your text.

Dreamweaver loads Code Hints menus from the CodeHints.xml file in the Configuration/
CodeHints folder. You can add Code Hints menus to Dreamweaver by defining them in the
CodeHints.xml file. After Dreamweaver loads the contents of CodeHints.xml, you can also add
new Code Hints menus dynamically through JavaScript. For example, JavaScript code populates
the list of session variables in the Bindings panel. You can use the same code to add a Code Hints
menu, so when a user types
variables. For information on using JavaScript to add or modify a Code Hints menu, see Code
Functions in the Dreamweaver API Reference.

Dreamweaver cannot express some types of Code Hints menus through the XML file or the
JavaScript API. Both the CodeHints.xml file and the JavaScript API expose a useful subset of the
Code Hints engine, but some Dreamweaver functionality is not accessible. For example, there is
no JavaScript hook to open a color picker, so Dreamweaver cannot express the Attribute Values
menu using JavaScript. You can only open a menu of text items from which you can insert text.

Note: When you insert text, the insertion pointer is placed after the inserted string.

"Session." in Code view, Dreamweaver displays a menu of session

<, a pop-up

77

The CodeHints.xml file

The CodeHints.xml file contains the following entities:

• A list of all the menu groups

Dreamweaver displays the list of menu groups when you select the Code Hints category

from the Preferences dialog box. You can open the Preferences dialog box by selecting

Edit > Preferences. Dreamweaver MX provides the following menu groups or types of Code

Hints menus: Tag Names, Attribute Names, Attribute Values, Function Arguments, Object

Methods and Variables, and HTML Entities.

• The description for each menu group

The description appears in the Preferences dialog box for the Code Hints category when you

select the menu group in the list. The description for the selected entry appears below the

menu group list.

• Code Hints menus

A menu consists of a pattern that triggers the Code Hints menu and a list of menu items. For

example, a pattern such as "

The following example shows the format of the CodeHints.xml file:

<codehints>
<menugroup name="HTML Entities" enabled="true" id="CodeHints_HTML_Entities">

<description>

<![CDATA[ When you type a '&', a drop-down menu shows

a list of HTML entities. The list of HTML entities
is stored in Configuration/CodeHints.xml. ]]>

</description>

<menu pattern="&">

<menuitem value="&amp;" texticon="&"/>
<menuitem value="&lt;" icon="lessThan.gif"/>

</menu>
</menugroup>

&" could trigger a menu such as "&", ">", "<".

<menugroup name="Tag Names" enabled="true" id="CodeHints_Tag_Names">

<description>

<![CDATA[ When you type '<', a drop-down menu shows
all possible tag names. You can edit the list of tag
names using the
<a href="javascript:dw.popupTagLibraryEditor()"> Tag Library Editor

</a>]]>

</description>

</menugroup>
<menugroup name="Function Arguments" enabled="true"

id="CodeHints_Function_Arguments">

<description>

...

</description>

<function pattern="ArraySort(array, sort_type, sort_order)"

<function pattern="Response.addCookie(Cookie cookie)"

</menugroup>
<codehints>

78 Chapter 5: Customizing Code View

doctypes="CFML"/>

doctypes="JSP"/>

Code Hints tags

The CodeHints.xml file contains the following tags, which define Code Hints menus. You can
use these tags to define additional Code Hints menus.

<codehints>

Description

The codehints tag is the root of the CodeHints.xml file.

Attributes

None.

Contents

One or more menugroup tags.

Container

None.

Example

<codehints>

<menugroup>

Description

Each menugroup tag corresponds to a type of menu. You can see the menu types that
Dreamweaver defines by selecting the Code Hints category from the Preferences dialog box.
Select Preferences from the Edit menu to display the Preferences dialog box.

You can create a new menu group or add to an existing group. Menu groups are logical collections
of menus that the user might want to enable or disable using the Preferences dialog box.

Attributes

name, enabled, id

• The name attribute is the localized name that appears in the list of menu groups in the Code

Hints category of the Preferences dialog box.

• The enabled attribute indicates whether the menu group is currently checked or enabled. A

menu group that is enabled appears with a check mark next to it in the Code Hints category of

the Preferences dialog box. Assign a

true value to enable the menu group or a false value to

disable a menu group.

• The id attribute is a nonlocalized identifier that refers to the menu group.

Contents

The description, menu, and function tags.

Container

The codehints tag.

Example

<menugroup name=

"Session Variables" enabled="true" id="Session_Code_Hints">

Code Hints 79

<description>

Description

The description tag contains text that Dreamweaver displays when you select the menu group
from the Preferences dialog box. The description text displays below the list of menu groups. The
description text might optionally contain a single

a tag where the href attribute must be a

JavaScript URL that Dreamweaver executes if the user clicks the link. Use the XML CDATA
construct to enclose any special or illegal characters in the string so that Dreamweaver treats them
as text.

Attributes

None.

Contents

Description text.

Container

The menugroup tag.

Example

<description>
<![CDATA[ To add or remove tags and attributes, use the <a

href="javascript:dw.tagLibrary.showTagLibraryEditor()">Tag Library Editor</

a>.
]]>
</description>

<menu>

Description

This tag describes a single pop-up menu. Dreamweaver opens the menu whenever the user types
the last character of the string in the pattern attribute. For example, the menu that shows the
contents of a Session variable might have a pattern attribute that is equal to "

Attributes

pattern, doctypes, casesensitive

Session.".

• The pattern attribute specifies the pattern of typed characters that cause Dreamweaver to

open the Code Hints menu. If the first character of the pattern is a letter, number, or

underscore, Dreamweaver displays the menu only if the character that precedes the pattern in

the document is not a letter, number, or underscore. For example, if the pattern is "

Dreamweaver does not display the menu if the user types "

my_Session.".

• The doctypes attribute specifies that the menu is active only for the specified document types.

This attribute lets you specify different lists of function names for ASP-JavaScript (ASP-JS),

Java Server Pages (JSP), Macromedia ColdFusion, and so on. You can specify the

attribute as a comma-separated list of document type IDs. See the Dreamweaver

Configuration/Documenttypes/MMDocumentTypes.xml file for a list of Dreamweaver

document types.

80 Chapter 5: Customizing Code View

Session.",

doctypes

• The casesensitive attribute specifies whether the pattern is case-sensitive. The possible

values for the

list that you specify for the

the pattern is case-sensitive for some document types but not for others. The value defaults to

false if you omit this attribute. If the casesensitive attribute is a value of true, the Code

Hints menu will open only if the text that the user types exactly matches the pattern that the

pattern attribute specifies. If the

appears even if the pattern is lowercase and the text is uppercase.

Contents

The menuitem tag.

Container

The menugroup tag.

Example

<menu pattern="CGI." doctypes="ColdFusion">

<menuitem>

Description

This tag specifies the text for an item in a Code Hints pop-up menu. The menuitem tag also
specifies the value to insert into the text when you select the item.

Attributes

label, value

casesensitive attribute are true, false, or a subset of the comma-separated

doctypes attribute. The list of document types lets you specify that

casesensitive attribute is a value of false, the menu

{icon}, {texticon}

• The label attribute is the string that Dreamweaver displays in the pop-up menu.

• The value attribute is the string that Dreamweaver inserts in the document when you select

the menu item. When the user selects the item from the menu and presses Enter or Return,

Dreamweaver replaces all the text that the user typed since the menu opened. The user typed

the pattern-matching characters before the menu opened, so Dreamweaver does not insert

them again. For example, if you want to insert

(&), you can define the following

<menu pattern="&">

<menuitem label="&amp;" value="amp;" texticon="&"/>

menu and menuitem tags:

&, which is the HTML entity for ampersand

The value attribute does not include the ampersand (&) character because the user typed it

before the menu opened.

• The icon attribute, which is optional, specifies the path to an image file that Dreamweaver

displays as an icon to the left of the menu text. The location is expressed as a URL, relative to

the Configuration folder.

• The texticon attribute, which is optional, specifies a text string to appear in the icon area

instead of an image file. This attribute is used for the HTML Entities menu.

Contents

None.

Code Hints 81

Container

The menu tag.

Example

<menuitem label="CONTENT_TYPE" value=""CONTENT_TYPE")" icon="shared/

mm/images/hintMisc.gif" />

<function>

Description

This tag replaces the menu tag for specifying function arguments and object methods for a Code
Hints pop-up menu. When you type a function or method name in Code View, Dreamweaver
opens a menu of function prototypes, displaying the current argument in bold. Each time you
type a comma, Dreamweaver updates the menu to display the next argument in bold. For
example, if you typed the function name
Hints menu would display

array, the menu updates to show ArrayAppend(array, value).

ArrayAppend(array, value). After you type the comma following

ArrayAppend in a Coldfusion document, the Code

For object methods, when you type the object name, Dreamweaver opens a menu of the methods
that are defined for that object.

The set of recognized functions is stored in the Dreamweaver Configuration/CodeHints.xml file.

Attributes

pattern, doctypes, casesensitive

• The pattern attribute specifies the name of the function and its argument list. For methods,

the pattern attribute describes the name of the object, the name of the method, and the

method’s arguments. For a function name, the Code Hints menu appears when the user types

functionname(. The menu shows the list of arguments for the function. For an object

method, the Code Hints menu appears when the user types

objectname. (including the

period). This menu shows the methods that have been specified for the object. After that, the

Code Hints menu opens a list of the arguments for the method in the same way it does for

a function.

• The doctypes attribute specifies that the menu is active only for the specified document types.

This attribute lets you specify different lists of function names for ASP-JavaScript (ASP-JS),

Java Server Pages (JSP), Macromedia ColdFusion, and so on. You can specify the

doctypes

attribute as a comma-separated list of document type IDs. For a list of Dreamweaver document

types, see the Dreamweaver Configuration/Documenttypes/MMDocumentTypes.xml file.

• The casesensitive attribute specifies whether the pattern is case-sensitive. The possible

values for the

list that you specify for the doctypes attribute. The list of document types lets you specify that

the pattern is case-sensitive for some document types but not for others. The value defaults to

false if you omit this attribute. If the casesensitive attribute is a value of true, the Code

Hints menu appears only if the text that the user types exactly matches the pattern that the

pattern attribute specifies. If the

appears even if the pattern is lowercase and the text is uppercase.

casesensitive attribute are true, false, or a subset of the comma-separated

casesensitive attribute is a value of false, the menu

Contents

None.

82 Chapter 5: Customizing Code View

Container

The menugroup tag.

Example

// function example
<function pattern="CreateDate(year, month, day)" DOCTYPES="ColdFusion" />
// object method example
<function pattern="application.getAttribute(String name)" DOCTYPES="JSP" />

Code coloring

Dreamweaver lets you customize or extend the code coloring schemes that you see in Code view
so that you can add new keywords to a scheme or add code coloring schemes for new document
types. If you develop 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. Likewise, if you develop a new programming language for an application
server and you want to distribute a new document type to help Dreamweaver users build pages
with it, you could add a code coloring scheme for the document type.

Dreamweaver provides the JavaScript function
enables you to reload code coloring XML files that might have been edited manually. For more
information on this function, see the Dreamweaver API Reference.

To update a code coloring scheme or add a new scheme, you must modify the code coloring
definition files.

Code coloring files

Dreamweaver defines code coloring styles and schemes in XML files that reside in the
Configuration/CodeColoring folder. A code coloring style file defines styles for fields that are
defined in syntax definitions. It has a root node of
defines code coloring syntax and has a root node of

The code coloring style file that Dreamweaver provides is Colors.xml. The code coloring syntax
files that Dreamweaver provides are CodeColoring.xml, ASP JavaScript.xml, ASP VBScript.xml,
ASP.NET CSharp.xml, and ASP.NET VB.xml.

Note: The code coloring in the following examples does not appear on a black and white printed
page. To see the code coloring in these examples, see Dreamweaver Help > Extensions > Extending
Dreamweaver or see the PDF file for Extending Dreamweaver in the Documentation folder on your
installation CD.

dreamweaver.reloadCodeColoring(), which

<codeColors>. A code coloring scheme file

<codeColoring>.

Code coloring 83

The following excerpt from the Colors.xml file illustrates the hierarchy of tags in a code coloring
style file:

<codeColors>

<colorGroup>

<syntaxColor id="CodeColor_HTMLEntity" bold="true" italic="true" />
<syntaxColor id="CodeColor_JavascriptNative" text="#009999" />
<syntaxColor id="CodeColor_JavascriptNumber" text="#FF0000" />

…

<tagColor id="CodeColor_HTMLStyle" text="#990099" />
<tagColor id="CodeColor_HTMLTable" text="#009999" />
<syntaxColor id="CodeColor_HTMLComment" text="#999999" italic="true" />

…

</colorGroup>
</codeColors>

Colors are specified in red-green-blue (RGB) hexadecimal values. For example, the statement

text="009999" in the preceding XML code assigns a blue-green (teal) color to the ID

"CodeColor_JavascriptNative".

The following excerpt from the codeColoring.xml file illustrates the hierarchy of tags in a code
coloring scheme file, and it also illustrates the relationship between the styles file and the scheme
file:

<codeColoring>

<scheme name="Text" id="Text" doctypes="Text" priority="1">

<ignoreTags>Yes</ignoreTags>

<defaultText name="Text" id="CodeColor_TextText" />

<sampleText doctypes="Text">

<![CDATA[Default file syntax highlighting.
The quick brown fox
jumped over the lazy dog.
]]>

</sampleText>

</scheme>

<scheme name="HTML" id="HTML" doctypes="ASP.NET_VB,ASP.NET_CSharp,ASP-JS,ASP-

VB,ColdFusion,CFC,HTML,JSP,EDML,PHP_MySQL,DWTemplate,LibraryItem,WML"

priority="50">

<ignoreCase>Yes</ignoreCase>

<ignoreTags>No</ignoreTags>

<defaultText name="Text" id="CodeColor_HTMLText" />

<defaultTag name="Other Tags" id="CodeColor_HTMLTag" />

<defaultAttribute />

<commentStart name="Comment" id="CodeColor_HTMLComment"><![CDATA[<!--

]]></commentStart>

. . .

<tagGroup name="HTML Anchor Tags" id="CodeColor_HTMLAnchor"
taglibrary="DWTagLibrary_html" tags="a" />
<tagGroup name="HTML Form Tags" id="CodeColor_HTMLForm"

taglibrary="DWTagLibrary_html" tags="select,form,input,option,textarea" />

. . .
</codeColoring>

84 Chapter 5: Customizing Code View

Notice that the syntaxColor and tagColor tags in the Colors.xml file assign color and style
values to an
style to a scheme tag. For example, the

id of "CodeColor_HTMLComment". In the Colors.xml file, the id value of

"

CodeColor_HTMLComment" is assigned a text= value of "#999999", which is gray.

id string value. The id value is then used in the codeColoring.xml file to assign a

defaultTag tag in the codeColoring.xml excerpt has an

Dreamweaver includes the following code coloring schemes: Default, HTML, JavaScript,
ASP_JavaScript, ASP_VBScript, JSP, and ColdFusion. The Default scheme has an
to

"Text". Dreamweaver uses the Default scheme for document types that do not have a defined

id value equal

code coloring scheme.

A code coloring file contains the following tags.

<scheme>

Description

The scheme tag specifies code coloring for a block of code text. You can have multiple schemes
within a file to specify different coloring for different scripting or tag languages. Each scheme has
a priority that lets you nest a block of text with one scheme inside a block of text with a
different scheme.

Attributes

name

, id, priority, doctypes

• name="scheme_name" A string that assigns a name to the scheme. Dreamweaver shows the

scheme name in the Edit Coloring Scheme dialog box. Dreamweaver shows a combination of

scheme name and field name, such as

HTML Comment. If you do not specify a name, the fields

for the scheme do not appear in the Edit Coloring Scheme dialog box. For more information

about the Edit Coloring Scheme dialog box, see “Editing schemes” on page 103.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

• priority="string" The value ranges from "1" to "99". Highest priority is "1". Specifies

the precedence of the scheme. Blocks that are inside blocks with higher priority are ignored;

blocks that are inside blocks with the same or lower priority take precedence. The priority

defaults to "50" if you do not specify one.

• doctypes="doc_list" Optional. Specifies a comma-separated list of the document types to

which this code coloring scheme applies. This value is necessary to resolve conflicts in which

different start and end blocks use the same extensions.

Contents

blockEnd
commentEnd, cssProperty, cssSelector, cssValue, defaultAttribute, defaultText,
endOfLineComment, entity, functionKeyword, idChar1, idCharrest, ignoreCase,
ignoreMMTParam, ignoreTags, keywords, numbers, operators, regexp, sampletext,
searchPattern, stringStart, stringEnd, stringEsc, urlProtocol, urlProtocols

Container

, blockStart, brackets, charStart, charEnd, charEsc, commentStart,

The codeColoring tag.

Example

<scheme name="Text" id="Text" doctypes="Text" priority="1">

Code coloring 85

<blockEnd>

Description

Optional. Text values that delimit the end of the text block for this scheme. The blockEnd and

blockStart tags must be paired and the combination must be unique. Values are not evaluated

as case-sensitive. The
allowed. For more information on

Attributes

blockEnd value can be one character. Multiple instances of this tag are

blockEnd strings, see “Wildcard characters” on page 100.

None.

Example

<blockEnd><![CDATA[--->]]></blockEnd>

<blockStart>

Description

Optional. Specified only if the coloring scheme can be embedded inside a different coloring
scheme. The
unique. Values are not evaluated as case-sensitive. The

blockStart and blockEnd tags must be paired, and the combination must be

blockStart value must be two or more

characters in length. Multiple instances of this tag are allowed. For more information on

blockStart strings, see “Wildcard characters” on page 100. For information on the blockStart
scheme attribute, see “Scheme block delimiter coloring” on page 97.

Attributes

canNest

, doctypes, id, name, scheme

• canNest Specifies whether the scheme can nest inside itself. Values are "Yes" or "No". The

default is

"No".

• doctypes="doc_type1, doc_type2,…" Required. Specifies a comma-separated list of

document types into which you can nest this code coloring scheme. Document types are

defined in the Dreamweaver Configuration/Document Types/MMDocumentTypes.xml file.

• id="id_string" Required when scheme="customText". An identifier string that maps

color and style to this syntax item.

• name="display_name" A string that appears in the Edit Coloring Scheme dialog box when

scheme="customText".

• scheme Required. This defines how the blockStart and blockEnd strings are colored. For

information on the possible values for the scheme attribute, see “Scheme block delimiter

coloring” on page 97.

Example

<blockStart doctypes="ColdFusion,CFC" scheme="innerText"

canNest="Yes"><![CDATA[<!---]]></blockStart>

86 Chapter 5: Customizing Code View

<brackets>

Description

A list of characters that represent brackets.

Attributes

name

, id

• name="bracket_name" A string that assigns a name to the list of brackets.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

Example

<brackets name="Bracket" id="CodeColor_JavaBracket"><![CDATA[{[()]}]]></

brackets>

<charStart>

Description

Contains a text string that represents the delimiter of the start of a character. You must specify the

charStart and charEnd tags in pairs. Multiple charStart … charEnd pairs are allowed.

Attributes

None.

Example

<charStart><![CDATA[']]></charStart>

<charEnd>

Description

Contains a text string that represents the delimiter of the end of a character. You must specify the

charStart and charEnd tags in pairs. Multiple charStart … charEnd pairs are allowed.

Attributes

None.

Example

<charEnd><![CDATA[']]></charEnd>

<charEsc>

Description

Contains a text string that represents an escape character. Multiple charEsc tags are allowed.

Attributes

None.

Example

<charEsc><![CDATA[\]]></charEsc>

Code coloring 87

<commentStart>

Description

A text string that delimits the start of a comment block. You must specify the commentStart and

commentEnd tags in pairs. Multiple commentStart…/commentEnd pairs are allowed.

Attributes

None.

Example

<commentStart><![CDATA[<%--]]></commentStart>

<commentEnd>

Description

A text string that delimits the end of a comment block. You must specify the commentStart and

commentEnd tags in pairs. Multiple commentStart…/commentEnd pairs are allowed.

Attributes

None.

Example

<commentEnd><![CDATA[--%>]]></commentEnd>

<cssImport/>

Description

An empty tag that indicates the code coloring rule for the @import function of the style element
in a CSS.

Attributes

name

, id

name="cssImport_name"

id="id_string" Required. An identifier string that maps color and style to this syntax item.

Example

<cssImport name="@import" id="CodeColor_CSSImport" />

A string that assigns a name to the CSS @import function.

<cssMedia/>

Description

An empty tag that indicates the code coloring rule for the @media function of the style element
in a CSS.

Attributes

name, id

• name="cssMedia_name" A string that assigns a name to the CSS @media function.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

88 Chapter 5: Customizing Code View

Example

<cssMedia name="@media" id="CodeColor_CSSMedia" />

<cssProperty/>

Description

An empty tag that indicates CSS rules and holds code coloring attributes.

Attributes

name

, id

• name="cssProperty_name" A string that assigns a name to the CSS property.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

Code Color Preference

CSS Property

Example

<cssProperty name="Property" id="CodeColor_CSSProperty" />

<cssSelector/>

Description

An empty tag that indicates CSS rules and holds code coloring attributes.

Attributes

name

, id

• name="cssSelector_name" A string that assigns a name to the CSS Selector.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

Example

<cssSelector name="Selector" id="CodeColor_CSSSelector" />

<cssValue/>

Description

An empty tag that indicates CSS rules and holds code coloring attributes.

Attributes

name, id

• name="cssValue_name" A string that assigns a name to the CSS value.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

Example

<cssValue name="Value" id="CodeColor_CSSValue" />

Code coloring 89

<defaultAttribute>

Description

Optional. This tag applies only to tag-based syntax (that is, where ignoreTags="No"). If this tag
is present, then all tag attributes are colored according to the style assigned to this tag. If this tag is
omitted, then attributes are colored the same as the tag.

Attributes

name

• A string that assigns a name to the default attribute.

Example

<defaultAttribute name="Attribute"/>

<defaultTag>

Description

This tag is used to specify the default color and style for tags in a scheme.

Attributes

name

, id

• name="display_name" A string that Dreamweaver displays in the code color editor.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

Example

<defaultTag name="Other Tags" id="CodeColor_HTMLTag" />

<defaultText/>

Description

Optional. If this tag is present, all text that is not defined by any other tag is colored according to
the style assigned to this tag. If this tag is omitted, black text is used.

Attributes

name, id

• name="cssSelector_name" A string that assigns a name to the CSS Selector.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

Example

<defaultText name="Text" id="CodeColor_TextText" />

90 Chapter 5: Customizing Code View

<endOfLineComment>

Description

A text string that delimits the start of a comment that continues until the end of the current line.
Multiple

Attributes

endOfLineComment…/endOfLineComment tags are allowed.

None.

Example

<endOfLineComment><![CDATA[//]]></endOfLineComment>

<entity/>

Description

An empty tag that indicates that HTML special characters should be recognized and hold
coloring attributes.

Attributes

name

, id

• name="entity_name" A string that assigns a name to the entity.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

Example

<entity name="Special Characters" id="CodeColor_HTMLEntity" />

<functionKeyword>

Description

Identifies keywords that define a function. Dreamweaver uses these keywords to perform code
navigation. Multiple

Attributes

name

, id

functionKeyword tags are allowed.

• name="functionKeyword_name" A string that assigns a name to the functionKeyword

block.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

Example

<functionKeyword name="Function Keyword"

id="CodeColor_JavascriptFunction">function</functionKeyword>

Code coloring 91

<idChar1>

Description

A list of characters, each of which Dreamweaver can recognize as the first character in
an identifier.

Attributes

name

, id

• name="idChar1_name" A string that assigns a name to the list of identifier characters.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

Example

<idChar1>_$abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ</idChar1>

<idCharRest>

Description

A list of characters that are to be recognized as the remaining characters in an identifier. If

idChar1 is not specified, all characters of the identifier are validated against this list.

Attributes

name

, id

• name="idCharRest_name" A string that assigns a name to the stringStart block.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

Example

<idCharRest name="Identifier"

id="CodeColor_JavascriptIdentifier">_$abcdefghijklmnopqrstuvwxyzABCDEFGHIJK

LMNOPQRSTUVWXYZ0123456789</idCharRest>

<ignoreCase>

Description

Specifies whether case should be ignored when comparing tokens to keywords. Values are Yes or

No. The default is Yes.

Attributes

None.

Example

<ignoreCase>Yes</ignoreCase>

<ignoreMMTParams>

Description

Specifies whether the MMTInstance:Param, <!-- InstanceParam, or <!-- #InstanceParam tags
should be colored specially. Values are Yes and No; the default is Yes. This handles proper
coloring in pages that use Templates.

92 Chapter 5: Customizing Code View

Attributes

None.

Example

<ignoreMMTParams>No</ignoreMMTParams>

<ignoreTags>

Description

Specifies whether markup tags should be ignored. Values are Yes and No; the default is Yes. Set to

No when syntax is for tag markup language that is delimited by < and >. Set to Yes when syntax is

for a programming language.

Attributes

None.

Example

<ignoreTags>No</ignoreTags>

<isLocked>

Description

Specifies whether the text that is matched by this scheme is locked from being edited in the Code
view. Values are

Attributes

Yes and No. Default is No.

None.

Example

<isLocked>Yes</isLocked>

<keyword>

Description

A string of text that defines a keyword. Multiple keyword tags are allowed. A keyword may start
with any character, but subsequent characters may only be

The code color is specified by the containing

Attributes

keyword tags.

a-z, A-Z, 0-9, _, $, or @.

None.

Example

<keyword>.getdate</keyword>

Code coloring 93

<keywords>

Description

List of keywords for type specified in category attribute. Multiple keywords tags are allowed.

Attributes

name

, id

• name="keywords_name" A string that assigns a name to the list of keywords.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

Contents

<keyword></keyword>

Example

<keywords name="Reserved Keywords" id="CodeColor_JavascriptReserved">

<keyword>break</keyword>
<keyword>case</keyword>

</keywords>

<numbers/>

Description

An empty tag that specifies numbers that should be recognized and also holds color attributes.

Attributes

name

, id

• name="number_name" A string that assigns a name to the numbers tag.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

Example

<numbers name="Number" id="CodeColor_CFScriptNumber" />

<operators>

Description

A list of characters to be recognized as operators.

Attributes

name

, id

• name="operator_name" A string that assigns a name to the list of operator characters.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

Example

<operators name="Operator" id="CodeColor_JavaOperator"><![CDATA[+-*/

%<>!?:=&|^~]]></operators>

94 Chapter 5: Customizing Code View

<regexp>

Description

Specifies a list of searchPattern tags.

Attributes

name

, id, delimiter, escape

• name="stringStart_name" A string that assigns a name to the list of search pattern strings.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

• delimiter The character or string that starts and ends a regular expression.

• escape The character or string that signals special character processing, known as the

“escape” character or string.

Contents

<searchPattern></searchPattern>

Example

<regexp name="RegExp" id="CodeColor_JavascriptRegexp" delimiter="/"

escape="\\">

<searchPattern><![CDATA[(\s*/\e*\\/]]></searchPattern>

<searchPattern><![CDATA[=\s*/\e*\\/]]></searchPattern>

</regexp>

<sampleText>

Description

Representative text that appears in the Preview window of the Edit Coloring Scheme dialog box.
For more information on the Edit Coloring Scheme dialog box, see “Editing schemes”

on page 103.

Attributes

doctypes

• doctypes="doc_type1, doc_type2,...” The document types for which this sample

text appears.

Example

<sampleText doctypes="JavaScript"><![CDATA[/* JavaScript */
function displayWords(arrayWords) {

for (i=0; i < arrayWords.length(); i++) {

// inline comment

alert("Word " + i + " is " + arrayWords[i]);

}
}

var tokens = new Array("Hello", "world");

displayWords(tokens);
]]></sampleText>

Code coloring 95

<searchPattern>

Description

A string of characters that define a regular search pattern using supported wildcard characters.
Multiple

Attributes

searchPattern tags are allowed.

None.

Container

The regexp tag.

Example

<searchPattern><![CDATA[(\s*/\e*\\/]]></searchPattern>

<stringStart>

Description

These tags contain a text string that represents the delimiter of the start of a string. You must
specify the

stringStart and stringEnd tags in pairs. Multiple stringStart … stringEnd

pairs are allowed.

Attributes

name

, id, wrap

• name="stringStart_name" A string that assigns a name to the stringStart block.

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

• wrap="true" or "false". Defines whether code coloring recognizes text strings that wrap to

the next line. The default is

"true".

Example

<stringStart name="Attribute Value" id="CodeColor_HTMLString"><![CDATA["]]></

stringStart>

<stringEnd>

Description

Contains a text string that represents the delimiter of the end of a code string. You must specify
the

stringStart and stringEnd tags in pairs. Multiple stringStart … stringEnd pairs are

allowed.

Attributes

None.

Example

<stringEnd><![CDATA["]]></stringEnd>

96 Chapter 5: Customizing Code View

<stringEsc>

Description

Contains a text string that represents the delimiter of a string escape character. Multiple

stringEsc tags are allowed.

Attributes

None.

Example

<stringEsc><![CDATA[\]]></stringEsc>

<tagGroup>

Description

This tag groups one or more tags to which you can assign a unique color and style.

Attributes

id

, name, taglibrary, tags

• id="id_string" Required. An identifier string that maps color and style to this syntax item.

• name="display_name" A string that Dreamweaver displays in the code color editor.

• taglibrary="tag_library_id" The identifier of the tag library to which this group of

tags belongs.

• tags="tag_list" A tag or comma-separated list of tags that comprise the tag group.

Example

<tagGroup name="HTML Table Tags" id="CodeColor_HTMLTable"

taglibrary="DWTagLibrary_html"

tags="table,tbody,td,tfoot,th,thead,tr,vspec,colw,hspec" />

Scheme block delimiter coloring

The

blockStart scheme attribute controls the coloring of block opening and closing strings or

block delimiters. The following values are valid values for the

Note: Do not confuse the blockStart.scheme attribute with the scheme tag.

blockStart attribute.

innerText

This value tells Dreamweaver to color the block delimiters the same as the default text of the
scheme inside them.

The Template scheme provides an example of the effect of this scheme. The Template scheme
matches blocks of read-only code that are colored gray because you cannot edit them. The block
delimiters, which are the

<!-- #EndEditable --> and <!-- #BeginEditable "..." -->

strings, are also colored gray because they also are not editable.

Code coloring 97

Sample code

<!-- #EndEditable -->

<p><b><font size="+2">header</font></b></p>

<!-- #BeginEditable "test" -->

<p>Here's some editable text </p>

<p> </p>

<!-- #EndEditable -->

Example

<blockStart doctypes="ASP-JS,ASP-VB, ASP.NET_CSharp, ASP.NET_VB,

ColdFusion,CFC, HTML, JSP,LibraryItem,PHP_MySQL"

scheme="innerText"><![CDATA[<!--\s*#BeginTemplate]]></blockStart>

customText

This value tells Dreamweaver to use custom colors to color the block delimiters.

Sample code

The delimiters for blocks of PHP script, which appear in red, provide an example of the effect of
the

customText value:

<?php

if ($loginMsg <> "")

echo $loginMsg;

?>

Example

<blockStart name="Block Delimiter" id="CodeColor_JavaBlock" doctypes="JSP"

scheme="customText"><![CDATA[<%]]></blockStart>

outerTag

The

outerTag value specifies that both the blockStart and blockEnd tags are complete tags and

that Dreamweaver should color them as tags would be colored in the scheme that
surrounds them.

The JavaScript scheme, in which

blockEnd tags, provides an example of this value. This scheme matches blocks of JavaScript code,

<script> and </script> strings are the blockStart and

which does not recognize tags, so the delimiters need to be colored by the scheme that
surrounds them.

Sample code

<script language="JavaScript">

// comment

if (true)

window.alert("Hello, World");

</script>

Example

<blockStart doctypes="PHP_MySQL"

scheme="outerTag"><![CDATA[<script\s+language="php">]]></blockStart>

98 Chapter 5: Customizing Code View

innerTag

This value is identical to the
scheme inside the delimiters. This is currently used for the

outerTag value, except that the tag coloring is taken from the

html tag.

nameTag

This value specifies that the

blockStart string is the opening of a tag and blockEnd string is the

closing of a tag, and these delimiters are to be colored based on the tag settings of the scheme.

This type of scheme displays tags that can be embedded inside other tags, such as the

cfoutput

tag.

Sample code

<input type="text" name="zip"

<cfif newRecord IS "no">

<cfoutput query="employee"> Value="#zip#" </cfoutput>

</cfif>

>

Example

<blockStart doctypes="ColdFusion,CFC"

scheme="nameTag"><![CDATA[<cfoutput\n]]></blockStart>

nameTagScript

This value is identical to the
statements or expressions, as opposed to attribute

nameTag scheme; however, the content is script, such as assignment

name=value pairs.

This type of scheme displays a unique type of tag that contains script inside the tag itself, such as
the ColdFusion

cfset, cfif, and cfifelse tags, and can be embedded inside other tags.

Sample Code

See the sample text for nameTag.

Example

<blockStart doctypes="ColdFusion,CFC"

scheme="nameTagScript"><![CDATA[<cfset\n]]></blockStart>

Scheme processing

Dreamweaver has three basic code coloring modes: CSS mode, Script mode, and Tags mode.

In each mode, Dreamweaver applies code coloring only to particular fields. The following chart
indicates which fields are subject to code coloring in each mode.

Field CSS Tags Script

defaultText X X

defaultTag X

defaultAttribute X

comment X X X

string X X X

Code coloring 99

Field CSS Tags Script

cssProperty X

cssSelector X

cssValue X

character X X

function keyword X

identifier X

number X X

operator X

brackets X X

keywords X X

To make the process of defining schemes more flexible, Dreamweaver lets you specify wildcard
and escape characters.

Wildcard characters

The following is a list of wildcard characters that Dreamweaver supports, along with the strings to
specify them and descriptions of their usage.

Wildcard Escape

string

Wildcard

Wildcard with
escape character

\*

\e*x

Description

Skip all characters in the rule until the character that follows the
wildcard is found. For example, use

name=”\*”>

specified.

Where x is the escape character.
This is the same as the wildcard, except that an escape character

can be specified. The character following any escape character is
ignored. This lets the character following the wildcard appear in the
string without matching the criteria to end wildcard processing.
For example,
expression that starts and ends with a forward slash (/) and can
contain forward slashes that are preceded by a backslash (\).
Because the backslash is the code coloring escape character, you
must precede it with a backslash when you specify it in code
coloring XML.

to match all tags of this type that have the name attribute

/\e*\\/ is used to recognize a JavaScript regular

<MMTInstance:Editable

100 Chapter 5: Customizing Code View