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
</SCRIPT>
<body onLoad="MMHttp.clearServerScriptsFolder()">
</body>
</html>
MMHttp.clearTemp()
Description
This function deletes all the files in the Configuration/Temp folder, which is located in the
Dreamweaver application folder.
Arguments
None.
Returns
Nothing.
Example
The following code, when saved in a file within the Configuration/Shutdown folder, removes
all the files from the Configuration/Temp folder when the user quits Dreamweaver:
<html>
<head>
<title>Clean Up Temp Files on Shutdown</title>
</head>
<body onLoad="MMHttp.clearTemp()">
</body>
</html>
MMHttp.getFile()
Description
This function gets the file at the specified URL and saves it in the Configuration/Temp folder,
which is located in the Dreamweaver application folder. Dreamweaver automatically creates
subfolders that mimic the folder structure of the server; for example, if the specified file is at
www.dreamcentral.com/people/index.html, Dreamweaver stores the index.html file in the
People folder inside the www.dreamcentral.com folder.
Arguments
URL, {prompt}, {saveURL}, {titleBarLabel}
■ The URL argument is an absolute URL on a web server; if http:// is omitted from the
URL, Dreamweaver assumes HTTP protocol.
The HTTP API 31
■ The prompt argument, which is optional, is a Boolean value that specifies whether to
prompt the user to save the file. If
saveURL is outside the Configuration/Temp folder, a
prompt value of false is ignored for security reasons.
■ The saveURL argument, which is optional, is the location on the user’s hard disk where
the file should be saved, which is expressed as a file:// URL. If prompt is a
true value or
saveURL is outside the Configuration/Temp folder, the user can override saveURL in the
Save dialog box.
■ The titleBarLabel argument, which is optional, is the label that should appear in the
title bar of the Save dialog box.
Returns
An object that represents the reply from the server. The data property of this object is a string
that contains the location where the file is saved, which is expressed as a file:// URL.
Normally, the
statusCode property of the object contains the status code that is received
from the server. However, if a disk error occurs while Dreamweaver is saving the file on the
local drive, the
statusCode property contains an integer that represents one of the following
error codes if the operation is not successful:
■ 1: Unspecified error
■ 2: File not found
■ 3: Invalid path
■ 4: Number of open files limit reached
■ 5: Access denied
■ 6: Invalid file handle
■ 7: Cannot remove current working folder
■ 8: No more folder entries
■ 9: Error setting file pointer
■ 10: Hardware error
■ 11: Sharing violation
■ 12: Lock violation
■ 13: Disk full
■ 14: End of file reached
32 The HTTP API
Example
The following code gets an HTML file, saves all the files in the Configuration/Temp folder,
and then opens the local copy of the HTML file in a browser:
var httpReply = MMHttp.getFile("http://www.dreamcentral.com/¬
people/profiles/scott.html",
false);
if (httpReply.statusCode == 200){
var saveLoc = httpReply.data;
dw.browseDocument(saveLoc);
}
MMHttp.getFileCallback()
Description
This function gets the file at the specified URL, saves it in the Configuration/Temp folder
inside the Dreamweaver application folder, and then calls the specified function with the
request ID and reply result. When saving the file locally, Dreamweaver automatically creates
subfolders that mimic the folder structure of the server; for example, if the specified file is at
www.dreamcentral.com/people/index.html, Dreamweaver stores the index.html file in the
People folder inside the www.dreamcentral.com folder.
Arguments
callbackFunction, URL, {prompt}, {saveURL}, {titleBarLabel}
■ The callbackFunction argument is the name of the JavaScript function to call when the
HTTP request is complete.
■ The URL argument is an absolute URL on a web server; if http:// is omitted from the
URL, Dreamweaver assumes HTTP protocol.
■ The prompt argument, which is optional, is a Boolean value that specifies whether to
prompt the user to save the file. If
Configuration/Temp folder, a
■ The saveURL argument, which is optional, is the location on the user’s hard disk where
the file should be saved, which is expressed as a file:// URL. If prompt is a
saveURL is outside the Configuration/Temp folder, the user can override saveURL in the
Save dialog box.
■ The titleBarLabel argument, which is optional, is the label that should appear in the
title bar of the Save dialog box.
saveURL argument specifies a location outside the
prompt value of false is ignored for security reasons.
true value or
The HTTP API 33
Returns
An object that represents the reply from the server. The data property of this object is a string
that contains the location where the file was saved, which is expressed as a file:// URL.
Normally the
statusCode property of the object contains the status code that is received
from the server. However, if a disk error occurs while Dreamweaver is saving the file on the
local drive, the
statusCode property contains an integer that represents an error code. See
MMHttp.getFile() for a list of possible error codes.
MMHttp.getText()
Availability
Macromedia Dreamweaver UltraDev 4, enhanced in Dreamweaver MX.
Description
Retrieves the contents of the document at the specified URL.
Arguments
URL, {serverScriptsFolder}
■ The URL argument is an absolute URL on a web server. If http:// is omitted from the
URL, Dreamweaver assumes HTTP protocol.
■ The serverScriptsFolder argument is an optional string that names a particular
folder—relative to the Configuration folder on the application server—from which you
want to retrieve server scripts. To retrieve the scripts, Dreamweaver uses the appropriate
transfer protocol (such as FTP, WebDAV, or Remote File System). Dreamweaver copies
these files to the _mmServerScripts subfolder under the root folder for the current site.
If an error occurs, Dreamweaver reports it in the
statusCode property of the returned object.
MMHttp.getTextCallback()
Availability
Dreamweaver UltraDev 4, enhanced in Dreamweaver MX.
Description
Retrieves the contents of the document at the specified URL and passes it to the
specified function.
34 The HTTP API
Arguments
callbackFunc, URL, {serverScriptsFolder}
■ The callbackFunc argument is the JavaScript function to call when the HTTP request is
complete.
■ The URL argument is an absolute URL on a web server; if http:// is omitted from the
URL, Dreamweaver assumes HTTP protocol.
■ The serverScriptsFolder argument is an optional string that names a particular
folder—relative to the Configuration folder on the application server—from which you
want to retrieve server scripts. To retrieve the scripts, Dreamweaver uses the appropriate
transfer protocol (such as FTP, WebDAV, or Remote File System). Dreamweaver retrieves
these files and passes them to the function that
If an error occurs, Dreamweaver MX reports it in the
callbackFunc identifies.
statusCode property of the
returned object.
MMHttp.postText()
Availability
Dreamweaver UltraDev 4, enhanced in Dreamweaver MX.
Description
Performs an HTTP post of the specified data to the specified URL. Typically, the data
associated with a post operation is form-encoded text, but it could be any type of data that the
server expects to receive.
Arguments
URL, dataToPost, {contentType}, {serverScriptsFolder}
■ The URL argument is an absolute URL on a web server; if http:// is omitted from the
URL, Dreamweaver assumes HTTP protocol.
■ The dataToPost argument is the data to post. If the third argument is "application/x-
www-form-urlencoded"
or omitted, dataToPost must be form-encoded according to
section 8.2.1 of the RFC 1866 specification (available at www.faqs.org/rfcs/
rfc1866.html).
■ The contentType argument, which is optional, is the content type of the data to post. If
omitted, this argument defaults to
"application/x-www-form-urlencoded".
The HTTP API 35
■ The serverScriptsFolder argument is an optional string that names a particular
folder—relative to the Configuration folder on the application server—to which you want
to post the data. To post the data, Dreamweaver uses the appropriate transfer protocol
(such as FTP, WebDAV, or Remote File System).
If an error occurs, Dreamweaver reports it in the
Example
statusCode property of the returned object.
In the following example of an MMHttp.postText() function call, assume that a developer
has placed the myScripts.cfm file in a folder named DeployScripts, which is located in the
Configuration folder on the local computer:
MMHttp.postText(
"http://ultraqa8/DeployScripts/myScripts.cfm",
"arg1=Foo",
"application/x-www-form-urlencoded",
"Configuration/DeployScripts/"
)
When Dreamweaver executes this function call, the following sequence occurs:
1. The myScripts.cfm file in the Configuration/DeployScripts folder on the local computer is
copied to another folder named DeployScripts, which is a subfolder of the root folder on
the ultraqa8 website. To deploy the files, Dreamweaver uses the protocol specified in the
site configuration properties.
2. Dreamweaver uses HTTP protocol to post the arg1=Foo data to the web server.
3. As a result of the post request, the web server on ultraqa8 executes the myScripts.cfm script
using the
arg1 data.
MMHttp.postTextCallback()
Availability
Dreamweaver UltraDev 4, enhanced in Dreamweaver MX.
Description
Performs an HTTP post of the text to the specified URL and passes the reply from the server
to the specified function. Typically, the data associated with a post operation is form-encoded
text, but it could be any type of data that the server expects to receive.
36 The HTTP API
Arguments
callbackFunc, URL, dataToPost, {contentType}, {serverScriptsFolder}
■ The callbackFunc argument is the name of the JavaScript function to call when the
HTTP request is complete.
■ The URL argument is an absolute URL on a web server; if http:// is omitted from the
URL, Dreamweaver assumes HTTP protocol.
■ The dataToPost argument is the data to be posted. If the third argument is
"application/x-www-form-urlencoded" or omitted, data must be form-encoded
according to section 8.2.1 of the RFC 1866 specification (available at www.faqs.org/rfcs/
rfc1866.html).
■ The contentType argument, which is optional, is the content type of the data to be
posted. If omitted, this argument defaults to
■ The serverScriptsFolder argument is an optional string. It names a particular folder,
"application/x-www-form-urlencoded".
relative to the Configuration folder on the application server—to which you want to post
the data. To post the data, Dreamweaver uses the appropriate transfer protocol (such as
FTP, WebDAV, or Remote File System). Dreamweaver retrieves these data and passes
them to the function identified by
If an error occurs, Dreamweaver reports it in the
callbackFunc.
statusCode property of the returned object.
The HTTP API 37
38 The HTTP API
CHAPTER 3
The Design Notes API
Macromedia Dreamweaver 8, Macromedia Fireworks, and Macromedia Flash give web
designers and developers a way to store and retrieve extra information about documents—
information such as review comments, change notes, or the source file for a GIF or JPEG—in
files that are called Design Notes.
MMNotes is a C shared library that lets extensions authors read and write Design Notes files.
As with the DWfile shared library, MMNotes has a JavaScript API that lets you call the
functions in the library from objects, commands, behaviors, floating panels, Property
inspectors, and data translators.
MMNotes also has a C API that lets other applications read and write Design Notes files. The
MMNotes shared library can be used independently, even if Dreamweaver is not installed.
For more information about using the Design Notes feature from within Dreamweaver, see
Using Dreamweaver.
How Design Notes work
Each Design Notes file stores information for a single document. If one or more documents in
a folder has an associated Design Notes file, Dreamweaver creates a _notes subfolder where
Design Notes files can be stored. The _notes folder and the Design Notes files that it contains
are not visible in the Site panel, but they appear in the Finder (Macintosh) or Windows
Explorer. A Design Notes filename comprises the main filename plus the .mno extension. For
example, the Design Notes file that is associated with avocado8.gif is avocado8.gif.mno.
Design Notes files are XML files that store information in a series of key/value pairs. The key
describes the type of information that is being stored, and the value represents the
information. Keys are limited to 64 characters.
3
39
The following example shows the Design Notes file for foghorn.gif.mno:
<?xml version="1.0" encoding="iso-8859-1" ?>
<info>
<infoitem key="FW_source" value="file:///C|sites/¬
dreamcentral/images/sourceFiles/foghorn.png" />
<infoitem key="Author" value="Heidi B." />
<infoitem key="Status" value="Final draft, approved ¬
by Jay L." />
</info>
The Design Notes JavaScript API
All functions in the Design Notes JavaScript API are methods of the MMNotes object.
MMNotes.close()
Description
This function closes the specified Design Notes file and saves any changes. If all the key/value
pairs are removed, Dreamweaver deletes the Design Notes file. If it is the last Design Notes
file in the _notes folder, Dreamweaver also deletes the folder.
NOTE
Always call the MMNotes.close() function when you finish with Design Notes so
Dreamweaver writes to the file.
Arguments
fileHandle
■ The fileHandle argument is the file handle that the MMNotes.open() function returns.
Returns
Nothing.
Example
See “MMNotes.set()” on page 45.
MMNotes.filePathToLocalURL()
Description
This function converts the specified local drive path to a file:// URL.
40 The Design Notes API
Arguments
drivePath
■ The drivePath argument is a string that contains the full drive path.
Returns
A string that contains the file:// URL for the specified file.
Example
A call to MMNotes.filePathToLocalURL('C:\sites\webdev\index.htm') returns
"file:///c|/sites/webdev/index.htm".
MMNotes.get()
Description
This function gets the value of the specified key in the specified Design Notes file.
Arguments
fileHandle, keyName
■ The fileHandle argument is the file handle that MMNotes.open() returns.
■ The keyName argument is a string that contains the name of the key.
Returns
A string that contains the value of the key.
Example
See “MMNotes.getKeys()” on page 42.
MMNotes.getKeyCount()
Description
This function gets the number of key/value pairs in the specified Design Notes file.
Arguments
fileHandle
■ The fileHandle argument is the file handle that the MMNotes.open() function returns.
Returns
An integer that represents the number of key/value pairs in the Design Notes file.
The Design Notes JavaScript API 41
MMNotes.getKeys()
Description
This function gets a list of all the keys in a Design Notes file.
Arguments
fileHandle
■ The fileHandle argument is the file handle that the MMNotes.open() function returns.
Returns
An array of strings where each string contains the name of a key.
Example
The following code might be used in a custom floating panel to display the Design Notes
information for the active document:
var noteHandle = MMNotes.open(dw.getDocumentDOM().URL);
var theKeys = MMNotes.getKeys(noteHandle);
var noteString = "";
var theValue = "";
for (var i=0; i < theKeys.length; i++){
theValue = MMNotes.get(noteHandle,theKeys[i]);
noteString += theKeys[i] + " = " theValue + "\n";
}
document.theForm.bigTextField.value = noteString;
// always close noteHandle
MMNotes.close(noteHandle);
MMNotes.getSiteRootForFile()
Description
This function determines the site root for the specified Design Notes file.
Arguments
fileURL
■ The fileURL argument, which is expressed as a file:// URL, is the path to a local file.
Returns
A string that contains the path of the Local Root folder for the site, which is expressed as a
file:// URL, or an empty string if Dreamweaver is not installed or the Design Notes file is
outside any site that is defined with Dreamweaver. This function searches for all the sites that
are defined in Dreamweaver.
42 The Design Notes API
MMNotes.getVersionName()
Description
This function gets the version name of the MMNotes shared library, which indicates the
application that implemented it.
Arguments
None.
Returns
A string that contains the name of the application that implemented the MMNotes shared
library.
Example
Calling the MMNotes.getVersionName() function from a Dreamweaver command, object,
behavior, Property inspector, floating panel, or data translator returns
Calling the
"Dreamweaver" because Fireworks uses the same version of the library, which was created by
MMNotes.getVersionName() function from Fireworks also returns
"Dreamweaver".
the Dreamweaver engineering team.
MMNotes.getVersionNum()
Description
This function gets the version number of the MMNotes shared library.
Arguments
None.
Returns
A string that contains the version number.
MMNotes.localURLToFilePath()
Description
This function converts the specified file:// URL to a local drive path.
Arguments
fileURL
■ The fileURL argument, which is expressed as a file:// URL, is the path to a local file.
The Design Notes JavaScript API 43
Returns
A string that contains the local drive path for the specified file.
Example
A call to MMNotes.localURLToFilePath('file:///MacintoshHD/images/moon.gif')
returns "MacintoshHD:images:moon.gif".
MMNotes.open()
Description
This function opens the Design Notes file that is associated with the specified file or creates
one if none exists.
Arguments
filePath, {bForceCreate}
■ The filePath argument, which is expressed as a file:// URL, is the path to the main file
with which the Design Notes file is associated.
■ The bForceCreate argument is a Boolean value that indicates whether to create the note
even if Design Notes is turned off for the site or if the
associated with any site.
Returns
The file handle for the Design Notes file or 0 if the file was not opened or created.
filePath argument is not
Example
See “MMNotes.set()” on page 45.
MMNotes.remove()
Description
The function removes the specified key (and its value) from the specified Design Notes file.
Arguments
fileHandle, keyName
■ The fileHandle argument is the file handle that the MMNotes.open() function returns.
■ The keyName argument is a string that contains the name of the key to remove.
Returns
A Boolean value: true indicates the operation is successful; false otherwise.
44 The Design Notes API
MMNotes.set()
Description
This function creates or updates one key/value pair in a Design Notes file.
Arguments
fileHandle, keyName, valueString
■ The fileHandle argument is the file handle that the MMNotes.open() function returns.
■ The keyName argument is a string that contains the name of the key.
■ The valueString argument is a string that contains the value.
Returns
A Boolean value: true indicates the operation is successful; false otherwise.
Example
The following example opens the Design Notes file that is associated with a file in the
dreamcentral site called peakhike99/index.html, adds a new key/value pair, changes the value
of an existing key, and then closes the Design Notes file:
var noteHandle = MMNotes.open('file:///c|/sites/dreamcentral/
peakhike99/index.html',true);
if(noteHandle > 0){
MMNotes.set(noteHandle,"Author","M. G. Miller");
MMNotes.set(noteHandle,"Last Changed","August 28, 1999");
MMNotes.close(noteHandle);
}
The Design Notes C API
In addition to the JavaScript API, the MMNotes shared library also exposes a C API that lets
other applications create Design Notes files. It is not necessary to call these C functions
directly if you use the MMNotes shared library in Dreamweaver because the JavaScript
versions of the functions call them.
This section contains descriptions of the functions, their arguments, and their return values.
You can find definitions for the functions and data types in the MMInfo.h file in the
Extending/c_files folder inside the Dreamweaver application folder.
The Design Notes C API 45
void CloseNotesFile()
Description
This function closes the specified Design Notes file and saves any changes. If all key/value
pairs are removed from the Design Note file, Dreamweaver deletes it. Dreamweaver deletes
the _notes folder when the last Design Notes file is deleted.
Arguments
FileHandle noteHandle
■ The noteHandle argument is the file handle that the OpenNotesFile() function returns.
Returns
Nothing.
BOOL FilePathToLocalURL()
Description
This function converts the specified local drive path to a file:// URL.
Arguments
const char* drivePath, char* localURLBuf, int localURLMaxLen
■ The drivePath argument is a string that contains the full drive path.
■ The localURLBuf argument is the buffer where the file:// URL is stored.
■ The localURLMaxLen argument is the maximum size of localURLBuf.
Returns
A Boolean value: true indicates the operation is successful; false otherwise. The
localURLBuf argument receives the file:// URL value.
BOOL GetNote()
Description
This function gets the value of the specified key in the specified Design Notes file.
Arguments
FileHandle noteHandle, const char keyName[64], char* valueBuf, int
valueBufLength
■ The noteHandle argument is the file handle that the OpenNotesFile() function returns.
46 The Design Notes API
■ The keyName[64] argument is a string that contains the name of the key.
■ The valueBuf argument is the buffer where the value is stored.
■ The valueBufLength argument is the integer that GetNoteLength(noteHandle,
keyName) returns, which indicates the maximum length of the value buffer.
Returns
A Boolean value: true indicates the operation is successful; false otherwise. The valueBuf
argument receives the value of the key.
Example
The following code gets the value of the comments key in the Design Notes file that is
associated with the welcome.html file:
FileHandle noteHandle = OpenNotesFile("file:///c|/sites/avocado8/¬
iwjs/welcome.html");
if(noteHandle > 0){
int valueLength = GetNoteLength( noteHandle, "comments");
char* valueBuffer = new char[valueLength + 1];
GetNote(noteHandle, "comments", valueBuffer, valueLength + 1);
printf("Comments: %s",valueBuffer);
CloseNotesFile(noteHandle);
}
int GetNoteLength()
Description
This function gets the length of the value that is associated with the specified key.
Arguments
FileHandle noteHandle, const char keyName[64]
■ The noteHandle argument is the file handle that the OpenNotesFile() function returns.
■ The keyName[64] argument is a string that contains the name of the key.
Returns
An integer that represents the length of the value.
Example
See “BOOL GetNote()” on page 46.
The Design Notes C API 47
int GetNotesKeyCount()
Description
This function gets the number of key/value pairs in the specified Design Notes file.
Arguments
FileHandle noteHandle
■ The noteHandle argument is the file handle that the OpenNotesFile() function returns.
Returns
An integer that represents the number of key/value pairs in the Design Notes file.
BOOL GetNotesKeys()
Description
This function gets a list of all the keys in a Design Notes file.
Arguments
FileHandle noteHandle, char* keyBufArray[64], int keyArrayMaxLen
■ The noteHandle argument is the file handle that OpenNotesFile() returns.
■ The keyBufArray[64] argument is the buffer array where the keys are stored.
■ The keyArrayMaxLen argument is the integer that GetNotesKeyCount(noteHandle)
returns, indicating the maximum number of items in the key buffer array.
Returns
A Boolean value: true indicates the operation is successful; false otherwise. The
keyBufArray argument receives the key names.
Example
The following code prints the key names and values of all the keys in the Design Notes file
that are associated with the welcome.html file:
typedef char[64] InfoKey;
FileHandle noteHandle = OpenNotesFile("file:///c|/sites/avocado8/¬
iwjs/welcome.html");
if (noteHandle > 0){
int keyCount = GetNotesKeyCount(noteHandle);
if (keyCount <= 0)
return;
InfoKey* keys = new InfoKey[keyCount];
BOOL succeeded = GetNotesKeys(noteHandle, keys, keyCount);
48 The Design Notes API
if (succeeded){
for (int i=0; i < keyCount; i++){
printf("Key is: %s\n", keys[i]);
printf("Value is: %s\n\n", GetNote(noteHandle, keys[i]);
}
}
delete []keys;
}
CloseNotesFile(noteHandle);
BOOL GetSiteRootForFile()
Description
This function determines the site root for the specified Design Notes file.
Arguments
const char* filePath, char* siteRootBuf, int siteRootBufMaxLen,
{InfoPrefs* infoPrefs}
■ The filePath argument is the file://URL of the file for which you want the site root.
■ The siteRootBuf argument is the buffer where the site root is stored.
■ The siteRootBufMaxLen argument is the maximum size of the buffer that
siteRootBuf references.
■ The infoPrefs argument, which is optional, is a reference to a struct in which the
preferences for the site are stored.
Returns
A Boolean value: true indicates the operation is successful; false otherwise. The
siteRootBuf argument receives the address of the buffer that stores the site root. If you
specify the
the site. The
bUploadDesignNotes, both of type BOOL.
infoPrefs argument, the function also returns the Design Notes preferences for
InfoPrefs struct has two variables: bUseDesignNotes and
BOOL GetVersionName()
Description
This function gets the version name of the MMNotes shared library, which indicates the
application that implemented it.
The Design Notes C API 49
Arguments
char* versionNameBuf, int versionNameBufMaxLen
■ The versionNameBuf argument is the buffer where the version name is stored.
■ The versionNameBufMaxLen argument is the maximum size of the buffer that the
versionNameBuf argument references.
Returns
A Boolean value: true indicates the operation is successful; false otherwise. Dreamweaver
stores
"Dreamweaver" in versionNameBuf argument.
BOOL GetVersionNum()
Description
This function gets the version number of the MMNotes shared library, which lets you
determine whether certain functions are available.
Arguments
char* versionNumBuf, int versionNumBufMaxLen
■ The versionNumBuf argument is the buffer where the version number is stored.
■ The versionNumBufMaxLen argument is the maximum size of the buffer that
versionNumBuf references.
Returns
A Boolean value: true indicates the operation is successful; false otherwise. The
versionNumBuf argument stores the version number.
BOOL LocalURLToFilePath()
Description
This function converts the specified file:// URL to a local drive path.
Arguments
const char* localURL, char* drivePathBuf, int drivePathMaxLen
■ The localURL argument, which is expressed as a file:// URL, is the path to a local file.
■ The drivePathBuf argument is the buffer where the local drive path is stored.
■ The drivePathMaxLen argument is the maximum size of the buffer that the
drivePathBuf argument references.
50 The Design Notes API
Returns
A Boolean value: true indicates the operation is successful; false otherwise. The
drivePathBuf argument receives the local drive path.
FileHandle OpenNotesFile()
Description
This function opens the Design Notes file that is associated with the specified file or creates
one if none exists.
Arguments
const char* localFileURL, {BOOL bForceCreate}
■ The localFileURL argument, which is expressed as a file:// URL, is a string that contains
the path to the main file with which the Design Notes file is associated.
■ The bForceCreate argument is a Boolean value that indicates whether to create the
Design Notes file even if Design Notes is turned off for the site or if the path specified by
the
localFileURL argument is not associated with any site.
FileHandle OpenNotesFilewithOpenFlags()
Description
This function opens the Design Notes file that is associated with the specified file or creates
one if none exists. You can open the file in read-only mode.
Arguments
const char* localFileURL, {BOOL bForceCreate}, {BOOL bReadOnly}
■ The localFileURL argument, which is expressed as a file:// URL, is a string that contains
the path to the main file with which the Design Notes file is associated.
■ The bForceCreate argument is a Boolean value that indicates whether to create the
Design Notes file even if Design Notes are turned off for the site or the path is not
associated with any site. The default value is
false. This argument is optional, but you
need to specify it if you specify the third argument.
■ The bReadOnly argument, which is optional, is a Boolean value that indicates whether to
open the file in read-only mode. The default value is
bReadOnly argument starting in version 2 of the MMNotes.dll file.
false. You can specify the
The Design Notes C API 51
BOOL RemoveNote()
Description
This function removes the specified key (and its value) from the specified Design Notes file.
Arguments
FileHandle noteHandle, const char keyName[64]
■ The noteHandle argument is the file handle that the OpenNotesFile() function returns.
■ The keyName[64] argument is a string that contains the name of the key to remove.
Returns
A Boolean value: true indicates the operation is successful; false otherwise.
BOOL SetNote()
Description
This function creates or updates one key/value pair in a Design Notes file.
Arguments
FileHandle noteHandle, const char keyName[64], const char* value
■ The noteHandle argument is the file handle that the OpenNotesFile() function returns.
■ The keyName[64] argument is a string that contains the name of the key.
■ The value argument is a string that contains the value.
Returns
A Boolean value: true indicates the operation is successful; false otherwise.
52 The Design Notes API
CHAPTER 4
Fireworks Integration
FWLaunch is a C shared library that gives authors of objects, commands, behaviors, and
Property inspectors the ability to communicate with Macromedia Fireworks. Using
FWLaunch, you write JavaScript to open the Fireworks user interface (UI) and provide
commands to Fireworks through its own JavaScript API documented in the Extending
Fireworks manual. For general information on how C libraries interact with the JavaScript
interpreter in Macromedia Dreamweaver 8, see Extending Dreamweaver for details on
C-level extensibility.
The FWLaunch API
The FWLaunch object lets extensions open Fireworks, perform Fireworks operations using
the Fireworks JavaScript API, and then return values back to Dreamweaver. This chapter
describes the FWLaunch Communication API and how to use it.
FWLaunch.bringDWToFront()
Availability
Dreamweaver 3, Fireworks 3.
4
Description
This function brings Dreamweaver to the front.
Arguments
None.
Returns
Nothing.
53
FWLaunch.bringFWToFront()
Availability
Dreamweaver 3, Fireworks 3.
Description
This function brings Fireworks to the front if it is running.
Arguments
None.
Returns
Nothing.
FWLaunch.execJsInFireworks()
Availability
Dreamweaver 3, Fireworks 3.
Description
This function passes the specified JavaScript, or a reference to a JavaScript file, to Fireworks
to execute.
Arguments
javascriptOrFileURL
■ The javascriptOrFileURL argument, which is expressed as a file:// URL, is either a
string of literal JavaScript or the path to a JavaScript file.
Returns
A cookie object if the JavaScript passes successfully or a nonzero error code that indicates one
of the following errors occurred:
■ Invalid usage, which indicates that the javascriptOrFileURL argument is specified as a
null value or as an empty string, or the path to the JS or JSF file is invalid.
■ File I/O error, which indicates that Fireworks cannot create a Response file because the
disk is full.
■ Error notifying Dreamweaver that the user is not running a valid version of Dreamweaver
(version 3 or later).
54 Fireworks Integration
■ Error starting Fireworks process, which indicates that the function does not open a valid
version of Fireworks (version 3 or later).
■ User cancelled the operation.
FWLaunch.getJsResponse()
Availability
Dreamweaver 3, Fireworks 3.
Description
This function determines whether Fireworks is still executing the JavaScript passed to it by the
FWLaunch.execJsInFireworks() function, whether the script completed successfully, or
whether an error occurred.
Arguments
progressTrackerCookie
■ The progressTrackerCookie argument is the cookie object that the
FWLaunch.execJsInFireworks() function returns.
Returns
A string that contains the result of the script passed to the FWLaunch.execJsInFireworks()
function if the operation completes successfully, a
JavaScript, or a nonzero error code that indicates one of the following errors occurred:
■ Invalid usage, which indicates that a JavaScript error occurred while Fireworks executed
the script.
■ File I/O error, which indicates that Fireworks cannot create a Response file because the
disk is full.
■ Error notifying Dreamweaver that the user is not running a valid version of Dreamweaver
(version 3 or later).
■ Error starting Fireworks process, which indicates that the function does not open a valid
version of Fireworks (version 3 or later).
■ User cancelled the operation.
null value if Fireworks is still executing the
The FWLaunch API 55
Example
The following code passes the string "prompt('Please enter your name:')" to
FWLaunch.execJsInFireworks() and checks for the result:
var progressCookie = FWLaunch.execJsInFireworks("prompt('Please enter your
name:')");
var doneFlag = false;
while (!doneFlag){
// check for completion every 1/2 second
setTimeout('checkForCompletion()',500);
}
function checkForCompletion(){
if (progressCookie != null) {
var response = FWLaunch.getJsResponse(progressCookie);
if (response != null) {
if (typeof(response) == "number") {
// error or user-cancel, time to close the window
// and let the user know we got an error
window.close();
alert("An error occurred.");
}else{
// got a valid response!
alert("Nice to meet you, " + response);
window.close();
}
doneFlag = true;
}
}
}
FWLaunch.mayLaunchFireworks()
Availability
Dreamweaver 2, Fireworks 2.
Description
This function determines whether it is possible to open a Fireworks optimization session.
Arguments
None.
Returns
A Boolean value that indicates whether the platform is Windows or the Macintosh; if it is the
Macintosh, the value indicates if another Fireworks optimization session is already running.
56 Fireworks Integration
FWLaunch.optimizeInFireworks()
Availability
Dreamweaver 2, Fireworks 2.
Description
This function opens a Fireworks optimization session for the specified image.
Arguments
docURL, imageURL, {targetWidth}, {targetHeight}
■ The docURL argument is the path to the active document, which is expressed as a file://
URL.
■ The imageURL argument is the path to the selected image. If the path is relative, it is
relative to the path that you specify in the
■ The targetWidth argument, which is optional, defines the width to which the image
should be resized.
■ The targetHeight argument, which is optional, defines the height to which the image
should be resized.
Returns
Zero, if a Fireworks optimization session successfully opens for the specified image; otherwise,
a nonzero error code that indicates one of the following errors occurred:
■ Invalid usage, which indicates that the docURL argument, the imageURL argument, or
both, are specified as a
■ File I/O error, which indicates that Fireworks cannot create a response file because the
null value or an empty string.
disk is full.
■ Error notifying Dreamweaver that the user is not running a valid version of Dreamweaver
(version 2 or later).
■ Error starting Fireworks process, which indicates that the function does not open a valid
version of Fireworks (version 2 or later).
■ User cancelled the operation.
docURL argument.
The FWLaunch API 57
FWLaunch.validateFireworks()
Availability
Dreamweaver 2, Fireworks 2.
Description
This function looks for the specified version of Fireworks on the user’s hard disk.
Arguments
{versionNumber}
■ The versionNumber argument is an optional floating-point number that is greater than
or equal to 2; it represents the required version of Fireworks. If this argument is omitted,
the default is 2.
Returns
A Boolean value that indicates whether the specified version of Fireworks was found.
Example
The following code checks whether Fireworks is installed:
if (FWLaunch.validateFireworks(6.0)){
alert("Fireworks 6.0 or later is installed.");
}else{
alert("Fireworks 6.0 is not installed.");
}
A simple FWLaunch communication example
The following command asks Fireworks to prompt the user for their name and returns the
name to Dreamweaver:
<html>
<head>
<title>Prompt in Fireworks</title>
<meta http-equiv="Content-Type" content="text/html; ¬
charset=iso-8859-1">
<script>
function commandButtons(){
return new Array("Prompt", "promptInFireworks()", "Cancel", ¬
"readyToCancel()", "Close","window.close()");
}
var gCancelClicked = false;
var gProgressTrackerCookie = null;
58 Fireworks Integration
function readyToCancel() {
gCancelClicked = true;
}
function promptInFireworks() {
var isFireworks3 = FWLaunch.validateFireworks(3.0);
if (!isFireworks3) {
alert("You must have Fireworks 3.0 or later to use this ¬
command");
return;
}
// Tell Fireworks to execute the prompt() method.
gProgressTrackerCookie = FWLaunch.execJsInFireworks¬
("prompt('Please enter your name:')");
// null means it wasn't launched, a number means an error code
if (gProgressTrackerCookie == null || ¬
typeof(gProgressTrackerCookie) == "number") {
window.close();
alert("an error occurred");
gProgressTrackerCookie = null;
} else {
// bring Fireworks to the front
FWLaunch.bringFWToFront();
// start the checking to see if Fireworks is done yet
checkOneMoreTime();
}
}
function checkOneMoreTime() {
// Call checkJsResponse() every 1/2 second to see if Fireworks
// is done yet
window.setTimeout("checkJsResponse();", 500);
}
function checkJsResponse() {
var response = null;
// The user clicked the cancel button, close the window
if (gCancelClicked) {
window.close();
alert("cancel clicked");
} else {
// We're still going, ask Fireworks how it's doing
if (gProgressTrackerCookie != null)
response = ¬
FWLaunch.getJsResponse(gProgressTrackerCookie);
The FWLaunch API 59
if (response == null) {
// still waiting for a response, call us again in 1/2 a
// second
checkOneMoreTime();
} else if (typeof(response) == "number") {
// if the response was a number, it means an error
// occurred
// the user cancelled in Fireworks
window.close();
alert("an error occurred.");
} else {
// got a valid response! This return value might not
// always be a useful one, since not all functions in
// Fireworks return a string, but we know this one does,
// so we can show the user what we got.
window.close();
FWLaunch.bringDWToFront(); // bring Dreamweaver to the ¬
front
alert("Nice to meet you, " + response + "!");
}
}
}
</script>
</head>
<body>
<form>
<table width="313" nowrap>
<tr>
<td>This command asks Fireworks to execute the prompt() ¬
function. When you click Prompt, Fireworks comes forward and ¬
asks you to enter a value into a dialog box. That value is then ¬
returned to Dreamweaver and displayed in an alert.</td>
</tr>
</table>
</form>
</body>
</html>
60 Fireworks Integration
CHAPTER 5
Flash Integration
Macromedia Dreamweaver 8 provides support for Macromedia Flash elements as well as
continuing support for the Flash Object API, which leverages the Flash Generator Template
file to create new Flash objects. This chapter describes ways of working with Flash elements
(SWC files), and also provides details for the creation of Flash objects (SWF files) from Flash
Generator templates (SWT files).
For information about simply adding Flash content to Dreamweaver objects or commands,
see Extending Dreamweaver.
How Flash elements work
Flash elements are packaged as SWC files. A SWC file is a compiled component movie clip
that is generated by Flash for use by Macromedia and third-party products. Dreamweaver can
make these components available to users through the Insert bar, Insert menu, or a toolbar.
You create Flash elements using the Flash authoring tool, but Dreamweaver can parse
properties of a Flash element and express them through the
tag). Users can then edit the
is published (for more information about working with component properties in
Dreamweaver, see Using Dreamweaver).
param tag attributes to change the properties of the element as it
param tag (a child of the object
5
61
Inserting Flash elements
Flash elements are installed through the Extension Manager. Dreamweaver adds Flash
elements to documents in the same manner as the objects that are available on the Insert bar
or the Insert menu (for details about working with Dreamweaver objects, see “Insert Bar
Objects” in Extending Dreamweaver). By clicking on objects on the Insert bar or selecting
menu options from the Insert menu, users can add strings of code to documents. Flash
elements are available to users through the Insert bar or the Insert menu (meaning you can
add a valid Flash element file that is already installed in the Configuration/Objects/
FlashElements folder or one of its subfolders to the Insert bar or Insert menu). Extension
developers can use the JavaScript function dom.insertFlashElement() in the object definition
file to add available Flash elements to a document. When the user selects the Flash element
object, Dreamweaver unpacks the SWC file, which contains Flash content (SWF file) and a
file that details the parameters the user can edit. Dreamweaver then inserts the SWF file into
the user’s document.
Adding a Flash element to the Insert Bar
As with other objects, you add a Flash element to the Insert Bar using the button tag.
However, a
add the element successfully to the document (see the button tag details in “Insert Bar
Objects” in Extending Dreamweaver). Use the
source file for the element resides relative to the Objects folder. Then, use the
attribute to tell Dreamweaver to use the
clicks the button on the Insert bar.
The following example shows the code to place in the inserbar.xml file (either as a child of the
appropriate
button to appear):
<button id="FlashElement_Nav"
name="Navigation"
file="FlashElements\nav.swc"
command="dw.getDocumentDOM().insertFlashElement('nav.swc')" />
NOTE
button tag for a Flash element must have both file and command attributes to
file attribute to tell Dreamweaver where the
command
dom.insertFlashElement() function when the user
category or menubutton tag, depending on where you want the Flash element
The image on the Insert bar for the Flash element is determined within the SWC file.
Also, the button tag for a Flash element object must have a file attribute defined.
62 Flash Integration
Adding a Flash Element to a menu
A Flash element can also reside on the Insert menu, or on other menus, in Dreamweaver. Use
the JavaScript function dom.insertFlashElement() with the menus.xml file format (see
“Menus and Menu Commands” in Extending Dreamweaver) to specify the Flash element
menu item location. The following example shows how code within the menus.xml file makes
a Navigation Flash element available on the Insert > Flash Element menu:
<menuitem name="Navigation"
key=""command="dw.getDocumentDOM().insertFlashElement('nav.swc')"
enabled="(dw.getFocus() != 'browser') && (dw.getDocumentDOM() != null && ¬
dw.getDocumentDOM().getParseMode() == 'html')"
id="DWMenu_Insert_FlashElement_Nav" />
The Flash Objects API
The Flash Objects API lets extension developers build objects that create simple Flash content
through Flash Generator. This API provides a way to set parameters in a Flash Generator
template and output a SWF or image file. The API lets you create new Flash objects as well as
read and manipulate existing Flash objects. The Flash button and Flash text features are built
using this API.
The SWT file is a Flash Generator Template file, which contains all the information you need
to construct a Flash Object file. These API functions let you create a new SWF file (or image
file) from a SWT file by replacing the parameters of the SWT file with real values. For more
information on Flash, see the Flash documentation. The following functions are methods of
the
SWFFile object.
SWFFile.createFile()
Description
This function generates a new Flash Object file with the specified template and array of
parameters. It also creates a GIF, PNG, JPEG, and MOV version of the title if filenames for
those formats are specified.
If you want to specify an optional parameter that follows optional parameters that you do not
want to include, you need to specify empty strings for the unused parameters. For example, if
you want to specify a PNG file, but not a GIF file, you need to specify an empty string before
specifying the PNG filename.
The Flash Objects API 63
Arguments
templateFile, templateParams, swfFileName, {gifFileName}, {pngFileName},
{jpgFileName}, {movFileName}, {generatorParams}
■ The templateFile argument is a path to a template file, which is expressed as a file://
URL. This file can be a SWT file.
■ The templateParams argument is an array of name/value pairs where the names are the
parameters in the SWT file, and the values are what you want to specify for those
parameters. For Dreamweaver to recognize a SWF file as a Flash object, the first parameter
must be
such as
■ The swfFileName argument, which is expressed as a file:// URL, is the output filename of
"dwType". Its value should be a string that represents the name of the object type,
"Flash Text".
an SWF file or an empty string to ignore.
■ The gifFileName argument, which is expressed as a file:// URL, is the output filename of
a GIF file. This argument is optional.
■ The pngFileName argument, which is expressed as a file:// URL, is the output filename of
a PNG file. This argument is optional.
■ The jpgFileName argument, which is expressed as a file:// URL, is the output filename of
a JPEG file. This argument is optional.
■ The movFileName argument, which is expressed as a file:// URL, is the output filename of
a QuickTime file. This argument is optional.
■ The generatorParams argument is an array of strings that represents optional Generator
command line flags. This argument is optional. Each flag’s data items must follow it in the
array. Some commonly used flags are listed in the following table:
Option Flag Data Description Example
-defaultsize
-exactFit
Width, height Sets the output image size to the
specified width and height
None Stretches the contents in the
output image to fit exactly into the
specified output size
"-defaultsize",
"640", "480"
"-exactFit"
Returns
A string that contains one of the following values:
■ "noError" means the call completed successfully.
■ "invalidTemplateFile" means the specified template file is invalid or not found.
■ "invalidOutputFile" means at least one of the specified output filenames is invalid.
64 Flash Integration
■ "invalidData" means that one or more of the templateParams name/value pairs is
invalid.
■ "initGeneratorFailed" means the Generator cannot be initialized.
■ "outOfMemory" means there is insufficient memory to complete the operation.
■ "unknownError" means an unknown error occurred.
Example
The following JavaScript creates a Flash object file of type "myType", which replaces any
occurrences of the string
"text" inside the Template file with the string, "Hello World". It
creates a GIF file as well as a SWF file.
var params = new Array;
params[0] = "dwType";
params[1] = "myType";
params[2] = "text";
params[3] = "Hello World";
errorString = SWFFile.createFile( "file:///MyMac/test.swt", ¬
params, "file:///MyMac/test.swf", "file:///MyMac/test.gif");
SWFFile.getNaturalSize()
Description
This function returns the natural size of any Flash content.
Arguments
fileName
■ The fileName argument, which is expressed as a file:// URL, is a path to the Flash
content.
Returns
An array that contains two elements that represent the width and the height of the Flash
content or a
null value if the file is not a Flash file.
The Flash Objects API 65
SWFFile.getObjectType()
Description
This function returns the Flash object type; the value that passed in the dwType parameter
when the
Arguments
fileName
■ The fileName argument, which is expressed as a file:// URL, is a path to a Flash Object
Returns
A string that represents the object type, or null if the file is not a Flash Object file or if the file
cannot be found.
Example
The following code checks to see if the test.swf file is a Flash object of type myType:
if ( SWFFile.getObjectType("file:///MyMac/test.swf") == ¬
"myType" ){
}else{
}
SWFFile.createFile() function created the file.
file. This file is usually a SWF file.
alert ("This is a myType object.");
alert ("This is not a myType object.");
SWFFile.readFile()
Description
This function reads a Flash Object file.
Arguments
fileName
■ The fileName argument, which is expressed as a file:// URL, is a path to a Flash Object
file.
Returns
An array of strings where the first array element is the full path to the template SWT file. The
following strings represent the parameters (name/value pairs) for the object. Each name is
followed in the array by its value. The first name/value pair is
The function returns a
66 Flash Integration
null value if the file cannot be found or if it is not a Flash Object file.
"dwType", followed by its value.
Example
Calling var params = SWFFile.readFile("file:///MyMac/test.swf") returns the
following values in the parameters array:
"file:///MyMac/test.swt" // template file used to create this .swf file
"dwType" // first parameter
"myType" // first parameter value
"text" // second parameter
"Hello World" // second parameter value
The Flash Objects API 67
68 Flash Integration
CHAPTER 6
The Database API
Functions in the Database API let you manage database connections and access information
that is stored in databases. The Database API is divided by two distinct purposes: managing
and accessing database connections.
In managing database connections, you can get the user name and password needed to make a
connection to a database, open up a database connection dialog box, and so on.
In accessing database information, you can, for example, retrieve metadata that describes the
schema or structure of a database. This metadata includes information such as the names of
tables, columns, stored procedures, and views. You can also show the results of executing a
database query or stored procedure. When accessing a database through this API, you use
structured query language (SQL) statements.
Database API functions are used at design time when users are building web applications, not
at runtime when the web application is deployed.
You can use these functions in any extension. In fact, the Macromedia Dreamweaver 8
Server Behavior, Data Format, and Data Sources API functions all use these database
functions.
How Database API functions work
6
The following example shows how the server behavior function, getDynamicBindings(), is
defined for Recordset.js. This example uses the
function getDynamicBindings(ss)
{
var serverModel = dw.getDocumentDOM().serverModel.getServerName();
var bindingsAndTypeArray = new Array();
var connName = ss.connectionName;
var statement = ss.source;
var rsName = ss.rsName;
// remove SQL comments
statement = statement.replace(/\/\*[\S\s]*?\*\//g, " ");
MMDB.getColumnAndTypeList() function:
69
var bIsSimple = ParseSimpleSQL(statement);
statement = stripCFIFSimple(statement);
if (bIsSimple) {
statement = RemoveWhereClause(statement,false);
} else {
var pa = new Array();
if (ss.ParamArray != null) {
for (var i = 0; i < ss.ParamArray.length; i++) {
pa[i] = new Array();
pa[i][0] = ss.ParamArray[i].name;
pa[i][1] = ss.ParamArray[i].value;
}
}
var statement = replaceParamsWithVals(statement, pa, serverModel);
}
bindingsAndTypeArray = MMDB.getColumnAndTypeList(connName, statement);
return bindingsAndTypeArray;
}
Database connection functions
Database connection functions let you make and manage any connection, including the
Dreamweaver-provided ADO, ColdFusion, and JDBC connections. These functions
interface with the Connection Manager only; they do not access a database. For functions that
access a database, see “Database access functions” on page 86.
MMDB.deleteConnection()
Availability
Dreamweaver MX.
Description
This function deletes the named database connection.
Arguments
connName
■ The connName argument is the name of the database connection as it is specified in the
Connection Manager. This argument identifies, by name, the database connection to
delete.
70 The Database API
Returns
Nothing.
Example
The following example deletes a database connection:
function clickedDelete()
{
var selectedObj = dw.serverComponents.getSelectedNode();
if (selectedObj && selectedObj.objectType=="Connection")
{
var connRec = MMDB.getConnection(selectedObj.name);
if (connRec)
{
MMDB.deleteConnection(selectedObj.name);
dw.serverComponents.refresh();
}
}
}
MMDB.getColdFusionDsnList()
Availability
Dreamweaver UltraDev 4.
Description
This function gets the ColdFusion data source names (DSNs) from the site server, using the
getRDSUserName() and getRDSPassword() functions.
Arguments
None.
Returns
An array that contains the ColdFusion DSNs that are defined on the server for the current
site.
MMDB.getConnection()
Availability
Dreamweaver UltraDev 4, enhanced in Dreamweaver MX.
Description
This function gets a named connection object.
Database connection functions 71
Arguments
name
■ The name argument is a string variable that specifies the name of the connection that you
want to reference.
Returns
A reference to a named connection object. Connection objects contain the following
properties:
Property Description
name
type
string
dsn
driver
username
password
useHTTP
includePattern
variables
catalog
schema
filename
Connection name
Indicates, if useHTTP is a value of false, which DLL to use for
connecting to a database at runtime
Runtime ADO connection string or JDBC URL
ColdFusion DSN
Runtime JDBC driver
Runtime user name
Runtime password
String that contains either a true or false value, specifying
whether to use a remote driver (HTTP connection) at design time;
otherwise, use a local driver (DLL)
Regular expression used to find the file include statement on the
page during Live Data and Preview In Browser
Array of page variable names and their corresponding values
used during Live Data and Preview In Browser
Used to restrict the metadata that appears (for more information,
see “MMDB.getProcedures()” on page 90)
Used to restrict the metadata that appears (for more information,
see “MMDB.getProcedures()” on page 90)
Filename of dialog box that was used to create the connection
NOTE
These properties are the standard ones that Dreamweaver implements. Developers can
define their connection types and add new properties to this standard set or provide a
different set of properties.
72 The Database API
MMDB.getConnectionList()
Availability
Dreamweaver UltraDev 1.
Description
This function gets a list of all the connection strings that are defined in the Connection
Manager.
Arguments
None.
Returns
An array of strings where each string is the name of a connection as it appears in the
Connection Manager.
Example
A call to MMDB.getConnectionList() can return the strings ["EmpDB", "Test",
TestEmp"]
.
MMDB.getConnectionName()
Availability
Dreamweaver UltraDev 1.
Description
This function gets the connection name that corresponds to the specified connection string.
This function is useful when you need to reselect a connection name in the user interface (UI)
from data on the page.
If you have a connection string that references two drivers, you can specify the connection
string and the driver that corresponds to the connection name that you want to return. For
example, you can have two connections.
■ Connection 1 has the following properties:
ConnectionString="jdbc:inetdae:velcro-qa-5:1433?database=pubs"
DriverName="com.inet.tds.TdsDriver"
■ Connection 2 has the following properties:
ConnectionString="jdbc:inetdae:velcro-qa-5:1433?database=pubs"
DriverName="com.inet.tds.TdsDriver2"
Database connection functions 73
The connection strings for Connection 1 and Connection 2 are the same. Connection 2
connects to a more recent version of the
TdsDriver driver. You should pass the driver name
to this function to fully qualify the connection name you want to return.
Arguments
connString, {driverName}
■ The connString argument is the connection string that gets the connection name.
■ The driverName argument, which is optional, further qualifies the connString
argument.
Returns
A connection name string that corresponds to the connection string.
Example
The following code returns the string "EmpDB":
var connectionName = MMDB.getConnectionName ¬
("dsn=EmpDB;uid=;pwd=");
MMDB.getConnectionString()
Availability
Dreamweaver UltraDev 1.
Description
This function gets the connection string that is associated with the named connection.
Arguments
connName
■ The connName argument is a connection name that is specified in the Connection
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
Returns
A connection string that corresponds to the named connection.
74 The Database API
Example
The code var connectionString = MMDB.getConnectionString ("EmpDB") returns
different strings for an ADO or JDBC connection.
■ For an ADO connection, the following string can return:
"dsn=EmpDB;uid=;pwd=";
■ For a JDBC connection, the following string can return:
"jdbc:inetdae:192.168.64.49:1433?database=pubs&user=JoeUser&¬
password=joesSecret"
MMDB.getDriverName()
Availability
Dreamweaver UltraDev 1.
Description
This function gets the driver name that is associated with the specified connection. Only a
JDBC connection has a driver name.
Arguments
connName
■ The connName argument is a connection name that is specified in the Connection
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
Returns
A string that contains the driver name.
Example
The statement MMDB.getDriverName ("EmpDB"); might return the following string:
"jdbc/oracle/driver/JdbcOracle"
MMDB.getDriverUrlTemplateList() (deprecated)
Availability
Dreamweaver UltraDev 4, deprecated in Dreamweaver MX.
NOTE
For Dreamweaver UltraDev 4, the list of JDBC drivers are stored in the connections.xml
file, which is located in the Configuration/Connections folder. Each driver has an
associated URL template. This function returns the list of JDBC drivers.
Database connection functions 75
For Dreamweaver MX (or later), these drivers and URL templates are hard-coded in the
JDBC dialog boxes. In addition, this function is an empty function definition to eliminate
undefined-function errors. The following example shows how a JDBC driver and URL
template are hard-coded:
var DEFAULT_DRIVER = "COM.ibm.db2.jdbc.app.DB2Driver";
var DEFAULT_TEMPLATE = "jdbc:db2:[database name]";
Dreamweaver has a dialog box for each driver/URL template pair.
In summary, Dreamweaver UltraDev 4 developers need to add a new entry to the XML, and
Dreamweaver MX (or later), developers need to implement a new dialog box.
Description
This function gets JDBC Drivers and respective URL templates.
Arguments
None.
Returns
An array that contains JDBC drivers that have been detected on the user’s system and their
respective URL templates, if they are specified. The array has an even number of elements that
contain:
Driver1, UrlTemplate1, Driver2, UrlTemplate2, and so on.
MMDB.getLocalDsnList()
Availability
Dreamweaver UltraDev 4.
Description
This function gets ODBC DSNs that are defined on the user’s system.
Arguments
None.
Returns
An array that contains the ODBC DSNs that are defined on the user’s system.
MMDB.getPassword()
Availability
Dreamweaver UltraDev 1.
76 The Database API
Description
This function gets the password that is used for the specified connection.
Arguments
connName
■ The connName argument is a connection name that is specified in the Connection
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
Returns
A password string that is associated with the connection name.
Example
The statement MMDB.getPassword ("EmpDB"); might return "joessecret".
MMDB.getRDSPassword()
Availability
Dreamweaver UltraDev 4.
Description
This function gets the Remote Development Services (RDS) password (for use with
ColdFusion connections).
Arguments
None.
Returns
A string that contains the RDS password.
MMDB.getRDSUserName()
Availability
Dreamweaver UltraDev 4.
Description
This function gets the RDS user name (for use with ColdFusion connections).
Database connection functions 77
Arguments
None.
Returns
A string that contains the RDS user name.
MMDB.getRemoteDsnList()
Availability
Dreamweaver UltraDev 4, enhanced in Dreamweaver MX.
Description
This function gets the ODBC DSNs from the site server. The getRDSUserName() and
getRDSPassword() functions are used when the server model of the current site is
ColdFusion. This function provides an option for a developer to specify a URL parameter
string to be appended to the Remote Connectivity URL that
generates. If the developer provides a parameter string, this function passes it to the HTTP
connectivity scripts.
Arguments
{urlParams}
■ The urlParams argument, which is optional, is a string that contains a list of name=value
expressions, which are separated by ampersand (&) characters. You must not enclose
values with quotes. Some characters, such as the space in the value
be encoded. The following example shows a valid sample argument that you can pass to
MMDB.getRemoteDsnList():
a=1&b=Hello%20World
MMDB.getRemoteDsnList()
Hello World, need to
Returns
Returns an array that contains the ODBC DSNs that are defined on the server for the current
site.
MMDB.getRuntimeConnectionType()
Availability
Dreamweaver UltraDev 1.
Description
This function returns the runtime connection type of the specified connection name.
78 The Database API
Arguments
connName
■ The connName argument is a connection name that is specified in the Connection
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
Returns
A string that corresponds to the connection type. This function can return one of the
following values:
Example
"ADO", "ADODSN", "JDBC", or "CFDSN".
The following code returns the string "ADO" for an ADO connection:
var connectionType = MMDB.getRuntimeConnectionType ("EmpDB")
MMDB.getUserName()
Availability
Dreamweaver UltraDev 1.
Description
This function returns a user name for the specified connection.
Arguments
connName
■ The connName argument is a connection name that is specified in the Connection
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
Returns
A user name string that is associated with the connection name.
Example
The statement MMDB.getUserName ("EmpDB"); might return "amit".
Database connection functions 79
MMDB.hasConnectionWithName()
Availability
Dreamweaver UltraDev 4.
Description
This function determines whether a connection of a given name exists.
Arguments
name
■ The name argument is the connection name.
Returns
Returns a Boolean value: true indicates that a connection with the specified name exists;
false otherwise.
MMDB.needToPromptForRdsInfo()
Availability
Dreamweaver MX.
Description
This function determines whether Dreamweaver should open the RDS Login Information
dialog box.
Arguments
bForce
■ The bForce argument is a Boolean value; true indicates that the user who has
previously cancelled out of the RDS login dialog box still needs to be prompted for
RDS login information.
Returns
A Boolean value: true indicates that the user needs to be prompted for RDS login
information;
80 The Database API
false otherwise.
MMDB.needToRefreshColdFusionDsnList()
Availability
Dreamweaver MX.
Description
This function tells the Connection Manager to empty the cache and get the ColdFusion data
source list from the application server the next time a user requests the list.
Arguments
None.
Returns
Nothing.
MMDB.popupConnection()
Availability
Dreamweaver MX.
Description
This function invokes a connection dialog box. This function has the following three
signatures:
■ If the argument list consists only of dialogFileName (a string), the popupConnection()
function makes Dreamweaver open the Connection dialog box so you can define a
new connection.
■ If the argument list consists only of connRec (a connection reference), the
popupConnection() function makes Dreamweaver launch the Connection dialog box in
edit mode for editing the named connection. In this mode, the name text field is dimmed.
■ If the argument list consists of connRec and the Boolean value bDuplicate, the
popupConnection() function makes Dreamweaver open the Connection dialog box in
duplicate mode. In this mode, the name text field is blanked out, and the remaining
properties are copied to define a duplicate connection.
Arguments
dialogFileName
or
connRec
Database connection functions 81
or
connrec, bDuplicate
■ The dialogFileName argument is a string that contains the name of an HTML file that
resides in the Configuration/Connections/server-model folder. This HTML file defines the
dialog box that creates a connection. This file must implement three JavaScript API
functions:
findConnection(), inspectConnection(), and applyConnection().
Typically, you create a JavaScript file that implements these functions and then include
that file in the HTML file. (For more information on creating a connection, see “The
Database Connectivity API” on page 101.)
■ The connRec argument is a reference to an existing Connection object.
■ The bDuplicate argument is a Boolean value.
Returns
Nothing. The defined connection dialog box appears.
MMDB.setRDSPassword()
Availability
Dreamweaver UltraDev 4.
Description
This function sets the RDS password.
Arguments
password
■ The password argument is a string that contains the RDS password.
Returns
Nothing.
MMDB.setRDSUserName()
Availability
Dreamweaver UltraDev 4.
Description
This function sets the RDS user name.
82 The Database API
Arguments
username
■ The username argument is a valid RDS user name.
Returns
Nothing.
MMDB.showColdFusionAdmin()
Availability
Dreamweaver MX.
Description
This function displays the ColdFusion Administrator dialog box.
Arguments
None.
Returns
Nothing. The ColdFusion Administrator dialog box appears.
MMDB.showConnectionMgrDialog()
Availability
Dreamweaver UltraDev 1.
Description
This function displays the Connection Manager dialog box.
Arguments
None.
Returns
Nothing. The Connection Manager dialog box appears.
MMDB.showOdbcDialog()
Availability
Dreamweaver UltraDev 4 (Windows only).
Database connection functions 83
Description
This function displays the System ODBC Administration dialog box or the ODBC Data
Source Administrator dialog box.
Arguments
None.
Returns
Nothing. The System ODBC Administration dialog box or the ODBC Data Source
Administrator dialog box appears.
MMDB.showRdsUserDialog()
Availability
Dreamweaver UltraDev 4.
Description
This function displays the RDS user name and password dialog box.
Arguments
username, password
■ The username argument is the initial user name.
■ The password argument is the initial password.
Returns
An object that contains the new values in the username and password properties. If either
property is not defined, it indicates that the user cancelled the dialog box.
MMDB.showRestrictDialog()
Availability
Dreamweaver UltraDev 4.
Description
This function displays the Restrict dialog box.
84 The Database API
Arguments
catalog, schema
■ The catalog argument is the initial catalog value.
■ The schema argument is the initial schema value.
Returns
An object that contains the new values in the catalog and schema properties. If either
property is not defined, it indicates that the user cancelled the dialog box.
MMDB.testConnection()
Availability
Dreamweaver UltraDev 4.
Description
This function tests connection settings. It displays a modal dialog box that describes the
results.
Arguments
serverPropertiesArray
This function expects a single argument, an array object that contains values from the
following list, which are appropriate for the current server model. For properties that do not
apply to the connection being tested, set them to empty (
■ The type argument indicates, when useHTTP is a false value, which DLL to use for
connecting to a database at design time to test connection settings.
■ The string argument is the ADO connection string or JDBC URL.
■ The dsn argument is the data source name.
■ The driver argument is the JDBC driver.
■ The username argument is the user name.
■ The password argument is the password.
■ The useHTTP argument is a Boolean value. A value of true specifies that Dreamweaver
should use an HTTP connection at design time; otherwise, Dreamweaver uses a DLL.
"").
Returns
A Boolean value: true if the connection test is successful; false otherwise.
Database connection functions 85
Database access functions
Database access functions let you query a database. For the collection of functions that
manage a database connection, see “Database connection functions” on page 70.
The following list describes some of the arguments that are common to the functions that are
available:
■ Most database access functions use a connection name as an argument. You can see a
list of valid connection names in the Connection Manager, or you can use the
MMDB.getConnectionList() function to get a list of all the connection
names programmatically.
■ Stored procedures often require parameters. There are two ways of specifying parameter
values for database access functions. First, you can provide an array of parameter values
(
paramValuesArray). If you specify only parameter values, the values need to be in the
sequence in which the stored procedure requires the parameters. Second, you specify
parameter values to provide an array of parameter names (
the
MMDB.getSPParamsAsString() function to get the parameters of the
stored procedure. If you provide parameter names, the values that you specify in
paramValuesArray must be in the sequence of the parameter names that you specify in
paramNameArray.
MMDB.getColumnAndTypeList()
paramNameArray). You can use
Availability
Dreamweaver UltraDev 1.
Description
This function gets a list of columns and their types from an executed SQL SELECT statement.
Arguments
connName, statement
■ The connName argument is a connection name that is specified in the Connection
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
■ The statement argument is the SQL SELECT statement to execute.
Returns
An array of strings that represents a list of columns (and their types) that match the SELECT
statement, or an error if the SQL statement is invalid or the connection cannot be made.
86 The Database API
Example
The code var columnArray = MMDB.getColumnAndTypeList("EmpDB","Select * from
Employees")
columnArray[0] = "EmpName"
columnArray[1] = "varchar"
columnArray[2] = "EmpFirstName"
columnArray[3] = "varchar"
columnArray[4] = "Age"
columnArray[5] = "integer"
returns the following array of strings:
MMDB.getColumnList()
Availability
Dreamweaver UltraDev 1.
Description
This function gets a list of columns from an executed SQL SELECT statement.
Arguments
connName, statement
■ The connName argument is a connection name that is specified in the Connection
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
■ The statement argument is the SQL SELECT statement to execute.
Returns
An array of strings that represents a list of columns that match the SELECT statement, or an
error if the SQL statement is invalid or the connection cannot be made.
Example
The code var columnArray = MMDB.getColumnList("EmpDB","Select * from
Employees")
columnArray[0] = "EmpName"
columnArray[1] = "EmpFirstName"
columnArray[2] = "Age"
returns the following array of strings:
MMDB.getColumns()
Availability
Dreamweaver MX, arguments updated in Dreamweaver MX 2004.
Database access functions 87
Description
This function returns an array of objects that describe the columns in the specified table.
Arguments
connName, tableName
■ The connName argument is the connection name. This value identifies the connection
containing the string that Dreamweaver should use to make a database connection to a
live data source.
■ The tableName argument is the table to query.
Returns
An array of objects, one object for each column. Each object defines the following three
properties for the column with which it is associated.
Property Name Description
name
datatype
definedsize
nullable Indicates whether the column can contain null values
Name of the column (for example, price)
Data type of the column (for example, small money)
Defined size of the column (for example, 8)
Example
The following example uses MMDB.getColumns() to set the tooltip text value:
var columnNameObjs = MMDB.getColumns(connName,tableName);
var databaseType = MMDB.getDatabaseType(connName);
for (i = 0; i < columnNameObjs.length; i++)
{
var columnObj = columnNameObjs[i];
var columnName = columnObj.name;
var typename = columnObj.datatype;
if (dwscripts.isNumber(typename))
{
// it already is a num
typename = dwscripts.getDBColumnTypeAsString(typename,
databaseType);
}
var tooltiptext = typename;
}
88 The Database API
MMDB.getColumnsOfTable()
Availability
Dreamweaver UltraDev 1.
Description
This function gets a list of all the columns in the specified table.
Arguments
connName, tableName
■ The connName argument is a connection name that is specified in the Connection
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
■ The tableName argument is the name of a table in the database that is specified by the
connName argument.
Returns
An array of strings where each string is the name of a column in the table.
Example
The statement MMDB.getColumnsOfTable ("EmpDB","Employees"); returns the
following strings:
["EmpID", "FirstName", "LastName"]
MMDB.getPrimaryKeys()
Availability
Dreamweaver MX.
Description
This function returns the column names that combine to form the primary key of the named
table. A primary key serves as the unique identifier for a database row and consists of at least
one column.
Arguments
connName, tableName
■ The connName argument is a connection name that is specified in the Connection
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
Database access functions 89
■ The tableName argument is the name of the table for which you want to retrieve the set
of columns that comprises the primary key of that table.
Returns
An array of strings. The array contains one string for each column that comprises the primary
key.
Example
The following example returns the primary key for the specified table.
var connName = componentRec.parent.parent.parent.name;
var tableName = componentRec.name;
var primaryKeys = MMDB.getPrimaryKeys(connName,tableName);
MMDB.getProcedures()
Availability
Dreamweaver MX.
Description
This function returns an array of procedure objects that are associated with a named
connection.
Arguments
connName
■ The connName argument is a connection name that is specified in the Connection
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
90 The Database API
Returns
An array of procedure objects where each procedure object has the following set of three
properties:
Property Name Description
schema*
catalog
procedure
* Dreamweaver connects to and gets all the tables in the database whenever you modify a recordset. If the
database has many tables, Dreamweaver might take a long time to retrieve them on certain systems. If your
database contains a schema or catalog, you can use the schema or catalog to restrict the number of
database items Dreamweaver gets at design time. You must first create a schema or catalog in your
database application before you can apply it in Dreamweaver. Consult your database documentation or
your system administrator.
Name of the schema that is associated with the object.
This property identifies the user that is associated with the stored
procedure in the SQL database that the
getProcedures() function
accesses. The database that this function accesses depends on
the type of connection.
• For ODBC connections, the ODBC data source defines the
database. The DSN is specified by the
connection object (
getProcedures() function.
connName) that you pass to the
dsn property in the
• For OLE DB connections, the connection string names the
database.
Name of the catalog that is associated with the object (owner
qualifier).
The value of the
catalog property is defined by an attribute of the
OLE DB driver. This driver attribute defines a default
user.database property to use when the OLE DB connection
string does not specify a database.
Name of the procedure.
Example
The following code gets a list of procedures:
var procObjects = MMDB.getProcedures(connectionName);
for (i = 0; i < procObjects.length; i++)
{
var thisProcedure = procObjects[i]
thisSchema = Trim(thisProcedure.schema)
if (thisSchema.length == 0)
{
thisSchema = Trim(thisProcedure.catalog)
}
if (thisSchema.length > 0)
{
thisSchema += "."
}
Database access functions 91
var procName = String(thisSchema + thisProcedure.procedure);
}
MMDB.getSPColumnList()
Availability
Dreamweaver UltraDev 1.
Description
This function gets a list of result set columns that are generated by a call to the specified
stored procedure.
Arguments
connName, statement, paramValuesArray
■ The connName argument is a connection name that is specified in the Connection
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
■ The statement argument is the name of the stored procedure that returns the result set
when it executes.
■ The paramValuesArray argument is an array that contains a list of design-time parameter
test values. Specify the parameter values in the order in which the stored procedure expects
them. You can use the
the stored procedure.
MMDB.getSPParamsAsString() function to get the parameters for
Returns
An array of strings that represents the list of columns. This function returns an error if the
SQL statement or the connection string is invalid.
Example
The following code can return a list of result set columns that are generated from the executed
stored procedure,
var paramValueArray = new Array("2/1/2000", "50000")
var columnArray = MMDB.getSPColumnList("EmpDB", ¬
"getNewEmployeesMakingAtLeast", paramValueArray)
getNewEmployeesMakingAtLeast:
The following values return:
columnArray[0] = "EmpID", columnArray[1] = "LastName", ¬
columnArray[2] ="startDate", columnArray[3] = "salary"
92 The Database API
MMDB.getSPColumnListNamedParams()
Availability
Dreamweaver UltraDev 1.
Description
This function gets a list of result set columns that are generated by a call to the specified
stored procedure.
Arguments
connName, statement, paramNameArray, paramValuesArray
■ The connName argument is a connection name that is specified in the Connection
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
■ The statement argument is the name of the stored procedure that returns the result set
when it executes.
■ The paramNameArray argument is an array that contains a list of parameter names. You
can use the
stored procedure.
■ The paramValuesArray argument is an array that contains a list of design-time parameter
test values. You can specify if the procedure requires parameters when it executes. If you
have provided parameter names in
same order that their corresponding parameter names appear in
did not provide
procedure expects them.
MMDB.getSPParamsAsString() function to get the parameters of the
paramNameArray, specify the parameter values in the
paramNameArray. If you
paramNameArray, specify the values in the order in which the stored
Returns
An array of strings that represents the list of columns. This function returns an error if the
SQL statement or the connection string is invalid.
Example
The following code can return a list of result set columns that are generated from the executed
stored procedure,
var paramNameArray = new Array("startDate", "salary")
var paramValueArray = new Array("2/1/2000", "50000")
var columnArray = MMDB.getSPColumnListNamedParams("EmpDB", ¬
"getNewEmployeesMakingAtLeast", paramNameArray, paramValueArray)
getNewEmployeesMakingAtLeast:
Database access functions 93
The following values return:
columnArray[0] = "EmpID", columnArray[1] = "LastName",¬
columnArray[2] ="startDate", columnArray[3] = "salary"
MMDB.getSPParameters()
Availability
Dreamweaver MX.
Description
This function returns an array of parameter objects for a named procedure.
Arguments
connName, procName
■ The connName argument is a connection name that is specified in the Connection
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
■ The procName argument is the name of the procedure.
Returns
An array of parameter objects, each specifying the following set of properties:
Property name Description
name
datatype
direction
Name of the parameter (for example, @@lolimit)
Datatype of the parameter (for example, smallmoney)
Direction of the parameter:
1-The parameter is used for input only.
2–The parameter is used for output only. In this case, you pass the
parameter by reference and the method places a value in it. You
can use the value after the method returns.
3– The parameter is used for both input and output.
4– The parameter holds a return value.
Example
The following example retrieves the parameter objects for the specified procedure and creates
a tooltip for each object using its properties.
var paramNameObjs = MMDB.getSPParameters(connName,procName);
for (i = 0; i < paramNameObjs.length; i++)
{
var paramObj = paramNameObjs[i];
94 The Database API
var tooltiptext = paramObj.datatype;
tooltiptext+=" ";
tooltiptext+=GetDirString(paramObj.directiontype);
}
MMDB.getSPParamsAsString()
Availability
Dreamweaver UltraDev 1.
Description
This function gets a comma-delimited string that contains the list of parameters that the
stored procedure takes.
Arguments
connName, procName
■ The connName argument is a connection name that is specified in the Connection
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
■ The procName argument is the name of the stored procedure.
Returns
A comma-delimited string that contains the list of parameters that the stored procedure
requires. The parameters’ names, direction, and data type are included, separated by
semicolons (;).
Example
The code MMDB.getSPParamsAsString ("EmpDB","getNewEmployeesMakingAtLeast")
can return a string of form name
salary;direction:in;datatype:integer
In this example, the stored procedure,
parameters:
date. For salary, the direction is in and the data type is date.
startDate and Salary. For startDate, the direction is in and the data type is
startDate;direction:in;datatype:date,
.
getNewEmployeesMakingAtLeast, has two
MMDB.getTables()
Availability
Dreamweaver UltraDev 1.
Database access functions 95
Description
This function gets a list of all the tables that are defined for the specified database. Each table
object has three properties:
Arguments
connName
■ The connName argument is a connection name that is specified in the Connection
table, schema, and catalog.
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
Returns
An array of objects where each object has three properties: table, schema, and catalog.
Table is the name of the table. Schema is the name of the schema that contains the table.
Catalog is the catalog that contains the table.
Example
The statement MMDB.getTables ("EmpDB"); might produce an array of two objects. The
first object’s properties might be similar to the following example:
object1[table:"Employees", schema:"personnel", catalog:"syscat"]
The second object’s properties might be similar to the following example:
object2[table:"Departments", schema:"demo", catalog:"syscat2"]
MMDB.getViews()
Availability
Dreamweaver UltraDev 4.
Description
This function gets a list of all the views that are defined for the specified database. Each view
object has
Arguments
connName
■ The connName argument is a connection name that is specified in the Connection
96 The Database API
catalog, schema, and view properties.
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
Returns
An array of view objects where each object has three properties: catalog, schema, and view.
Use
catalog or schema to restrict or filter the number of views that pertain to an individual
schema name or catalog name that is defined as part of the connection information.
Example
The following example returns the views for a given connection value,
CONN_LIST.getValue():
var viewObjects = MMDB.getViews(CONN_LIST.getValue())
for (i = 0; i < viewObjects.length; i++)
{
thisView = viewObjects[i]
thisSchema = Trim(thisView.schema)
if (thisSchema.length == 0)
{
thisSchema = Trim(thisView.catalog)
}
if (thisSchema.length > 0)
{
thisSchema += "."
}
views.push(String(thisSchema + thisView.view))
}
MMDB.showResultset()
Availability
Dreamweaver UltraDev 1.
Description
This function displays a dialog box that contains the results of executing the specified SQL
statement.The dialog box displays a tabular grid in which the header provides column
information that describes the result set. If the connection string or the SQL statement is
invalid, an error appears. This function validates the SQL statement.
Arguments
connName, SQLstatement
■ The connName argument is a connection name that is specified in the Connection
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
■ The SQLstatement argument is the SQL SELECT statement.
Database access functions 97
Returns
Nothing. This function returns an error if the SQL statement or the connection string is
invalid.
Example
The following code displays the results of the executed SQL statement:
MMDB.showResultset("EmpDB","Select EmpName,EmpFirstName,Age ¬
from Employees")
MMDB.showSPResultset()
Availability
Dreamweaver UltraDev 1.
Description
This function displays a dialog box that contains the results of executing the specified stored
procedure. The dialog box displays a tabular grid in which the header provides column
information that describes the result set. If the connection string or the stored procedure is
invalid, an error appears. This function validates the stored procedure.
Arguments
connName, procName, paramValuesArray
■ The connName argument is a connection name that is specified in the Connection
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
■ The procName argument is the name of the stored procedure to execute.
■ The paramValuesArrayargument is an array that contains a list of design-time parameter
test values. Specify the parameter values in the order in which the stored procedure expects
them. You can use the
the stored procedure.
MMDB.getSPParamsAsString() function to get the parameters of
Returns
This function returns an error if the SQL statement or the connection string is invalid;
otherwise, it returns nothing.
Example
The following code displays the results of the executed stored procedure:
var paramValueArray = new Array("2/1/2000", "50000")
98 The Database API
MMDB.showSPResultset("EmpDB", "getNewEmployeesMakingAtLeast", ¬
paramValueArray)
MMDB.showSPResultsetNamedParams()
Availability
Dreamweaver UltraDev 1.
Description
This function displays a dialog box that contains the result set of the specified stored
procedure. The dialog box displays a tabular grid in which the header provides column
information that describes the result set. If the connection string or the stored procedure is
invalid, an error appears. This function validates the stored procedure. This function differs
from the
by name instead of the order in which the stored procedure expects them.
Arguments
connName, procName, paramNameArray, paramValuesArray
■ The connName argument is a connection name that is specified in the Connection
■ The procName argument is the name of the stored procedure that returns the result set
■ The paramNameArray argument is an array that contains a list of parameter names. You
■ The paramValuesArray argument is an array that contains a list of design-time parameter
MMDB.showSPResultset() function because you can specify the parameter values
Manager. It identifies the connection string that Dreamweaver should use to make a
database connection to a live data source.
when it executes.
can use the
MMDB.getSPParamsAsString() function to get the parameters of the
stored procedure.
test values.
Returns
This function returns an error if the SQL statement or the connection string is invalid;
otherwise, it returns nothing.
Example
The following code displays the results of the executed stored procedure:
var paramNameArray = new Array("startDate", "salary")
var paramValueArray = new Array("2/1/2000", "50000")
MMDB.showSPResultsetNamedParams("EmpDB","getNewEmployees¬
MakingAtLeast", paramNameArray, paramValueArray)
Database access functions 99
100 The Database API
Loading...