Macromedia DREAMWEAVER 8 User Manual
Dreamweaver API Reference
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
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
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
3
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
4Contents
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
Contents 5
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
6Contents
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.
7
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)
8Introduction
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.
New functions in Dreamweaver 8 9
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)
10 Introduction
Design
The following new CSS, Layout view, and Zoom functions have been added to the Design
chapter:
CSS
■ cssStylePalette.getInternetExplorerRendering() on page 419
■ cssStylePalette.setInternetExplorerRendering() on page 420
■ dom.getElementView() on page 421
■ dom.getShowDivBackgrounds() on page 422
■ dom.getShowDivBoxModel() on page 422
■ dom.getShowDivOutlines() on page 423
■ dom.resetAllElementViews() on page 424
■ dom.setElementView() on page 425
■ dom.setShowDivBackgrounds() on page 426
■ dom.setShowDivBoxModel() on page 426
■ dom.setShowDivOutlines() on page 427
■ dreamweaver.cssStylePalette.applySelectedStyle() on page 428 (added new
argument)
■ dreamweaver.cssStylePalette.deleteSelectedStyle() on page 429 (added new
argument)
■ dreamweaver.cssStylePalette.duplicateSelectedStyle() on page 430 (added
new argument)
■ dreamweaver.cssStylePalette.editSelectedStyle() on page 430 (added new
argument)
■ dreamweaver.cssStylePalette.editSelectedStyleInCodeview() on page 431
■ dreamweaver.cssStylePalette.getDisplayStyles() on page 432
■ dreamweaver.cssStylePalette.renameSelectedStyle() on page 436
■ dreamweaver.cssStylePalette.setDisplayStyles() on page 436
■ dreamweaver.getBlockVisBoxModelColors() on page 437
■ dreamweaver.getBlockVisOutlineProperties() on page 438
■ dreamweaver.getDivBackgroundColors() on page 439
■ dreamweaver.setBlockVisOutlineProperties() on page 439
■ dreamweaver.setDivBackgroundColors() on page 440
New functions in Dreamweaver 8 11
Layout view
■ dom.getShowBlockBackgrounds() on page 459
■ dom.getShowBlockBorders() on page 459
■ dom.getShowBlockIDs() on page 460
■ dom.getShowBoxModel() on page 461
■ dom.setShowBlockBackgrounds() on page 461
■ dom.setShowBlockBorders() on page 462
■ dom.setShowBlockIDs() on page 462
■ dom.setShowBoxModel() on page 463
Zoom
■ dreamweaver.activeViewScale() on page 464
■ dreamweaver.fitAll() on page 465
■ dreamweaver.fitSelection() on page 465
■ dreamweaver.fitWidth() on page 466
■ dreamweaver.zoomIn() on page 466
■ dreamweaver.zoomOut() on page 467
Guide
■ dom.clearGuides() on page 468
■ dom.createHorizontalGuide() on page 468
■ dom.createVerticalGuide() on page 469
■ dom.deleteHorizontalGuide() on page 470
■ dom.deleteVerticalGuide() on page 470
■ dom.guidesColor on page 471
■ dom.guidesDistanceColor on page 471
■ dom.guidesLocked on page 472
■ dom.guidesSnapToElements on page 473
■ dom.guidesVisible on page 473
■ dom.hasGuides() on page 474
■ dom.hasHorizontalGuide() on page 474
■ dom.hasVerticalGuide() on page 475
12 Introduction
Enablers
The following new functions have been added to the Enablers chapter:
■ dreamweaver.canFitSelection() on page 568
■ dreamweaver.canPasteSpecial() on page 568
■ dreamweaver.canZoom() on page 574
■ dreamweaver.cssStylePalette.canApplySelectedStyle() on page 575 (added new
argument)
■ dreamweaver.cssStylePalette.canDeleteSelectedStyle() on page 575 (added
new argument)
■ dreamweaver.cssStylePalette.canDuplicateSelectedStyle() on page 576 (added
new argument)
■ dreamweaver.cssStylePalette.canEditSelectedStyle() on page 577 (added new
argument)
■ dreamweaver.cssStylePalette.canEditSelectedStyleInCodeview() on page 577
■ dreamweaver.cssStylePalette.canRenameSelectedStyle() on page 578
■ dreamweaver.siteSyncDialog.canCompare() on page 582
■ dreamweaver.siteSyncDialog.canMarkDelete() on page 583
■ dreamweaver.siteSyncDialog.canMarkGet() on page 583
■ dreamweaver.siteSyncDialog.canMarkIgnore() on page 584
■ dreamweaver.siteSyncDialog.canMarkPut() on page 584
■ dreamweaver.siteSyncDialog.canMarkSynced() on page 585
■ site.canCompareFiles() on page 589
Removed functions
The following functions have been removed from the Dreamweaver 8 API because the
associated features have been removed from the product.
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).
Errata 13
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.funcname can be abbreviated to
dw.funcname when you are writing code. This manual uses the full dreamweaver. prefix
when defining the function and in the index. Many examples use the
The following naming conventions are used in this guide:
■ You—the developer who is responsible for writing extensions
■ The user—the person using Dreamweaver
dw. prefix, however.
14 Introduction
PART 1
Utility APIs
Learn about the Macromedia Dreamweaver 8 utility functions that you can
use to access local and web-based files, work with Macromedia Fireworks,
and Macromedia Flash objects, manage database connections, create new
database connection types, access JavaBeans fscomponents, and integrate
Dreamweaver with various source control systems.
Chapter 1: The File I/O API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Chapter 2: The HTTP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Chapter 3: The Design Notes API . . . . . . . . . . . . . . . . . . . . . . . . . . .39
Chapter 4: Fireworks Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Chapter 5: Flash Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Chapter 6: The Database API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Chapter 7: The Database Connectivity API . . . . . . . . . . . . . . . . . . 101
Chapter 8: The JavaBeans API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Chapter 9: The Source Control Integration API. . . . . . . . . . . . . . . .117
1
15
CHAPTER 1
The File I/O API
Macromedia Dreamweaver 8 includes a C shared library called DWfile, which gives authors
of objects, commands, behaviors, data translators, floating panels, and Property inspectors the
ability to read and write files on the local file system. This chapter describes the File I/O API
and how to use it.
For general information on how C libraries interact with the JavaScript interpreter in
Dreamweaver, see “C-Level Extensibility” in Extending Dreamweaver.
Accessing configuration folders
On Microsoft Windows 2000 and Windows XP, and Mac OS X platforms, users have their
own copies of configuration files. Whenever Dreamweaver writes to a configuration file,
Dreamweaver writes it to the user’s Configuration folder. Similarly, when Dreamweaver reads
a configuration file, Dreamweaver searches for it first in the user’s Configuration folder and
then in the Dreamweaver Configuration folder. DWfile functions use the same mechanism.
In other words, if your extension reads or writes a file in the Dreamweaver Configuration
folder, your extension also accesses the user’s Configuration folder. For more information
about configuration folders on multiuser platforms, see Extending Dreamweaver.
1
The File I/O API
All functions in the File I/O API are methods of the DWfile object.
DWfile.copy()
Availability
Dreamweaver 3.
17
Description
This function copies the specified file to a new location.
Arguments
originalURL, copyURL
■ The originalURL argument, which is expressed as a file:// URL, is the file you want to
copy.
■ The copyURL argument, which is expressed as a file:// URL, is the location where you
want to save the copied file.
Returns
A Boolean value: true if the copy succeeds; false otherwise.
Example
The following code copies a file called myconfig.cfg to myconfig_backup.cfg:
var fileURL = "file:///c|/Config/myconfig.cfg";
var newURL ="file:///c|/Config/myconfig_backup.cfg";
DWfile.copy(fileURL, newURL);
DWfile.createFolder()
Availability
Dreamweaver 2.
Description
This function creates a folder at the specified location.
Arguments
folderURL
■ The folderURL argument, which is expressed as a file:// URL, is the location of the folder
you want to create.
Returns
A Boolean value: true if the folder is created successfully; false otherwise.
18 The File I/O API
Example
The following code tries to create a folder called tempFolder at the top level of the C drive and
displays an alert box that indicates whether the operation was successful:
var folderURL = "file:///c|/tempFolder";
if (DWfile.createFolder(folderURL)){
alert("Created " + folderURL);
}else{
alert("Unable to create " + folderURL);
}
DWfile.exists()
Availability
Dreamweaver 2.
Description
This function tests for the existence of the specified file.
Arguments
fileURL
■ The fileURL argument, which is expressed as a file:// URL, is the requested file.
Returns
A Boolean value: true if the file exists; false otherwise.
Example
The following code checks for the mydata.txt file and displays an alert message that tells the
user whether the file exists:
var fileURL = "file:///c|/temp/mydata.txt";
if (DWfile.exists(fileURL)){
alert(fileURL + " exists!");
}else{
alert(fileURL + " does not exist.");
}
DWfile.getAttributes()
Availability
Dreamweaver 2.
The File I/O API 19
Description
This function gets the attributes of the specified file or folder.
Arguments
fileURL
■ The fileURL argument, which is expressed as a file:// URL, is the file or folder for which
you want to get attributes.
Returns
A string that represents the attributes of the specified file or folder. If the file or folder does
not exist, this function returns a
null value. The following characters in the string represent
the attributes:
■ R is read only.
■ D is folder.
■ H is hidden.
■ S is system file or folder.
Example
The following code gets the attributes of the mydata.txt file and displays an alert box if the file
is read only:
var fileURL = "file:///c|/temp/mydata.txt";
var str = DWfile.getAttributes(fileURL);
if (str && (str.indexOf("R") != -1)){
alert(fileURL + " is read only!");
}
DWfile.getModificationDate()
Availability
Dreamweaver 2.
Description
This function gets the time when the file was last modified.
Arguments
fileURL
■ The fileURL argument, which is expressed as a file:// URL, is the file for which you are
checking the last modified time.
20 The File I/O API
Returns
A string that contains a hexadecimal number that represents the number of time units that
have elapsed since some base time. The exact meaning of time units and base time is
platform-dependent; in Windows, for example, a time unit is 100ns, and the base time is
January 1st, 1600.
Example
It’s useful to call the function twice and compare the return values because the value that this
function returns is platform-dependent and is not a recognizable date and time. The
following code example gets the modification dates of file1.txt and file2.txt and displays an
alert message that indicates which file is newer:
var file1 = "file:///c|/temp/file1.txt";
var file2 = "file:///c|/temp/file2.txt";
var time1 = DWfile.getModificationDate(file1);
var time2 = DWfile.getModificationDate(file2);
if (time1 == time2){
alert("file1 and file2 were saved at the same time");
}else if (time1 < time2){
alert("file1 older that file2");
}else{
alert("file1 is newer than file2");
}
DWfile.getCreationDate()
Availability
Dreamweaver 4.
Description
This function gets the time when the file was created.
Arguments
fileURL
■ The fileURL argument, which is expressed as a file:// URL, is the file for which you are
checking the creation time.
Returns
A string that contains a hexadecimal number that represents the number of time units that
have elapsed since some base time. The exact meaning of time units and base time is
platform-dependent; in Windows, for example, a time unit is 100ns, and the base time is
January 1st, 1600.
The File I/O API 21
Example
You can call this function and the DWfile.getModificationDate() function on a file to
compare the modification date to the creation date:
var file1 = "file:///c|/temp/file1.txt";
var time1 = DWfile.getCreationDate(file1);
var time2 = DWfile.getModificationDate(file1);
if (time1 == time2){
alert("file1 has not been modified since it was created");
}else if (time1 < time2){
alert("file1 was last modified on " + time2);
}
DWfile.getCreationDateObj()
Availability
Dreamweaver MX.
Description
This function gets the JavaScript object that represents the time when the file was created.
Arguments
fileURL
■ The fileURL argument, which is expressed as a file:// URL, is the file for which you are
checking the creation time.
Returns
A JavaScript Date object that represents the date and time when the specified file was created.
DWfile.getModificationDateObj()
Availability
Dreamweaver MX.
Description
This function gets the JavaScript Date object that represents the time when the file was last
modified.
22 The File I/O API
Arguments
fileURL
■ The fileURL argument, which is expressed as a file:// URL, is the file for which you are
checking the time of the most recent modification.
Returns
A JavaScript Date object that represents the date and time when the specified file was last
modified.
DWfile.getSize()
Availability
Dreamweaver MX.
Description
This function gets the size of a specified file.
Arguments
fileURL
■ The fileURL argument, which is expressed as a file:// URL, is the file for which you are
checking the size.
Returns
An integer that represents the actual size, in bytes, of the specified file.
DWfile.listFolder()
Availability
Dreamweaver 2.
Description
This function gets a list of the contents of the specified folder.
Arguments
folderURL, {constraint}
■ The folderURL argument is the folder for which you want a contents list, which is
expressed as a file:// URL, plus an optional wildcard file mask. Valid wildcards are asterisks
(*), which match one or more characters, and question marks (?), which match a single
character.
The File I/O API 23
■ The constraint argument, if it is supplied, must be either "files" (return only files) or
"directories" (return only folders). If it is omitted, the function returns files and
folders.
Returns
An array of strings that represents the contents of the folder.
Example
The following code gets a list of all the text (TXT) files in the C:/temp folder and displays the
list in an alert message:
var folderURL = "file:///c|/temp";
var fileMask = "*.txt";
var list = DWfile.listFolder(folderURL + "/" + fileMask, "files");
if (list){
alert(folderURL + " contains: " + list.join("\n"));
}
DWfile.read()
Availability
Dreamweaver 2.
Description
This function reads the contents of the specified file into a string.
Arguments
fileURL
■ The fileURL argument, which is expressed as a file:// URL, is the file you want to read.
Returns
A string that contains the contents of the file or a null value if the read fails.
Example
The following code reads the mydata.txt file and, if it is successful, displays an alert message
with the contents of the file:
var fileURL = "file:///c|/temp/mydata.txt";
var str = DWfile.read(fileURL);
if (str){
alert(fileURL + " contains: " + str);
}
24 The File I/O API
DWfile.remove()
Availability
Dreamweaver 3.
Description
This function deletes the specified file.
Arguments
fileURL
■ The fileURL argument, which is expressed as a file:// URL, is the file you want to
remove.
Returns
A Boolean value: true value if the operation succeeds; false otherwise.
Example
The following example uses the DWfile.getAttributes() function to determine whether
the file is read-only and the
function deleteFile(){
var delAnyway = false;
var selIndex = document.theForm.menu.selectedIndex;
var selFile = document.theForm.menu.options[selIndex].value;
if (DWfile.getAttributes(selFile).indexOf('R') != -1){
delAnyway = confirm('This file is read-only. Delete anyway?');
if (delAnyway){
DWfile.remove(selFile);
}
}
}
confirm() function to display a Yes/No dialog box to the user:
DWfile.setAttributes()
Availability
Dreamweaver MX.
Description
This function sets the system-level attributes of a particular file.
The File I/O API 25
Arguments
fileURL, strAttrs
■ The fileURL argument, which is expressed as a file:// URL, identifies the file for which
you are setting the attributes.
■ The strAttrs argument specifies the system-level attributes for the file that is identified
by the
fileURL argument. The following table describes valid attribute values and their
meaning:
Attribute Value Description
R
W
H
V
Read only
Writable (overrides R)
Hidden
Visible (overrides H)
Acceptable values for the
You should not use
them,
R becomes meaningless, and the file is set as writable (W). You should not use H and
V together because they are also mutually exclusive. If you combine them, H becomes
meaningless, and the file is set as visible (
If you specify
H or V without specifying an R or W read/write attribute, the existing read/
write attribute for the file is not changed. Likewise, if you specify
specifying an
H or V visibility attribute, the existing visibility attribute for the file is not
strAttrs string are R, W, H, V, RH, RV, WH, or WV.
R and W together because they are mutually exclusive. If you combine
V).
R or W, without
changed.
Returns
Nothing.
DWfile.write()
Availability
Dreamweaver 2.
Description
This function writes the specified string to the specified file. If the specified file does not yet
exist, it is created.
26 The File I/O API
Arguments
fileURL, text, {mode}
■ The fileURL argument, which is expressed as a file:// URL, is the file to which you are
writing.
■ The text argument is the string to be written.
■ The mode argument, if it is supplied, must be "append". If this argument is omitted, the
contents of the file are overwritten by the string.
Returns
A Boolean value: true if the string is successfully written to the file; false otherwise.
Example
The following code attempts to write the string "xxx" to the mydata.txt file and displays an
alert message if the write operation succeeds. It then tries to append the string
"aaa" to the
file and displays a second alert if the write succeeds. After executing this script, the mydata.txt
file contains the text
var fileURL = "file:///c|/temp/mydata.txt";
if (DWfile.write(fileURL, "xxx")){
alert("Wrote xxx to " + fileURL);
}
if (DWfile.write(fileURL, "aaa", "append")){
alert("Appended aaa to " + fileURL);
}
xxxaaa and nothing else.
The File I/O API 27
28 The File I/O API
CHAPTER 2
The HTTP API
Extensions are not limited to working within the local file system. Macromedia
Dreamweaver 8 provides a mechanism to get information from and send information to a
web server by using hypertext transfer protocol (HTTP). This chapter describes the HTTP
API and how to use it.
How the HTTP API works
All functions in the HTTP API are methods of the MMHttp object. Most of these functions
take a URL as an argument, and most return an object. The default port for URL arguments
is 80. To specify a port other than 80, append a colon and the port number to the URL, as
shown in the following example:
MMHttp.getText("http://www.myserver.com:8025");
For functions that return an object, the object has two properties: statusCode and data.
The
statusCode property indicates the status of the operation; possible values include, but
are not limited to, the following values:
■ 200: Status OK
■ 400: Unintelligible request
■ 404: Requested URL not found
■ 405: Server does not support requested method
■ 500: Unknown server error
■ 503: Server capacity reached
For a comprehensive list of status codes for your server, check with your Internet service
provider or system administrator.
The value of the
in the individual function listings.
data property varies according to the function; possible values are specified
2
29
Functions that return an object also have a callback version. Callback functions let other
functions execute while the web server processes an HTTP request. This capability is useful if
you are making multiple HTTP requests from Dreamweaver. The callback version of a
function passes its ID and return value directly to the function that is specified as its first
argument.
The HTTP API
This section details the functions that are methods of the MMHttp object.
MMHttp.clearServerScriptsFolder()
Availability
Dreamweaver MX.
Description
Deletes the _mmServerScripts folder—and all its files—under the root folder for the current
site, which can be local or remote. The _mmServerScripts folder is located in Configuration/
Connections/Scripts/
Arguments
serverScriptsfolder
■ The serverScriptsfolder argument is a string that names a particular folder, relative to
the Configuration folder on the application server, from which you want to retrieve and
clear server scripts.
server-model/_mmDBScripts folder.
Returns
An object that represents the reply from the server. The data property of this object is a string
that contains the contents of the deleted scripts. If an error occurs, Dreamweaver reports it in
the
statusCode property of the returned object.
Example
The following code, in a menu command file inside the Configuration/Menus folder, removes
all the files from the _mmServerScripts folder when it is called from a menu:
<!-- MENU-LOCATION=NONE -->
<html>
<head>
<TITLE>Clear Server Scripts</TITLE>
<SCRIPT SRC="ClearServerScripts.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript">
30 The HTTP API
Loading...