MACROMEDIA DREAMWEAVER 8-DREAMWEAVER API Service manual

Dreamweaver API Reference

000_DW_API_Print.book Page 1 Wednesday, July 20, 2005 11:58 AM

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.

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

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

000_DW_API_Print.book Page 2 Wednesday, July 20, 2005 11:58 AM

Contents

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Extending Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Additional resources for extension writers . . . . . . . . . . . . . . . . . . . . . . . . . 8

New functions in Dreamweaver 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Removed functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Errata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Conventions used in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

PART 1: UTILITY APIS

Chapter 1: The File I/O API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Accessing configuration folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

The File I/O API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 2: The HTTP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

How the HTTP API works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

The HTTP API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Chapter 3: The Design Notes API . . . . . . . . . . . . . . . . . . . . . . . . . 39

How Design Notes work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

The Design Notes JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

The Design Notes C API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Chapter 4: Fireworks Integration . . . . . . . . . . . . . . . . . . . . . . . . . 53

The FWLaunch API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Chapter 5: Flash Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

How Flash elements work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Inserting Flash elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

The Flash Objects API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

000_DW_API_Print.book Page 3 Wednesday, July 20, 2005 11:58 AM

4Contents

Chapter 6: The Database API . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69

How Database API functions work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Database connection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Database access functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Chapter 7: The Database Connectivity API . . . . . . . . . . . . . . . . . 101

How to develop a new connection type . . . . . . . . . . . . . . . . . . . . . . . . . .101

The Connection API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

The generated include file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

The definition file for your connection type . . . . . . . . . . . . . . . . . . . . . . 109

Chapter 8: The JavaBeans API. . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

The JavaBeans API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Chapter 9: The Source Control Integration API . . . . . . . . . . . . . .117

How source control integration with Dreamweaver works. . . . . . . . . .118

Adding source control system functionality. . . . . . . . . . . . . . . . . . . . . . .118

The Source Control Integration API required functions . . . . . . . . . . . .119

The Source Control Integration API optional functions . . . . . . . . . . . 126

Enablers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

PART 2: JAVASCRIPT API

Chapter 10: Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

External application functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Global application functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Chapter 11: Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

History functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161

Insert object functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Keyboard functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Menu functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Results window functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Toggle functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Toolbar functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222

Window functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229

Code collapse functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Code view toolbar functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

000_DW_API_Print.book Page 4 Wednesday, July 20, 2005 11:58 AM

Contents 5

Chapter 12: Site. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

Report functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

Site functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Chapter 13: Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Conversion functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Command functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

File manipulation functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Global document functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321

Path functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Selection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

String manipulation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

Translation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

XSLT functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351

Chapter 14: Page Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

Assets panel functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

Behavior functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

Clipboard functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

Library and template functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

Snippets panel functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .391

Chapter 15: Dynamic Documents . . . . . . . . . . . . . . . . . . . . . . . . 397

Server Components functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

Data source functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

Extension Data Manager functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

Live data functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

Server behavior functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408

Server model functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .410

Chapter 16: Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419

CSS functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419

Frame and frameset functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .441

Layer and image map functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

Layout environment functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

Layout view functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453

Zoom functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464

Guide functions and properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468

Table editing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477

000_DW_API_Print.book Page 5 Wednesday, July 20, 2005 11:58 AM

6Contents

Chapter 17: Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489

Code functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489

Find/replace functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494

General editing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500

Print function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520

Quick Tag Editor functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521

Code view functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524

Tag editor and tag library functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544

Chapter 18: Enablers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551

Enablers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599

000_DW_API_Print.book Page 6 Wednesday, July 20, 2005 11:58 AM

Introduction

The Dreamweaver API Reference describes two application programming interfaces (APIs) that

let you perform various supporting tasks when developing Macromedia Dreamweaver 8

extensions and adding program code to your Dreamweaver web pages. These two APIs are the

utility API and the JavaScript API. The utility API contains subsets of related functions that

let you perform specific types of tasks. The utility API includes the following API subsets:

■The File I/O API, which lets you read and write files on the local file system

■The HTTP API, which lets you send and receive information from a web server

■The Design Notes API, which lets you store and retrieve notes about Dreamweaver

documents

■The Fireworks Integration API, which lets you communicate with Macromedia Fireworks

■Flash Integration, which contains information about adding Flash elements to the

Dreamweaver user interface (UI) and details on the Flash Objects API (which lets you

build objects that create Macromedia Flash content)

