MACROMEDIA DREAMWEAVER 8-EXTENDING DREAMWEAVER User manual

Extending Dreamweaver

Trademarks
1 Step RoboPDF, ActiveEdit, ActiveTest, Authorware, Blue Sky Software, Blue Sky, Breeze, Breezo, Captivate, Central,
ColdFusion, Contribute, Database Explorer, Director, Dreamweaver, Fireworks, Flash, FlashCast, FlashHelp, Flash Lite,
FlashPaper, Flex, Flex Builder, Fontographer, FreeHand, Generator, HomeSite, JRun, MacRecorder, Macromedia, MXML,
RoboEngine, RoboHelp, RoboInfo, RoboPDF, Roundtrip, Roundtrip HTML, Shockwave, SoundEdit, Studio MX, UltraDev,
and WebHelp are either registered trademarks 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, service marks, or trade names 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.
Opera ® browser Copyright © 1995-2002 Opera Software ASA and its suppliers. All rights reserved.
Copyright © 2005 Macromedia, Inc. 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 written approval from
Macromedia, Inc. Notwithstanding the foregoing, the owner or authorized user of a valid copy of the software with which
this manual was provided may print out one copy of this manual from an electronic version of this manual for the sole
purpose of such owner or authorized user learning to use such software, provided that no part of this manual may be
printed out, reproduced, distributed, resold, or transmitted for any other purposes, including, without limitation,
commercial purposes, such as selling copies of this documentation or providing paid-for support services.
Acknowledgments
Project Management: Charles Nadeau, Robert Berry
Writing: Anne Sandstrom
Editing: Anne Szabla, John Hammett
Production and Editing Management: Patrice OíNeill and Rosana Francescato
Media Design and Production: Adam Barnett, Aaron Begley, Paul Benkman, John Francis, Geeta Karmarkar, Mario Reynoso
Localization Management: Melissa Baerwald
Special thanks to Jay London, Raymond Lim, Alain Dumesny, and the entire Dreamweaver engineering and QA teams.
First Edition: September 2005
Macromedia, Inc.
601 Townsend St.‘
San Francisco, CA 94103

3
Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Installing an extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Creating an extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Additional resources for extension writers . . . . . . . . . . . . . . . . . . . . . . . . .11
What’s new in Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
Conventions used in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
PART 1: CUSTOMIZING DREAMWEAVER
Chapter 1: Customizing Dreamweaver . . . . . . . . . . . . . . . . . . . . . . 17
Ways to customize Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Customizing Dreamweaver in a multiuser environment. . . . . . . . . . . . .27
Working with browser profiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Changing FTP mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Extensible document types in Dreamweaver . . . . . . . . . . . . . . . . . . . . . 35
Chapter 2: Customizing Code View . . . . . . . . . . . . . . . . . . . . . . . 55
Code hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Code coloring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Code validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Changing default HTML formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
PART 2: OVERVIEW OF EXTENDING DREAMWEAVER
Chapter 3: Extending Dreamweaver . . . . . . . . . . . . . . . . . . . . . . 99
Types of Dreamweaver extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Configuration folders and extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . .102
Extension APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Localizing an extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Working with the Extension Manager . . . . . . . . . . . . . . . . . . . . . . . . . . .109

4Contents
Chapter 4: User Interfaces for Extensions. . . . . . . . . . . . . . . . . . . 111
Designing an extension user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Dreamweaver HTML rendering control . . . . . . . . . . . . . . . . . . . . . . . . . .112
Using custom UI controls in extensions . . . . . . . . . . . . . . . . . . . . . . . . . .113
Adding Flash content to Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . 124
Chapter 5: The Dreamweaver Document Object Model . . . . . . 127
Which document DOM? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
The Dreamweaver DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
PART 3: EXTENSION APIS
Chapter 6: Insert Bar Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
How object files work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
The Insert bar definition file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141
Modifying the Insert bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
A simple insert object example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
The Objects API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
Chapter 7: Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
How commands work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Adding commands to the Commands menu . . . . . . . . . . . . . . . . . . . . . 168
A simple command example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
The Commands API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Chapter 8: Menus and Menu Commands . . . . . . . . . . . . . . . . . . 181
About the menus.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Changing menus and menu commands . . . . . . . . . . . . . . . . . . . . . . . . . .191
Menu commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
A simple menu command example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
A dynamic menu example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
The Menu Commands API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Chapter 9: Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
How toolbars work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
A simple toolbar command file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
The toolbar definition file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Toolbar item tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226
Item tag attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
The toolbar command API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238

Contents 5
Chapter 10: Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Site reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Stand-alone reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
The Reports API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Chapter 11: Tag Libraries and Editors . . . . . . . . . . . . . . . . . . . . . . 261
Tag library file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
The Tag Chooser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
A simple example of creating a new tag editor . . . . . . . . . . . . . . . . . . 270
Tag editor APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Chapter 12: Property Inspectors . . . . . . . . . . . . . . . . . . . . . . . . . 279
How Property inspector files work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
A simple Property inspector example . . . . . . . . . . . . . . . . . . . . . . . . . . 282
The Property inspector API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Chapter 13: Floating Panels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
How floating panel files work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
A simple floating panel example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291
The Floating panel API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Chapter 14: Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
How Behaviors work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
A simple behavior example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
The Behaviors API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
Chapter 15: Server Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Dreamweaver architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
A simple server behavior example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
How the Server Behavior API functions are called. . . . . . . . . . . . . . . 326
The Server Behavior API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Server behavior implementation functions . . . . . . . . . . . . . . . . . . . . . . 335
Editing EDML files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Group EDML file tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Participant EDML files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Server behavior techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

6Contents
Chapter 16: Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
How data sources work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
A simple data source example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382
The Data Sources API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Chapter 17: Server Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
How data formatting works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
When the data formatting functions are called . . . . . . . . . . . . . . . . . . 402
The Server Formats API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Chapter 18: Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Component basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .407
Extending the Components panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
How to customize the Components panel . . . . . . . . . . . . . . . . . . . . . . 408
Components panel files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Components panel API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Chapter 19: Server Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
How customizing server models works . . . . . . . . . . . . . . . . . . . . . . . . .423
The Server Model API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Chapter 20: Data Translators . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
How data translators work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
Determining what kind of translator to use . . . . . . . . . . . . . . . . . . . . . .435
Adding a translated attribute to a tag . . . . . . . . . . . . . . . . . . . . . . . . . . .435
Inspecting translated attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .437
Locking translated tags or blocks of code . . . . . . . . . . . . . . . . . . . . . . .437
Creating Property inspectors for locked content . . . . . . . . . . . . . . . . 439
Finding bugs in your translator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
A simple attribute translator example . . . . . . . . . . . . . . . . . . . . . . . . . . 443
A simple block/tag translator example . . . . . . . . . . . . . . . . . . . . . . . . . .447
The Data Translator API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Chapter 21: C-Level Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 457
How integrating C functions works . . . . . . . . . . . . . . . . . . . . . . . . . . . . .457
C-level extensibility and the JavaScript interpreter . . . . . . . . . . . . . . 459
Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
The C-level API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
File Access and Multiuser Configuration API . . . . . . . . . . . . . . . . . . . .470
Calling a C function from JavaScript. . . . . . . . . . . . . . . . . . . . . . . . . . . .479

Contents 7
PART 4: APPENDIX
Appendix: The Shared Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
The Shared folder contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
Using the Shared folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .491
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493

8Contents

9
Introduction
This guide describes the Macromedia Dreamweaver 8 framework and application
programming interface (API) that lets you build extensions to Dreamweaver. It provides
information about how each type of extension works; the API functions that Dreamweaver
calls to implement the various objects, menus, floating panels, server behaviors, and so on,
that make up the features of Dreamweaver; and a simple example of each type of extension.
This guide also explains how to customize Dreamweaver by editing tags in various HTML
and XML files to add menu items or document types, and so on.
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 guide describes the arguments
that Dreamweaver passes to these functions and also the values that Dreamweaver expects
these functions to return.
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.
Background
Most Dreamweaver extensions are written in HTML and JavaScript. This guide assumes that
you are familiar with Dreamweaver, HTML, XML, and JavaScript programming. If you are
implementing C extensions, the guide assumes that you know how to create and use C
dynamic link 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), Macromedia ColdFusion,
or Java Server Pages (JSP).

10 Introduction
Installing an extension
To 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 8/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.
Creating an extension
Before you create a Dreamweaver extension, visit the Macromedia Exchange website at
www.macromedia.com/exchange to see if the extension you plan to create already exists. If
you do not find an extension that meets your needs, you then perform the following steps to
create the extension:
■Determine the type of extension you want to create. For more information about the
extension types, see “Types of Dreamweaver extensions” on page 100.
■Review the documentation for the type of extension you plan to create. To become
familiar with creating that type of extension, it’s a good idea to create the simple extension
example in the appropriate chapter.