■The Database API, which lets you access information stored in databases and manage

database connections

■The Database Connectivity API, which lets you create a new connection type and

corresponding dialog boxes for new or existing server models

■The JavaBeans API, which retrieves class names, methods, properties, and events for

JavaBeans that you have defined

■The Source Control Integration API, which lets you write shared libraries to extend the

Dreamweaver Check In/Check Out feature

The extensive JavaScript API lets you perform a diverse set of smaller tasks, many of which are

tasks that a user would perform when creating or editing Dreamweaver documents. These

API functions are grouped by the parts of the Dreamweaver UI that they affect. For example,

the JavaScript API includes Workspace functions, Document functions, Design functions,

and so on. These functions let you perform tasks such as opening a new document, getting or

setting a font size, finding the occurrence of a search string in HTML code, making a toolbar

visible, and much more.

000_DW_API_Print.book Page 7 Wednesday, July 20, 2005 11:58 AM

8Introduction

Background

This book assumes that you are familiar with Dreamweaver, HTML, XML, JavaScript

programming and, if applicable, C programming. 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).

Extending Dreamweaver

To learn about the Dreamweaver framework and the API that enables you to build

Dreamweaver extensions, see Extending Dreamweaver. Extending Dreamweaver describes the

API functions that Dreamweaver calls to implement the objects, menus, floating panels,

server behaviors, and so on, that comprise the various features of Dreamweaver. You can use

those APIs to add objects, menus, floating panels, or other features to the product. Extending

Dreamweaver 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.

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/.

New functions in Dreamweaver 8

The following new functions have been added to the Dreamweaver 8 JavaScript API. The

headings designate the chapters and sections that contain the new functions:

Application

The following Global application functions have been added to the Application chapter.

Global application

■dreamweaver.showPasteSpecialDialog() on page 158

■dreamweaver.showPreferencesDialog() on page 159 (added new argument)

000_DW_API_Print.book Page 8 Wednesday, July 20, 2005 11:58 AM

New functions in Dreamweaver 8 9

Workspace

The following new Window, Code collapse, and Code view toolbar functions have been

added to the Workspace chapter.

Window

■dreamweaver.cascade() on page 231 (added support for the Macintosh)

■dreamweaver.tileHorizontally() on page 239 (added support for the Macintosh)

■dreamweaver.tileVertically() on page 240 (added support for the Macintosh)

Code collapse

■dom.collapseFullTag() on page 241

■dom.collapseSelectedCodeFragment() on page 243

■dom.collapseSelectedCodeFragmentInverse() on page 243

■dom.expandAllCodeFragments() on page 244

■dom.expandSelectedCodeFragments() on page 245

■dreamweaver.htmlInspector.collapseFullTag() on page 245

■dreamweaver.htmlInspector.collapseSelectedCodeFragment() on page 246

■dreamweaver.htmlInspector.collapseSelectedCodeFragmentInverse()

on page 247

■dreamweaver.htmlInspector.expandAllCodeFragments() on page 248

■dreamweaver.htmlInspector.expandSelectedCodeFragments() on page 248

Code view toolbar

■dom.getOpenPathName() on page 249

■dom.getShowHiddenCharacters() on page 249

■dom.setShowHiddenCharacters() on page 250

■dom.source.applyComment() on page 251

■dom.source.removeComment() on page 251

■dreamweaver.htmlInspector.getShowHiddenCharacters() on page 252

■dreamweaver.htmlInspector.setShowHiddenCharacters() on page 253

Site

The following new Site functions have been added to the Site chapter.

000_DW_API_Print.book Page 9 Wednesday, July 20, 2005 11:58 AM

10 Introduction

Site

■dom.getSiteURLPrefixFromDoc() on page 256

■dom.localPathToSiteRelative() on page 257

■dom.siteRelativeToLocalPath() on page 257

■dreamweaver.compareFiles() on page 258

■dreamweaver.siteSyncDialog.compare() on page 259

■dreamweaver.siteSyncDialog.markDelete() on page 260

■dreamweaver.siteSyncDialog.markGet() on page 260

■dreamweaver.siteSyncDialog.markIgnore() on page 261

■dreamweaver.siteSyncDialog.markPut() on page 261

■dreamweaver.siteSyncDialog.markSynced() on page 262

■site.compareFiles() on page 267

■site.getAppURLPrefixForSite() on page 274

■site.getSiteURLPrefix() on page 280

■site.serverActivity() on page 290

■site.siteRelativeToLocalPath() on page 294

Document

The following new File manipulation functions have been added to the Document chapter.

File manipulation

■dreamweaver.getNewDocumentDOM() on page 312 (added new argument)

■MMXSLT.getXMLSchema() on page 351

■MMXSLT.getXMLSourceURI() on page 352

■MMXSLT.launchXMLSourceDialog() on page 353

Page content

The following new Clipboard functions have been added to the Page content chapter:

Clipboard

■dreamweaver.clipPaste() on page 383 (added new argument)

000_DW_API_Print.book Page 10 Wednesday, July 20, 2005 11:58 AM

This manual suits for next models

Table of contents

Other MACROMEDIA Software manuals

MACROMEDIA

MACROMEDIA COLFUSION MX 7-CFML Service manual

MACROMEDIA

MACROMEDIA COLDFUSION MX 61-CFML User manual

MACROMEDIA

MACROMEDIA FLASH 8-USING FLASH VIDEO ENCODER Mounting instructions

MACROMEDIA

MACROMEDIA BREEZE 5 Quick setup guide

MACROMEDIA

MACROMEDIA DIRECTOR MX 2004-USING DIRECTOR Mounting instructions

MACROMEDIA

MACROMEDIA COLDFUSION STUDIO 4.5-USING COLDFUSION... Mounting instructions

MACROMEDIA

MACROMEDIA FLASH MEDIA SERVER 2-INSTALLING FLASH MEDIA SERVER... User manual

MACROMEDIA

MACROMEDIA BREEZE-USING THE MACROMEDIA BREEZE MANAGER Mounting instructions

MACROMEDIA

MACROMEDIA COLDFUSION MX 61-GETTING STARTED BUILDING COLDFUSION... User manual

MACROMEDIA

MACROMEDIA FLASH MX 2004-FLASH JAVASCRIPT DICTIONARY User manual

MACROMEDIA

MACROMEDIA COLDFUSION 4.5-DEVELOPING WEB User manual

MACROMEDIA

MACROMEDIA 38028779 - Macromedia Dreamweaver - Mac Installation and operating instructions

MACROMEDIA

MACROMEDIA CONTRIBUTE 3 - USING AND ADMINISTERING... Mounting instructions

MACROMEDIA

MACROMEDIA DIRECTOR MX-LINGO DICTIONARY User manual

MACROMEDIA

MACROMEDIA FIREWORKS 2-USING FIREWORKS Mounting instructions

MACROMEDIA

MACROMEDIA FLEX-FLEX BUILDER Operation instructions

MACROMEDIA

MACROMEDIA COLDFUSION MX-CLUSTERCATS Mounting instructions

MACROMEDIA

MACROMEDIA FLASH MX 2004 - ACTIONSCRIPT User manual

MACROMEDIA

MACROMEDIA FIREWORKS 8-USING FIREWORKS Mounting instructions

MACROMEDIA

MACROMEDIA FLASH 8-INTRODUCTION TO FLASH LITE 2.X... Reference manual

MACROMEDIA

MACROMEDIA COLDFUSION MX 7.0.2-USING COLDFUSION MX WITH FLEX... Mounting instructions

MACROMEDIA

MACROMEDIA DIRECTOR MX 2004-GETTING STARTED WITH... User manual

MACROMEDIA

MACROMEDIA FLASH 8-ACTIONSCRIPT 2.0 LANGUAGE Service manual

MACROMEDIA

MACROMEDIA FLASH 8-FLASH Operation instructions

Popular Software manuals by other brands

COMPRO

COMPRO COMPROFM manual

Muratec

Muratec OFFICEBRIDGE ONLINE user guide

Oracle

Oracle Contact Center Anywhere 8.1 installation guide

Adobe

Adobe 65007312 - Photoshop Lightroom Programmer's guide

Avaya

Avaya NULL One-X for RIM Blackberry user guide

HP ProLiant BL420c user guide

PS Audio

PS Audio PowerPlay Programming manual

Brady

Brady LOCKOUT PRO 3.0 Administrator's guide

Avaya

Avaya Interaction Center user guide

Texas Instruments

Texas Instruments TI-83 Plus Silver Edition Guide book

Novell

Novell GROUPWISE 8 - INTERNET AGENT manual

Oracle

Oracle Application 9i Configuration guide

Acer

Acer RDM user guide

Canon

Canon Vixia HF21 instruction manual

Canon

Canon ZR950 instruction manual

Samsung

Samsung Auto Backup user manual

Polycom

Polycom Vortex EF2201 Application note

Brocade Communications Systems

Brocade Communications Systems Brocade 8/12c user manual