API REFERENCE
ADOBE® DREAMWEAVER® CS
3
© 2007 Adobe Systems Incorporated. All rights reserved.
Adobe® Dreamweaver® CS3 API Reference for Windows® and Macintosh
If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished under license and may be used or
copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the
content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement. The content of this guide is furnished
for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated
assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide.
Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The unauthorized incorporation of such
material into your new work could be a violation of the rights of the copyright owner. Please be sure to obtain any permission required from the copyright owner. Any references
to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization.
Adobe, the Adobe logo, ActionScript, Adobe Bridge, ColdFusion, Creative Suite, Director, Dreamweaver, Fireworks, Flash, FlashPaper, HomeSite, JRun, Photoshop, Shockwave,
and Version Cue are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States.
ActiveX, Microsoft, and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Apple andMac OS are
trademarks of Apple Computer Inc., registered in the United States and other countries. Java and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in
the United States and other countries. Linux is the registered trademark of Linus Torvalds in the U.S. and other countries. UNIX is a trademark in the United States and other
countries, licensed exclusively through X/Open Company, Ltd. All other trademarks are the property of their respective owners.
This product includes software developed by the Apache Software Foundation (http://www.apache.org/). The Graphics Interchange Format © is the Copyright property of
CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated. MPEG Layer-3 audio compression technology licensed by Fraunhofer IIS and
Thomson Multimedia (http://www.mp3licensing.com). You cannot use the MP3 compressed audio within the Software for real time or live broadcasts. If you require an MP3
decoder for real time or live broadcasts, you are responsible for obtaining this MP3 technology license. Speech compression and decompression technology licensed from Nellymoser, Inc. (www.nellymoser.com) Flash CS3 video is powered by On2 TrueMotion video technology. © 1992-2005 On2 Technologies, Inc. All Rights Reserved.
http://www.on2.com. This product includes software developed by the OpenSymphony Group (http://www.opensymphony.com/) Sorenson SparkTM video compression and
decompression technology licensed from Sorenson Media, Inc.
Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.
No tic e to U.S . Go ve rnm ent En d Us ers . Th e S oft wa re a nd D oc um ent ati on are “Co mme rci al Ite ms,” a s t hat ter m i s de fi ned at 48 C .F.R . §2.101, consisting of “Commercial Computer
Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R.
§12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being
licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions
herein. Unpublishedrights reserved under the copyright laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA 95110-2704, USA. For U.S.
Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of Executive Order 11246, as amended,
Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations
at 41 CFR Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference.
Contents
Chapter 1: Introduction
Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Extending Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Additional resources for extension writers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
New functions in Dreamweaver CS3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Removed functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Errata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Conventions used in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Chapter 2: The file I/O API
Accessing configuration folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
The file I/O API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Chapter 3: The HTTP API
How the HTTP API works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
The HTTP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
iii
Chapter 4: The Design Notes API
How Design Notes work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
The Design Notes JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
The Design Notes C API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Chapter 5: Fireworks integration
The FWLaunch API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Chapter 6: Flash integration
How Flash elements work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Inserting Flash elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
The Flash Objects API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Chapter 7: The database API
How database API functions work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Database connection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Database access functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Chapter 8: The database connectivity API
How to develop a new connection type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
The Connection API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
The generated include file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
The definition file for your connection type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Chapter 9: The JavaBeans API
The JavaBeans API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Chapter 10: The source control integration API
How source control integration with Dreamweaver works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Adding source control system functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
The source control integration API required functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
The source control integration API optional functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Enablers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Chapter 11: Application
External application functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Global application functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Bridge communication functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Chapter 12: Workspace
History functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Insert object functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Keyboard functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Menu functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Results window functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Toggle functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Too lba r fun ctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Window functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Code collapse functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Code view toolbar functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
iv
Chapter 13: Site
Report functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Site functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Chapter 14: Document
Conversion functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Command functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
File manipulation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Global document functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Path functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Selection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
String manipulation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Translation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
XSLT functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Chapter 15: Page content
Assets panel functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Behavior functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Clipboard functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Library and template functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Snippets panel functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Spry widget editing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Inserting Spry widgets functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Browser compatibility check functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Chapter 16: Dynamic documents
Server components functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Data source functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Extension Data Manager functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Live data functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Server behavior functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Server model functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Chapter 17: Design
CSS layout functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Frame and frameset functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Layer and image map functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Layout environment functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Layout view functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Zoom functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
Guide functions and properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Table editing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
v
Chapter 18: Code
Code functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Find and replace functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
General editing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Print function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Quick Tag Editor functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Code view functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Tag editor and tag library functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Chapter 19: Enablers
Enabler functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
Chapter 1: Introduction
The Adobe Dreamweaver CS3 API Reference describes the application programming interfaces
(APIs) that let you perform various supporting tasks when developing Adobe® Dreamweaver®
CS3 extensions and adding program code to your Dreamweaver web pages. These APIs include
the main JavaScript API, which provides access to much of the core functionality of Dreamweaver (generally anything that can be done with a menu, and more), and various utility APIs
for performing such common tasks as reading and writing files, transferring information with
HTTP, and communicating with Fireworks and Flash.
The utility APIs contain subsets of related functions that let you perform specific types of tasks.
The utility APIs include:
• 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 Adobe Fireworks
• Flash Integration, which contains information about adding Flash elements to the Dream-
weaver user interface (UI) and details on the Flash Objects API (which lets you build objects
that create Adobe 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 corre-
sponding 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
DREAMWEAVER CS3
API Reference
Th e exte nsiv e JavaScr ipt A PI let s you perfo rm a di vers e s et o f sma ller tas ks, m any of w hi ch a re t asks t hat a user wo uld
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.
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 Dream-
weaver 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.
2
Additional resources for extension writers
To communicate with other developers who are involved in writing extensions, to join the Dreamweaver extensibility newsgroup. You can access the website for this newsgroup at www.adobe.com/support/dream-
weaver/extend/form/.
New functions in Dreamweaver CS3
The following new functions are added to the Dreamweaver CS3 JavaScript API. The headings designate the chapters
and sections that contain the new functions:
Application
The following functions are added to the Application chapter.
External application functions
• “dom.insertFiles()” on page 111
• “dreamweaver.activateApp()” on page 111
• “dreamweaver.printDocument()” on page 111
• “dreamweaver.revealDocument()” on page 112
General application functions
• “dw.registerIdleHandler()” on page 115
• “dw.revokeIdleHandler()” on page 116
Bridge Communication
• “BridgeTalk.bringToFront()” on page 117
• “Bridgetalk.send()” on page 117
• “BridgeTalk.suppressStartupScreen()” on page 118
• “dw.browseInBridge()” on page 118
Workspace
The following new Active Content and Code View functions are added to “Workspace” on page 119.
Active content
• “dom.convertNextActiveContent()” on page 129
DREAMWEAVER CS3
API Reference
3
• “dom.convertActiveContent()” on page 129
Code view
• “dom.source.refreshVariableCodeHints()” on page 191
Site
The following new Site functions are added to “Site” on page 193.
• “site.displaySyncInfoForFile()” on page 204
• “site.canDisplaySyncInfoForFile()” on page 464
Documents
The following new XML dataset function is added to “Document” on page 227.
• “MMXSLT.getXML()” on page 267
Page content
The following new functions are added to “Page content” on page 270. They address creating Spry XML datasets,
enhanced editing of Spry and other widgets, inserting Spry widgets, and browser compatibility checking.
Spry widget editing
• “element.removeTranslatedAttribute()” on page 302
• “element.setTranslatedAttribute()” on page 302
• “element.translatedClassName” on page 303
• “element.translatedStyle” on page 303
Spry widget insertion
• “dom.addJavaScript()” on page 303
• “dom.copyAssets()” on page 304
• “dom.getDefaultAssetFolder()” on page 305
Browser compatibility check issues
• “elem.getComputedStyleProp()” on page 306
• “window.getDeclaredStyle()” on page 307
• “dom.getMinDisplayWidth()” on page 307
• “dom.getBlockElements() elem.getBlockElements()” on page 308
• “dom.getInlineElements() elem.getInlineElements()” on page 309
• “dom.getHeaderElements() elem.getHeaderElements()” on page 310
• “dom.getListElements() elem.getListElements()” on page 310
• “elem.isBlockElement()” on page 311
• “elem.isInlineElement()” on page 311
• “elem.isHeaderElement()” on page 312
• “elem.isListElement()” on page 312
DREAMWEAVER CS3
API Reference
4
Dynamic documents
The following new Data source function is added to “Dynamic documents” on page 314.
• “dw.dbi.setExpanded()” on page 316
Design
The following new CSS Layout functions are added to “Design” on page 332:
CSS Layout
• “dom.applyLayout()” on page 332
• “dom.canApplyLayout()” on page 333
• “dw.getLayoutNames()” on page 334
• “dw.getLayoutDescriptions()” on page 334
• “dw.getFilesForLayout()” on page 334
Removed functions
The following functions are removed from the Dreamweaver CS3 API because the associated features are removed
from the product.
• “dreamweaver.exportCSS() (deprecated)” on page 235
• “dreamweaver.canExportCSS() (deprecated)” on page 447
DREAMWEAVER CS3
API Reference
Errata
A current list of known issues can be found in the Extensibility section of the Dreamweaver Support Center
(www.adobe.com/support/dreamweaver/extend/extending_dwmx_errata).
Conventions used in this guide
Typographical conventions
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
examples use the
dw. prefix, however.
dreamweaver. prefix when defining the function and in the index. Many
5
Naming conventions
The following naming conventions are used in this guide:
• You—the developer who is responsible for writing extensions
• The user—the person using Dreamweaver
Chapter 2: The file I/O API
Adobe® Dreamweaver® CS3 includes a C shared library called DWfile, which lets authors of
objects, commands, behaviors, data translators, floating panels, and Property inspectors 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.
The file I/O API
All functions in the file I/O API are methods of the DWfile object.
DWfile.copy()
Availability
Dreamweaver 3.
DREAMWEAVER CS3
API Reference
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()
7
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.
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.
DREAMWEAVER CS3
API Reference
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.");
}
8
DWfile.getAttributes()
Availability
Dreamweaver 2.
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
• 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:
null value. The following characters in the string represent the attributes:
DREAMWEAVER CS3
API Reference
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.
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.
9
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
DREAMWEAVER CS3
API Reference
• 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.
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);
}
10
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.
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.
DREAMWEAVER CS3
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()
API Reference
11
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 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"));
}
DREAMWEAVER CS3
API Reference
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
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);
}
null value if the read fails.
12
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:
Example
The following example uses the
confirm() function to display a Yes/No dialog box to the user:
the
function deleteFile(){
var delAnyway = false;
var selIndex = document.theForm.menu.selectedIndex;
true value if the operation succeeds; false otherwise.
DWfile.getAttributes() function to determine whether the file is read-only and
DREAMWEAVER CS3
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);
}
}
}
DWfile.setAttributes()
Availability
Dreamweaver MX.
Description
This function sets the system-level attributes of a particular file.
Arguments
fileURL, strAttrs
• The fileURL argument, which is expressed as a file:// URL, identifies the file for which you are setting the
attributes.
API Reference
13
• 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
Acceptable values for the
You should not use
R and W together because they are mutually exclusive. If you combine them, R becomes
meaningless, and the file is set as writable (
exclusive. If you combine them,
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
Read only
Writable (overrides R)
Hidden
Visible (overrides H)
strAttrs string are R, W, H, V, RH, RV, WH, or WV.
W). You should not use H and V together because they are also mutually
H becomes meaningless, and the file is set as visible (V).
R or W, without specifying an H or V visibility attribute, the existing visibility
attribute for the file is not changed.
Returns
Nothing.
DWfile.write()
Availability
Dreamweaver 2.
DREAMWEAVER CS3
API Reference
Description
This function writes the specified string to the specified file. If the specified file does not yet exist, it is created.
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
operation succeeds. It then tries to append the string
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);
}
"xxx" to the mydata.txt file and displays an alert message if the w rite
"aaa" to the file and displays a second alert if the write
xxxaaa and nothing else.
14
Chapter 3: The HTTP API
Extensions are not limited to working in the local file system. Adobe® Dreamweaver® CS3
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.
statusCode property indicates the status of the operation; possible values include, but are
The
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
the individual function listings.
data property varies according to the function; possible values are specified in
DREAMWEAVER CS3
API Reference
Functions that return an obj ect 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/
model
/_mmDBScripts folder.
server-
16
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.
Returns
An object that represents the reply from the server. The
contents of the deleted scripts. If an error occurs, Dreamweaver reports it in the
data property of this object is a string that contains 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">
</SCRIPT>
<body onLoad="MMHttp.clearServerScriptsFolder()">
</body>
</html>
DREAMWEAVER CS3
API Reference
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>
17
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 prompt argument, which is optional, is a Boolean value that specifies whether to prompt the user to save the
saveURL is outside the Configuration/Temp folder, a prompt value of false is ignored for security reasons.
file. If
• 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
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.
true value or saveURL is outside the Configuration/Temp folder,
DREAMWEAVER CS3
API Reference
Returns
An object that represents the reply from the server. The
location where the file is saved, which is expressed as a file:// URL. Normally, the
data property of this object is a string that contains 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
18
• 12: Lock violation
• 13: Disk full
• 14: End of file reached
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 (Boolean == 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}
DREAMWEAVER CS3
API Reference
• 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
saveURL argument specifies a location outside the Configuration/Temp folder, a prompt value of false is
file. If
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
the user can override
saveURL in the Save dialog box.
true value or saveURL is outside the Configuration/Temp folder,
• 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
location where the file was saved, which is expressed as a file:// URL. Normally the
data property of this object is a string that contains 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()” on page 17 for a list of possible error codes.
19
MMHttp.getText()
Availability
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 Config-
uration 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.
DREAMWEAVER CS3
API Reference
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 Config-
uration 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
callbackFunc identifies.
20
If an error occurs, Dreamweaver MX reports it in the
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-urlen-
coded"
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
• The serverScriptsFolder argument is an optional string that names a particular folder—relative to the Config-
uration 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
"application/x-www-form-urlencoded".
statusCode property of the returned object.
Example
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:
DREAMWEAVER CS3
API Reference
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.
Arguments
callbackFunc, URL, dataToPost, {contentType}, {serverScriptsFolder}
21
• 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-urlen-
coded"
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
"application/x-www-form-urlencoded".
• The serverScriptsFolder argument is an optional string. It names a particular folder, relative to the Configu-
ration 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.
Chapter 4: The Design Notes API
Adobe® Dreamweaver® CS3, Fireworks, and 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.
The following example shows the Design Notes file for foghorn.gif.mno:
DREAMWEAVER CS3
API Reference
<?xml version="1.0" encoding="iso-8859-1" ?>
<info>
<infoitem key="FW
foghorn.png" />
<infoitem key="Author" value="Heidi B." />
<infoitem key="Status" value="Final draft, approved by Jay L." />
</info>
_source" value="file:///C|sites/dreamcentral/images/sourceFiles/¬
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.
23
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 27.
MMNotes.filePathToLocalURL()
Description
This function converts the specified local drive path to a file:// URL.
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
"file:///c|/sites/webdev/index.htm".
MMNotes.filePathToLocalURL('C:\sites\webdev\index.htm') returns
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 24.
MMNotes.getKeyCount()
Description
This function gets the number of key/value pairs in the specified Design Notes file.
DREAMWEAVER CS3
API Reference
24
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.
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 +=0theKeys[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.
DREAMWEAVER CS3
API Reference
25
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.
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
inspector, floating panel, or data translator returns
function from Fireworks also returns
was created by the Dreamweaver engineering team.
MMNotes.getVersionName() function from a Dreamweaver command, object, behavior, Property
"Dreamweaver". Calling the MMNotes.getVersionName()
"Dreamweaver" because Fireworks uses the same version of the library, which
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.
Returns
A string that contains the local drive path for the specified file.
Example
A call to
toshHD:images:moon.gif"
MMNotes.localURLToFilePath('file:///MacintoshHD/images/moon.gif') returns "Macin-
.
DREAMWEAVER CS3
API Reference
26
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
filePath argument is not associated with any site.
Returns
The file handle for the Design Notes file or 0 if the file was not opened or created.
Example
See “MMNotes.set()” on page 27.
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.
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.
DREAMWEAVER CS3
API Reference
27
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.
DREAMWEAVER CS3
API Reference
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
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.
28
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
• 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 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.
noteHandle, const char keyName[64], char* valueBuf, int valueBufLength
Returns
A Boolean value:
value of the key.
true indicates the operation is successful; false otherwise. The valueBuf argument receives the
DREAMWEAVER CS3
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]
API Reference
29
• 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 28.
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
DREAMWEAVER CS3
API Reference
• 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);
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);
30
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:
the address of the buffer that stores the site root. If you specify the
the Design Notes preferences for the site. The
DesignNotes
true indicates the operation is successful; false otherwise. The siteRootBuf argument receives
infoPrefs argument, the function also returns
InfoPrefs struct has two variables: bUseDesignNotes and bUpload-
, both of type BOOL.
DREAMWEAVER CS3
API Reference
BOOL GetVersionName()
Description
This function gets the version name of the MMNotes shared library, which indicates the application that implemented it.
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:
versionNameBuf argument.
in
true indicates the operation is successful; false otherwise. Dreamweaver stores "Dreamweaver"
BOOL GetVersionNum()
Description
This function gets the version number of the MMNotes shared library, which lets you determine whether certain
functions are available.
31
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*
• 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.
Returns
A Boolean value:
the local drive path.
localURL, char* drivePathBuf, int drivePathMaxLen
true indicates the operation is successful; false otherwise. The drivePathBuf argument receives
DREAMWEAVER CS3
API Reference
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.
32
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
false. You can specify the bReadOnly argument starting in version 2 of the
MMNotes.dll file.
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.
DREAMWEAVER CS3
API Reference
33
Chapter 5: Fireworks integration
FWLaunch is a C shared library that lets authors of objects, commands, behaviors, and
Property inspectors communicate with Adobe® 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 Extending Fireworks. For general information on how C
libraries interact with the JavaScript interpreter in Adobe® Dreamweaver® CS3, 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.
Description
This function brings Dreamweaver to the front.
Arguments
None.
Returns
Nothing.
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.
DREAMWEAVER CS3
API Reference
35
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).
• 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
InFireworks()
function, whether the script completed successfully, or whether an error occurred.
FWLaunch.execJs-
DREAMWEAVER CS3
API Reference
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
operation completes successfully, a
null value if Fireworks is still executing the JavaScript, or a nonzero error code
FWLaunch.execJsInFireworks() function if the
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.
Example
The following code passes the string
works()
and checks for the result:
"prompt('Please enter your name:')" to FWLaunch.execJsInFire-
36
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.
DREAMWEAVER CS3
API Reference
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.
FWLaunch.optimizeInFireworks()
Availability
Dreamweaver 2, Fireworks 2.
Description
This function opens a Fireworks optimization session for the specified image.
Arguments
docURL, imageURL, {targetWidth}, {targetHeight}
37
• 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
docURL argument.
• 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 null
value or an empty string.
• 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 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.
FWLaunch.validateFireworks()
Availability
Dreamweaver 2, Fireworks 2.
Description
This function looks for the specified version of Fireworks on the user’s hard disk.
DREAMWEAVER CS3
API Reference
Arguments
{versionNumber}
• The versionNumber argume nt is a n optio nal flo ati ng- point number tha t is gre ater th an or eq ual to 2 ; it re presents
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;
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 || ¬
38
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);
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 + "!");
}
}
}
DREAMWEAVER CS3
API Reference
39
</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>
DREAMWEAVER CS3
API Reference
40
Chapter 6: Flash integration
Ad obe ® Dre amw eav er® CS 3 pro vid es support for F lash e lemen ts as well as con tin uing sup port f or
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
Flash generates for Adobe and third-party products to use. 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
edit the
more information about working with component properties in Dreamweaver, see
Using Dreamweaver).
param tag attributes to change the properties of the element as it is published (for
param tag (a child of the object tag). Users can then
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
DREAMWEAVER CS3
API Reference
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()” on
page 127 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 button tag for a
Flash element must have both
button tag details in “Insert Bar Objects” in Extending Dreamweaver). Use the
where the source file for the element resides relative to the Objects folder. Then, use the
Dreamweaver to use the
file and command attributes to add the element successfully to the document (see the
file attribute to tell Dreamweaver
command attribute to tell
dom.insertFlashElement() function when the user clicks the button on the Insert bar.
42
The following example shows the code to place in the inserbar.xml file (either as a child of the appropriate
menubutton tag, depending on where you want the Flash element button to appear):
or
<button id="FlashElement_Nav"
name="Navigation"
file="FlashElements\nav.swc"
command="dw.getDocumentDOM().insertFlashElement('nav.swc')" />
category
Note: 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.
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()” on page 127 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.
DREAMWEAVER CS3
API Reference
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.
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
the object type, such as
"Flash Text".
• The swfFileName argu ment, whi ch is expressed as a file :// UR L, is t he output f ilena me of an SWF fil e or an empt y
string to ignore.
"dwType". Its value should be a string that represents the name of
43
• 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.
• "invalidData" means that one or more of the templateParams name/value pairs is invalid.
DREAMWEAVER CS3
• "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
"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");
"myType", which replaces any occurrences of the string
SWFFile.getNaturalSize()
Description
This function returns the natural size of any uncompressed Flash content.
API Reference
44
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 an uncompressed SWF file or a
null
value if the file is not an uncompressed SWF file.
SWFFile.getObjectType()
Description
This function returns the Flash object type; the value that passed in the
SWFFile.createFile() function created the file.
Arguments
fileName
• The fileName argument, which is expressed as a file:// URL, is a path to a Flash Object file. This file is usually a
SWF file.
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
dwType parameter when the
myType:
DREAMWEAVER CS3
API Reference
if ( SWFFile.getObjectType("file:///MyMac/test.swf") == "myType" ){
alert ("This is a myType object.");
}else{
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
if it is not a Flash Object file.
"dwType", followed by its value. The function returns a null value if the file cannot be found or
45
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
Chapter 7: 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 Adobe® Dreamweaver® CS3
server behavior, data format, and data sources APIs all use these database functions.
The functions described in this chapter are grouped into the following sections:
• “Database connection functions” on page 47
• “Database access functions” on page 59
How database API functions work
The following example shows how the server behavior function, getDynamicBindings(), is
defined for Recordset.js. This example uses the
MMDB.getColumnAndTypeList() function:
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, " ");
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;
}
DREAMWEAVER CS3
API Reference
47
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 59.
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.
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()
DREAMWEAVER CS3
API Reference
48
Availability
Dreamweaver UltraDev 4.
Description
This function gets the ColdFusion data source names (DSNs) from the site server, using the
getRDSPassword() functions.
getRDSUserName() and
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.
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
DREAMWEAVER CS3
API Reference
49
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 63)
Used to restrict the metadata that appears (for more information, see
“MMDB.getProcedures()” on page 63)
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.
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"].
DREAMWEAVER CS3
API Reference
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"
The connection strings for Connection 1 and Connection 2 are the same. Connection 2 connects to a more recent
version of the
name you want to return.
TdsDriver driver. You should pass the driver name to this function to fully qualify the connection
50
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
var connectionName = MMDB.getConnectionName ¬
("dsn=EmpDB;uid=;pwd=");
"EmpDB":
MMDB.getConnectionString()
Availability
Dreamweaver UltraDev 1.
Description
This function gets the connection string that is associated with the named connection.
Arguments
connName
DREAMWEAVER CS3
• 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.
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.
API Reference
51
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
"jdbc/oracle/driver/JdbcOracle"
MMDB.getDriverName ("EmpDB"); might return the following string:
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.
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:
DREAMWEAVER CS3
API Reference
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:
UrlTemplate2, and so on.
Driver1, UrlTemplate1, Driver2,
MMDB.getLocalDsnList()
52
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.
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.
DREAMWEAVER CS3
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()
API Reference
53
Availability
Dreamweaver UltraDev 4.
Description
This function gets the RDS user name (for use with ColdFusion connections).
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
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
snList()
generates. If the developer provides a parameter string, this function passes it to the HTTP connectivity
scripts.
getRDSUserName() and getRDSPassword() functions
MMDB.getRemoteD-
Arguments
{urlParams}
DREAMWEAVER CS3
API Reference
• 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
you can pass to
Hello World, need to be encoded. The following example shows a valid sample argument that
MMDB.getRemoteDsnList(): a=1&b=Hello%20World
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.
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.
54
Returns
A string that corresponds to the connection type. This function can return one of the following values:
"ADODSN", "JDBC", or "CFDSN".
"ADO",
Example
The following code returns the string
var connectionType = MMDB.getRuntimeConnectionType ("EmpDB")
"ADO" for an ADO connection:
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".
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.
DREAMWEAVER CS3
API Reference
55
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; 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.
DREAMWEAVER CS3
API Reference
MMDB.popupConnection()
Availability
Dreamweaver MX.
Description
This function starts a connection dialog box. This function has the following three signatures:
• If the argume nt list consis ts only of dialogFileName (a string), the popupConnection() function makes Dream-
weaver 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
or
connrec, bDuplicate
56
• The dialogFileName argument is a string that contains the name of an HTML file that resides in the Configu-
ration/Connections/server-model folder. This HT ML f ile d efi nes the dia log box that cr eates a connec tion . Th is f ile
must implement three JavaScript API functions:
nection()
. Typically, you create a JavaScript file that implements these functions and then include that file in the
findConnection(), inspectConnection(), and applyCon-
HTML file. (For more information on creating a connection, see “The database connectivity API” on page 71.)
• 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.
Arguments
username
• The username argument is a valid RDS user name.
Returns
Nothing.
MMDB.showColdFusionAdmin()
DREAMWEAVER CS3
API Reference
57
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.
DREAMWEAVER CS3
API Reference
MMDB.showOdbcDialog()
Availability
Dreamweaver UltraDev 4 (Windows only).
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.
58
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.
Arguments
catalog, schema
• The catalog argument is the initial catalog value.
• The schema argument is the initial schema value.
DREAMWEAVER CS3
API Reference
Returns
An object that contains the new values in the
indicates that the user cancelled the dialog box.
catalog and schema properties. If either property is not defined, it
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.
59
• 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 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 47.
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
the connection names programmatically.
MMDB.getConnectionList() function to get a list of all
DREAMWEAVER CS3
API Reference
• 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 (
MMDB.getSPParamsAsString() function to get the parameters of the stored procedure. If you provide
the
parameter names, the values that you specify in
names that you specify in
paramNameArray.
paramValuesArray must be in the sequence of the parameter
paramNameArray). You can use
MMDB.getColumnAndTypeList()
Availability
Dreamweaver UltraDev 1.
Description
This function gets a list of columns and their types from an executed SQL
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.
SELECT statement.
60
Returns
An array of strings that represents a list of columns (and their types) that match the
if the SQL statement is invalid or the connection cannot be made.
Example
The code
var columnArray = MMDB.getColumnAndTypeList("EmpDB","Select * from Employees") returns
the following array of strings:
columnArray[0] = "EmpName"
columnArray[1] = "varchar"
columnArray[2] = "EmpFirstName"
columnArray[3] = "varchar"
columnArray[4] = "Age"
columnArray[5] = "integer"
MMDB.getColumnList()
Availability
Dreamweaver UltraDev 1.
Description
This function gets a list of columns from an executed SQL
Arguments
connName, statement
SELECT statement.
SELECT statement, or an error
• 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") returns the
following array of strings:
columnArray[0] = "EmpName"
columnArray[1] = "EmpFirstName"
columnArray[2] = "Age"
MMDB.getColumns()
Availability
Dreamweaver MX, arguments updated in Dreamweaver MX 2004.
Description
This function returns an array of objects that describe the columns in the specified table.
DREAMWEAVER CS3
API Reference
61
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
Name of the column (for example, price)
Data type of the column (for example, small money)
Defined size of the column (for example, 8)
Indicates whether the column can contain null values
Example
The following example uses
var columnNameObjs = MMDB.getColumns(connName,tableName);
var databaseType = MMDB.getDatabaseType(connName);
MMDB.getColumns() to set the tooltip text value:
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;
}
MMDB.getColumnsOfTable()
Availability
Dreamweaver UltraDev 1.
Description
This function gets a list of all the columns in the specified table.
DREAMWEAVER CS3
API Reference
62
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
["EmpID", "FirstName", "LastName"]
MMDB.getColumnsOfTable ("EmpDB","Employees"); returns the following strings:
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.
DREAMWEAVER CS3
API Reference
• 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.
63
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
An array of procedure objects where each procedure object has the following set of three properties:
Property Name Description
schema
a
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
function accesses depends on the type of connection.
getProcedures() function accesses. The database that this
• For ODBC connections, the ODBC data source defines the database. The DSN is spec-
ified by the dsn property in the connection object (connName) that you pass to the
getProcedures() function.
• For OLE DB connections, the connection string names the database.
catalog
procedure
a. Dreamweaver connects to and gets all the tables in the database whenever you modif y 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 catalog that is associated with the object (owner qualifier).
The value of the
driver attribute defines a default
connection string does not specify a database.
Name of the procedure.
catalog property is defined by an attribute of the OLE DB driver. This
user.database property to use when the OLE DB
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 += "."
}
var procName = String(thisSchema + thisProcedure.procedure);
}
MMDB.getSPColumnList()
DREAMWEAVER CS3
API Reference
64
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
sAsString()
function to get the parameters for the stored procedure.
MMDB.getSPParam-
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,
getNewEmployeesMakingAtLeast:
var paramValueArray = new Array("2/1/2000", "50000")
var columnArray = MMDB.getSPColumnList("EmpDB", ¬
"getNewEmployeesMakingAtLeast", paramValueArray)
The following values return:
columnArray[0] = "EmpID", columnArray[1] = "LastName", ¬
columnArray[2] ="startDate", columnArray[3] = "salary"
DREAMWEAVER CS3
API Reference
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 MMDB.getSP-
ParamsAsString()
• 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
NameArray
paramNameArray. If you did not provide paramNameArray, specify the values in the order in which the stored
, specify the parameter values in the same order that their corresponding parameter names appear in
procedure expects them.
function to get the parameters of the stored procedure.
param-
65
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,
getNewEmployeesMakingAtLeast:
var paramNameArray = new Array("startDate", "salary")
var paramValueArray = new Array("2/1/2000", "50000")
var columnArray = MMDB.getSPColumnListNamedParams("EmpDB", ¬
"getNewEmployeesMakingAtLeast", paramNameArray, paramValueArray)
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
DREAMWEAVER CS3
• 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
API Reference
66
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];
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.
DREAMWEAVER CS3
API Reference
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
form name
MMDB.getSPParamsAsString ("EmpDB","getNewEmployeesMakingAtLeast") can return a string of
startDate;direction:in;datatype:date, salary;direction:in;datatype:integer.
67
In this example, the stored procedure,
Salary. For startDate, the direction is in and the data type is date. For salary, the direction is in and the data
date.
type is
getNewEmployeesMakingAtLeast, has two parameters: startDate and
MMDB.getTables()
Availability
Dreamweaver UltraDev 1.
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 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.
Example
The statement
might be similar to the following example:
table, schema, and catalog.
table, schema, and catalog. Table is the name of the
Schema is the name of the schema that contains the table. Catalog is the catalog that contains the table.
MMDB.getTables ("EmpDB"); might produce an array of two objects. The first object’s properties
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
schema, and view properties.
Arguments
connName
catalog,
DREAMWEAVER CS3
API Reference
• 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
An array of view objects where each object has three properties:
schema to restrict or filter the number of views that pertain to an individual schema name or catalog name that is
catalog, schema, and view. Use catalog or
defined as part of the connection information.
Example
The following example returns the views for a given connection value,
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))
}
CONN_LIST.getValue():
68
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.
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")
DREAMWEAVER CS3
API Reference
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
sAsString()
function to get the parameters of the stored procedure.
MMDB.getSPParam-
69
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")
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
name instead of the order in which the stored procedure expects them.
Arguments
connName, procName, paramNameArray, paramValuesArray
MMDB.showSPResultset() function because you can specify the parameter values by
• 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 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 MMDB.getSP-
ParamsAsString()
function to get the parameters of the stored procedure.
DREAMWEAVER CS3
API Reference
• The paramValuesArray argument is an array that contains a list of design-time parameter 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)
70
Chapter 8: The database connectivity API
As a developer, you can create new connection types and corresponding dialog boxes for new or
existing server models for Adobe® Dreamweaver® CS3. Then, when a user sets up a site to start
building pages, he or she creates a new connection object after selecting the particular type of
connection that you created.
The user can select your new connection type in the following ways:
• On the Application panel, the user can click the Plus (+) button and select Recordset. In the
Recordset dialog box, the user can expand the Connection list box.
• On the Database tab of the Databases panel, the user can click the Plus (+) button and select
Data Source Name.
How to develop a new connection type
The following steps outline the process for creating a new connection type:
1 Create the layout for the connection dialog box.
Create an HTML file that lays out the user interface (UI) for your connection dialog box. Name
this file using the name of the connection (for example, myConnection.htm). For information
about creating a dialog box, see Getting Started with Dreamweaver.
Make sure this HTML file includes a reference to the JavaScript implementation file that you
define in Step 2, “Create a JavaScript file that implements at least the following elements:” on
page 72, as shown in the following example:
<head>
<script SRC="../myConnectionImpl.js"></script>
</head>
Store this HTML file, which defines your connection dialog box, in the Configuration/Connections/server-model/platform folder (where the platform is either Windows or Macintosh).
DREAMWEAVER CS3
API Reference
For example, the default ADO connection dialog box for an ASP JavaScript document on a Windows platform is
stored in the ASP_Js/Win folder and is named Connection_ado_conn_string.htm.
Note: At runtime, Dreamweaver dynamically builds the list of connection types that are available to the user from the
collection of dialog boxes that are in the ASP_Js/Win folder.
The Configuration/ServerModels folder has HTML files that define each server model. Inside each HTML file is the
getServerModelFolderName() function, which returns the name of the folder that is associated with the server
model. The following example shows the function for the ASP JavaScript document type:
function getServerModelFolderName()
{
return "ASP
}
_JS";
You can also look at the MMDocumentTypes.xml file, which is located in the Configuration/DocumentTypes folder,
to determine the mapping between server models and document types.
2 Create a JavaScript file that implements at least the following elements:
Element Description Examples
72
A set of variables Each variable defines a specific connec-
tion property
A set of buttons Each button appears in the connection
dialog box
Connectivity functions Together, these functions define the
Connectivity API
Type of connection, data source
name, and so on
Test, Help, and so on (OK and
Cancel are automatically included)
findConnection()
applyConnection()
inspectConnection()
You can select any name for this implementation file, but it must have a .js extension (for example, myConnectionImpl.js). You can store this implementation file on either your local or a remote computer. You might want to
store your implementation file in the appropriate subfolder within the Configuration/Connections folder.
Note: The HTML file that you defined in Step 1, “Create the layout for the connection dialog box.” on page 71 must
include this connection type implementation file.
Unless you need to define connection parameters other than the ones provided in the standard
connection_includefile.edml file, these two steps are the minimum to create a new connection dialog box.
Note: The title of the dialog box that the user sees is in the
title tag, which is specified in the HTML document.
The functions listed in the next section let you create a connection dialog box. Along with implementing the calls
for generating include files for the user, you can register your connectivity type within the server model section of
the connection XML file.
For information about the Database Connectivity API that is associated with creating a new connection, see
“Database connection functions” on page 47.
DREAMWEAVER CS3
API Reference
The Connection API
To create a new type of connection, including the dialog box with which users interact, you must implement the
following three functions:
three functions and include them in the JavaScript implementation file that is associated with your new connection
type (see Step 2 “Create a JavaScript file that implements at least the following elements:” on page 72).
applyConnection() function returns an HTML source within an include file. You can see examples of the
The
HTML source in “The generated include file” on page 75. The
and extracts its properties. You can implement
the information that returns from
following two JavaScript files:
• connection_ado_conn_string.js is located in Configuration/Connections/ASP_Js folder.
• connection_common.js is located in Configuration/Connections/Shared folder.
When the user opens a site, Dreamweaver goes through each file in the Connections folder, opens it, and passes the
contents to
nection()
findConnection(). If the contents of a file match the criteria for a valid connection, findCon-
returns a connection object. Dreamweaver then lists all the connection objects in the Database Explorer
panel.
findConnection(), inspectConnection(), and applyConnection(). You write these
findConnection() function takes the HTML source
findConnection() to use the search patterns in XML files to extract
applyConnection(). For an example of such an implementation, see the
73
When the user opens a connection dialog box and selects to create a new connection or duplicate or edit an existing
connection, Dreamweaver calls the
findConnection() created. This process lets Dreamweaver populate the dialog box with the connection infor-
that
inspectConnection() function and passes back the same connection object
mation.
When the user clicks OK in a connection dialog box, Dreamweaver calls the
applyConnection() function to build
the HTML, which is placed in the connection include file that is located in the Configuration/Connections folder.
applyConnection() function returns an empty string that indicates there is an error in one of the fields and
The
the dialog box should not be closed. The include file has the default file extension type for the current server model.
When the user adds to the page a server behavior that uses the connection, such as a recordset or a stored procedure,
Dreamweaver adds a statement to the page that includes the connection include file.
findConnection()
Availability
Dreamweaver UltraDev 4.
Description
Dreamweaver calls this function to detect a connection in the specified HTML source and to parse the connection
parameters. If the contents of this source file match the criteria for a valid connection,
a connection object; otherwise, this function returns a
null value.
Argument
htmlSource
findConnection() returns
The htmlSource argument is the HTML source for a connection.
Returns
A connection object that provides values for a particular combination of the properties that are listed in the following
table. The properties for which this function returns a value depend on the document type.
Property Description
DREAMWEAVER CS3
API Reference
74
name
type
string
dsn
driver
username
password
designtimeString
designtimeDsn
designtimeDriver
designtimeUsername
designtimePassword
designtimeType
usesDesigntimeInfo
Name of the connection
If useHTTP is false, indicates which DLL to use for connecting to database
at runtime
Runtime connection string. For ADO, it is a string of connection parameters; for
JDBC, it is a connection URL
Data source name used for ODBC or Cold Fusion runtime connections
Name of a JDBC driver used at runtime
Name of the user for the runtime connection
Password used for the runtime connection
Design-time connection string (see string)
Design-time data source name (see dsn)
Name of a JDBC driver used at design time
Name of the user used for the design-time connection
Password used for the design-time connection
Design-time connection type
When false, Dreamweaver uses runtime properties at design time; otherwise,
Dreamweaver uses design-time properties
useHTTP
includePattern
variables
catalog
schema
filename
String containing either true or false: true specifies to use HTTP connection at design time; false specifies to use DLL
Regular expression used to find the file include statement on the page during
Live Data and Preview In Browser
Object with a property for each page variable that is set to its corresponding
value. This object is used during Live Data and Preview In Browser
String containing a database identifier that restricts the amount of metadata
that appears
String containing a database identifier that restricts the amount of metadata
that appears
Name of the dialog box used to create the connection
If a connection is not found in htmlSource, a null value returns.
Note: Developers can add custom proper ties (for example, metadata) to the HTML source, which
returns along with the standard properties.
inspectConnection()
Availability
Dreamweaver UltraDev 4.
applyConnection()
DREAMWEAVER CS3
API Reference
Description
Dreamweaver calls this function to initialize the dialog box data for defining a connection when the user edits an
existing connection. This process lets Dreamweaver populate the dialog box with the appropriate connection information.
Argument
parameters
The parameters argument is the same object that the findConnection() function returns.
Returns
Nothing.
applyConnection()
Availability
Dreamweaver UltraDev 4.
Description
Dreamweaver calls this function when the user clicks OK in the connection dialog box. The
function generates the HTML source for a connection. Dreamweaver writes the HTML to the Configuration/Connections/connection-name.ext include file, where connection-name is the name of your connection
(see “Create the layout for the connection dialog box.” on page 71), and .ext is the default extension that is associated
with the server model.
applyConnection()
75
Arguments
None.
Returns
The HTML source for a connection. Dreamweaver also closes the connection dialog box. If a field validation error
applyConnection() displays an error message and returns an empty string to indicate that the dialog box
occurs,
should remain open.
The generated include file
The include file that applyConnection() generates declares all the properties of a connection.The filename for the
include file is the connection name and has the file extension that is defined for the server model associated with the
current site.
Note: Connections are shared, so set the
included in the document only once and that the server script remains in the page if any other server behaviors use it.
The following sections illustrate some sample include files that
server models.
Note: To create a new connection include file format, you need to define a new EDML mapping file, which should be
similar to connection_includefile.edml, as shown in “The definition file for your connection type” on page 77.
allowMultiple value to false. This ensures that the connection file is
applyConnection() generates for various default
DREAMWEAVER CS3
API Reference
ASP JavaScript
The ASP and JavaScript include file should be named MyConnection1.asp, where MyConnection1 is the name of the
connection. The following sample is an include file for an ADO connection string:
<%
// Filename="Connection
// Type="ADO"
// HTTP="true"
// Catalog=""
// Schema=""
var MM
_MyConnection1_STRING = "dsn=pubs";
%>
_ado_conn_string.htm"
The server behavior file includes this connection by using the relative file include statement, as shown in the
following example:
<!--#include file="../Connections/MyConnection1.asp"-->
ColdFusion
When you use UltraDev 4 ColdFusion, Dreamweaver relies on a ColdFusion include file to get a list of data sources.
Note: For regular Dreamweaver ColdFusion, Dreamweaver ignores any include files and, instead, makes use of RDS to
retrieve the list of data sources from ColdFusion.
76
The UltraDev 4 ColdFusion include file should be named MyConnection1.cfm, where MyConnection1 is the name
of your connection. The following example shows the include file for a ColdFusion connection to a product table:
<!-- FileName="Connection_cf_dsn.htm" "dsn=products" -->
<!-- Type="ADO" -->
<!-- Catalog="" -->
<!-- Schema="" -->
<!-- HTTP="false" -->
<CFSET MM_MyConnection1_DSN = "products">
<CFSET MM_MyConnection1_USERNAME = "">
<CFSET MM_Product_USERNAME = "">
<CFSET MM_MyConnection1_PASSWORD = "">
The server behavior file includes this connection by using the cfinclude statement, as shown in the following
example:
<cfinclude template="Connections/MyConnection1.cfm">
JSP
The JSP include file should be named MyConnection1.jsp, where MyConnection1 is the name of your connection.
The following example is the include file for a JDBC connection to a database:
DREAMWEAVER CS3
API Reference
<%
// Filename="Connection_jdbc_conn1.htm"
// Type="JDBC"
// HTTP="false"
// Catalog=""
// Schema=""
String MM_MyConnection1_DRIVER = "com.inet.tds.TdsDriver";
String MM_MyConnection1_USERNAME = "testadmin";
String MM_MyConnection1_PASSWORD = "velcro";
String MM_MyConnection1_URL = "jdbc:server:test-3:1433?database=pubs";
%>
The server behavior file includes this connection by using the relative file include statement, as shown in the
following example:
<%@ include file="Connections/MyConnection1.jsp" %>
The definition file for your connection type
For each server model, there is a connection_includefile.edml file that defines the connection type and maps the
properties that are defined in the include file to elements in the Dreamweaver interface.
77
Dreamweaver provides seven default definition files, one for each of the predefined server models, as listed in the
following table.
Server model Subfolder within the Configuration/Connections folder
ASP JavaScript ASP_Js
ASP.NET CSharp ASP.NET_Csharp
ASP.NET VBScript ASP.NET_VB
ASP VBScript ASP_Vbs
ColdFusion ColdFusion
JavaServer Page JSP
PHP MySql PHP_MySql
Dreamweaver uses the
insertText pa rame ter to cre ate conne ct ion blo cks. Fo r mo re i nfor mat ion o n EDM L tags and a ttr ibut es, a nd re gular
quickSearch and searchPattern parameters to recognize connection blocks and the
expression search patterns, see “Server Behaviors” in Extending Dreamweaver.
Note: If you change the format of your include file or define an include file for a new server model, you need to map the
connection parameters with the Dreamweaver UI, Live Data, and Preview In Browser. The following sample EDML file,
which is associated with the default ASP JS server model, maps all connection page variables with their respective live
values before sending the page to the server. For more information on EDML and regular expression search patterns, see
“Server Behaviors” in Extending Dreamweaver.
<participant name="connection_includefile" version="5.0">
<quickSearch>
<![CDATA[// HTTP=]]></quickSearch>
<insertText location="">
<![CDATA[<%
// FileName="@@filename@@"
// Type="@@type@@" @@designtimeString@@
// DesigntimeType="@@designtimeType@@"
// HTTP="@@http@@"
// Catalog="@@catalog@@"
// Schema="@@schema@@"
var MM
_@@cname@@_STRING = @@string@@
%>
]]>
</insertText>
<searchPatterns whereToSearch="directive">
<searchPattern paramNames="filename">
<![CDATA[/\/\/\s*FileName="([^"]*)"/]]></searchPattern>
<searchPattern paramNames="type,designtimeString">
<![CDATA[/\/\/\s+Type="(\w*)"([^\r\n]*)/]]></searchPattern>
<searchPattern paramNames="designtimeType" isOptional="true">
<![CDATA[/\/\/\s*DesigntimeType="(\w*)"/]]></searchPattern>
<searchPattern paramNames="http">
<![CDATA[/\/\/\s*HTTP="(\w+)"/]]></searchPattern>
<searchPattern paramNames="catalog">
<![CDATA[/\/\/\s*Catalog="(\w*)"/]]></searchPattern>
<searchPattern paramNames="schema">
<![CDATA[/\/\/\s*Schema="(\w*)"/]]></searchPattern>
<searchPattern paramNames="cname,string">
<![CDATA[/var\s+MM
</searchPatterns>
</participant>
_(\w*)_STRING\s*=\s*([^\r\n]+)/]]></searchPattern>
DREAMWEAVER CS3
API Reference
78
Tokens in an EDML file—such as @@filename@@ in this example—map values in the include file to properties of a
connection object. You set the properties of connection objects in the JavaScript implementation file.
All the default connection dialog boxes that come with Dreamweaver use the connection_includefile.edml mapping
file. To let Dreamweaver find this file, its name is set in the JavaScript implementation file, as shown in the following
example:
var PARTICIPANT_FILE = "connection_includefile";
When you create a custom connection type, you can use any mapping file in your custom dialog boxes. If you create
a mapping file, you can use a name other than connection_includefile for your EDML file. If you use a different
name, you need to use this name in your JavaScript implementation file when you specify the value that is assigned
PARTICIPANT_FILE variable, as shown in the following example:
to the
var PARTICIPANT_FILE = "myConnection_mappingfile";
Chapter 9: The JavaBeans API
This chapter explains the APIs for JavaBeans; the MMJB*() functions are JavaScript hooks that
starts Java introspection calls for JavaBeans support. These functions get class names, methods,
properties, and events from the JavaBeans, which can appear in the Dreamweaver user interface
(UI). To use these JavaScript functions and let Adobe® Dreamweaver® CS3 access your JavaBeans,
the JavaBeans must reside in the Configuration/Classes folder.
Note: The function arguments described in this chapter sometimes contain an argument called
packageName.className, which is intended to represent a single value.
The JavaBeans API
The following functions are methods of the MMJB object.
MMJB.getClasses()
Availability
Dreamweaver UltraDev 4.
Description
This function reads all the JavaBeans class names from the Configuration/Classes folder.
Arguments
None.
Returns
A string array of class names that are located in Configuration/Classes folder; an error returns
an empty array.
DREAMWEAVER CS3
API Reference
MMJB.getClassesFromPackage()
Availability
Dreamweaver UltraDev 4.
Description
This function reads all the JavaBeans classes from the package.
Arguments
packageName.pathName
• The packageName.pathName argument is the path to the package. It must be a Java JAR or ZIP Java archive (for
example,
C:/jdbcdrivers/Una2000_Enterprise.zip).
Returns
A string array of class names inside the particular JAR or ZIP Java archive; an error returns an empty array.
MMJB.getErrorMessage()
Availability
Dreamweaver UltraDev 4.
80
Description
This function gets the last error message from Dreamweaver that occurred while using the MMJB interface.
Arguments
None.
Returns
A string of the Dreamweaver message from the last error.
MMJB.getEvents()
Availability
Dreamweaver UltraDev 4, enhanced in Dreamweaver MX.
Description
Introspects the JavaBeans class and returns its events.
Arguments
packageName.className, {packagePath}
• The packageName.className argument is the name of the class. The class must reside in a JAR or ZIP Java
archive. If
installed in the Configuration/Classes folder.
• The packagePath argument is an optional string that points to the location of the JAR or ZIP Java archive that
contains
packagePath is omitted, the archive must reside in your system classpath or be a class file that is
className.
Returns
A string array of the events associated with
className; an error returns an empty array.
DREAMWEAVER CS3
API Reference
MMJB.getIndexedProperties()
Availability
Dreamweaver UltraDev 4, enhanced in Dreamweaver MX.
Description
Introspects the JavaBeans class and returns its indexed properties, which are design patterns that behave the same
way as collections.
Arguments
packageName.className, {packagePath}
• The packageName.className argument is the name of the class. The class must reside in a JAR or ZIP Java
archive. If
installed in the Configuration/Classes folder.
• The packagePath argument, which is optional, is a string that points to the location of the JAR or ZIP Java archive
that contains
Returns
A string array of the indexed properties associated with
packagePath is omitted, the archive must reside in your system classpath or be a class file that is
className.
className; an error returns an empty array.
81
MMJB.getMethods()
Availability
Dreamweaver UltraDev 4, enhanced in Dreamweaver MX.
Description
Introspects the JavaBeans class and returns its methods.
Arguments
packageName.className, {packagePath}
• The packageName.className argument is the name of the class. The class must reside in a JAR or ZIP Java
archive. If
packagePath is omitted, the archive must reside in your system classpath or be a class file that is
installed in the Configuration/Classes folder.
• The packagePath argument is an optional string that points to the location of the JAR or ZIP Java archive that
contains
className.
Returns
A string array of the methods associated with
className; an error returns an empty array.
MMJB.getProperties()
Availability
Dreamweaver UltraDev 4, enhanced in Dreamweaver MX.
Description
Introspects the JavaBeans class and returns its properties.
DREAMWEAVER CS3
API Reference
Arguments
packageName.className, {packagePath}
• The packageName.className argument is the name of the class. The class must reside in a JAR or ZIP Java
archive. If
packagePath is omitted, the archive must reside in your system classpath or be a class file that is
installed in the Configuration/Classes folder.
• The packagePath argument is an optional string that points to the location of the JAR or ZIP Java archive that
contains
className.
Returns
A string array of the properties associated with
className; an error returns an empty array.
MMJB.getReadProperties()
Availability
Dreamweaver MX.
Description
Gets read-only properties for JavaBeans that support get accessor calls.
82
Arguments
packageName.className, {packagePath}
• The packageName.className argument is the name of the class. The class must reside in a JAR or ZIP Java
archive. If
packagePath is omitted, the archive must reside in your system classpath or be a class file that is
installed in the Configuration/Classes folder.
• The packagePath argument, which is optional, is a string that points to the location of the JAR or ZIP Java archive
that contains
className.
Returns
A string array of read-only properties associated with
className; an error returns an empty array.
MMJB.getWriteProperties()
Availability
Dreamweaver MX.
Description
Gets write-only properties for JavaBeans that support set method calls.
Arguments
packageName.className, {packagePath}
• The packageName.className argument is the name of the class. The class must reside in a JAR or ZIP Java
archive. If
installed in the Configuration/Classes folder.
• The packagePath argument, which is optional, is a string that points to the location of the JAR or ZIP Java archive
that contains
packagePath is omitted, the archive must reside in your system classpath or be a class file that is
className.
Returns
A string array of write-only properties associated with
className; an error returns an empty array.
DREAMWEAVER CS3
API Reference
83
Chapter 10: The source control integration API
The source control integration API lets you write shared libraries to extend the Adobe® Dreamweaver® CS3 Check In/Check Out feature using source control systems (such as Sourcesafe or
CVS).
Your libraries must support a minimum set of API functions for Dreamweaver to integrate with
a source control system. And, your libraries must reside in the Program Files/Adobe/Adobe
Dreamweaver CS3/Configuration/SourceControl folder.
When Dreamweaver starts, it loads each library. Dreamweaver determines which features the
library supports by calling
exist, Dreamweaver assumes the library does not support the API. If the address exists, Dreamweaver uses the library’s version of the function to support the functionality. When a Dreamweaver user defines or edits a site and then selects the Web Server SCS tab, the choices that
correspond to the DLLs that loaded from the Program Files/Adobe/Adobe Dreamweaver
CS3/Configuration/SourceControl folder appear (in addition to the standard items) on the tab.
To create a Site > Source Control menu to which you can add custom items, add the following
code in the Site menu in the menus.xml file:
GetProcAddress() for each API function. If an address does not
<menu name="Source Control" id="DWMenu_MainSite_Site_Source¬
Control"><menuitem dynamic name="None"file="Menus/MM/¬
File_SCSItems.htm" id="DWMenu_MainSite_Site_NewFeatures_¬
Default" />
</menu>
The functions described in this chapter are grouped into the following sections:
• “The source control integration API required functions” on page 85
• “The source control integration API optional functions” on page 91
• “Enablers” on page 99
DREAMWEAVER CS3
API Reference
How source control integration with Dreamweaver works
When a Dreamweaver user selects server connection, file transfer, or Design Notes features, Dreamweaver calls the
DLL’s version of the corresponding API function (
Checkout(), Undocheckout(), and Synchronize()). The DLL handles the request, including displaying dialog
boxes that gather information or letting the user interact with the DLL. The DLL also displays information or
error messages.
The source control system can optionally support Design Notes and Check In/Check Out. The Dreamweaver user
enables Design Notes in source control systems by selecting the Design Notes tab in the Edit Sites dialog box and
checking the box that enables the feature; this process is same to enable Design Notes with FTP and LAN. If the
source control system does not support Design Notes and the user wants to use this feature, Dreamweaver transports
Design Note (MNO) files to maintain the Design Notes (as it does with FTP and LAN).
Check In/Check Out is treated differently than the Design Notes feature; if the source control system supports it, the
user cannot override its use from the Design Notes dialog box. If the user tries to override the source control system,
an error message appears.
Connect(), Disconnect(), Get(), Put(), Checkin(),
85
Adding source control system functionality
You can add source control system functionality to Dreamweaver by writing a GetNewFeatures handler that returns
a set of menu items and corresponding C functions. For example, if you write a Sourcesafe library and want to let
Dreamweaver users see the history of a file, you can write a
item and the C function name of
item is one of the items on the menu. If a user selects the History menu item, Dreamweaver calls the corresponding
function, passing the selected files to the DLL. The DLL displays the History dialog box so the user can interact with
it in the same way as Sourcesafe.
history. Then, in Windows, when the user right-clicks a file, the History menu
GetNewFeatures handler that returns the History menu
The source control integration API required functions
The source control integration API has required and optional functions. The functions listed in this section are
required.
bool SCS_GetAgentInfo()
Description
This function asks the DLL to return its name and description, which appear in the Edit Sites dialog box. The name
appears in the Server Access pop-up menu (for example, sourcesafe, webdav, perforce) and the description below the
pop-up menu.
Arguments
char name[32], char version[32], char description[256], const char *dwAppVersion
DREAMWEAVER CS3
API Reference
• The name argument is the name of the source control system. The name appears in the combo box for selecting
a source control system on the Source Control tab in the Edit Sites dialog box. The name can be a maximum of 32
characters.
• The version argument is a string that indicates the version of the DLL. The version appears on the Source
Control tab in the Edit Sites dialog box. The version can be a maximum of 32 characters.
• The description argument is a string that indicates the description of the source control system. The
description appears on the Source Control tab in the Edit Sites dialog box. The description can be a maximum of
256 characters.
• The dwAppVersion argument is a string that indicates the version of Dreamweaver that is calling the DLL. The
DLL can use this string to determine the version and language of Dreamweaver.
Returns
A Boolean value:
true if successful; false otherwise.
bool SCS_Connect()
Description
This function connects the user to the source control system. If the DLL does not have log-in information, the DLL
must display a dialog box to prompt the user for the information and must store the data for later use.
86
Arguments
void **connectionData, const char siteName[64]
• The connectionData argument is a handle to the data that the agent wants Dreamweaver to pass to it when
calling other API functions.
• The siteName argument is a string that points to the name of the site. The site name can be a maximum of 64
characters.
Returns
A Boolean value:
true if successful; false otherwise.
bool SCS_Disconnect()
Description
This function disconnects the user from the source control system.
Arguments
void *connectionData
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
Returns
A Boolean value:
true if successful; false otherwise.
DREAMWEAVER CS3
bool SCS_IsConnected()
Description
This function determines the state of the connection.
Arguments
void *connectionData
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
Returns
A Boolean value:
true if successful; false otherwise.
int SCS_GetRootFolderLength()
Description
This function returns the length of the name of the root folder.
Arguments
void *connectionData
API Reference
87
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
Returns
An integer that indicates the length of the name of the root folder. If the function returns
< 0, Dreamweaver
considers it an error and tries to retrieve the error message from the DLL, if supported.
bool SCS_GetRootFolder()
Description
This function returns the name of the root folder.
Arguments
void *connectionData, char remotePath[], const int folderLen
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
• The remotePath is a buffer where the full remote path of the root folder is stored.
• The folderLen argument is an integer that indicates the length of remotePath. This is the value that GetRoot-
FolderLength
Returns
A Boolean value:
returns.
true if successful; false otherwise.
DREAMWEAVER CS3
API Reference
int SCS_GetFolderListLength()
Description
This function returns the number of items in the passed-in folder.
Arguments
void *connectionData, const char *remotePath
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
• The remotePath argument is the full path and name of the remote folder that the DLL checks for the number of
items.
Returns
An integer that indicates the number of items in the current folder. If the function returns
< 0, Dreamweaver
considers it an error and tries to retrieve the error message from the DLL, if supported.
bool SCS_GetFolderList()
Description
This function returns a list of files and folders in the passed-in folder, including pertinent information such as
modified date, size, and whether the item is a folder or file.
88
Arguments
void *connectionData, const char *remotePath, itemInfo itemList[ ], const int numItems
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
• The remotePath argument is the path of the remote folder that the DLL checks for the number of items.
• The itemList argument is a preallocated list of itemInfo structures:
name char[256] Name of file or folder
isFolder
month
day
year
hour
minutes
seconds
type
size
bool true if folder; false if file
int Month component of modification date 1-12
int Day component of modification date 1-31
int Year component of modification date 1900+
int Hour component of modification date 0-23
int Minute component of modification date 0-59
int Second component of modification date 0-59
char[256] Type of file (if not set by DLL, Dreamweaver uses file extensions to
determine type, as it does now)
int In bytes
• The numItems argument is the number of items that are allocated for the itemList (returned from GetFolder-
ListLength
).
DREAMWEAVER CS3
API Reference
Returns
A Boolean value:
true if successful; false otherwise.
bool SCS_Get()
Description
This function gets a list of files or folders and stores them locally.
Arguments
void *connectionData, const char *remotePathList[], const char *localPathList[], const int
numItems
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
• The remotePathList argument is a list of the remote files or folders to retrieve, which is specified as complete
paths and names.
• The localPathList argument is a mirrored list of local filenames or folder paths.
• The numItems argument is the number of items in each list.
89
Returns
A Boolean value:
true if successful; false otherwise.
bool SCS_Put()
Description
This function puts a list of local files or folders into the source control system.
Arguments
void *connectionData, const char *localPathList[], const char *remotePathList[], const int
numItems
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
• The localPathList argument is the list of local filenames or folder paths to put into the source control system.
• The remotePathList argument is a mirrored list of remote filenames or folder paths.
• The numItems argument is the number of items in each list.
Returns
A Boolean value:
true if successful; false otherwise.
bool SCS_NewFolder()
Description
This function creates a new folder.
Arguments
void *connectionData, const char *remotePath
DREAMWEAVER CS3
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
• The remotePath argument is the full path of the remote folder that the DLL creates.
Returns
A Boolean value:
true if successful; false otherwise.
bool SCS_Delete()
Description
This function deletes a list of files or folders from the source control system.
Arguments
void *connectionData, const char *remotePathList[], const int numItems
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
• The remotePathList argument is a list of remote filenames or folder paths to delete.
• The numItems argument is the number of items in remotePathList.
API Reference
90
Returns
A Boolean value:
true if successful; false otherwise.
bool SCS_Rename()
Description
This function renames or moves a file or folder, depending on the values that are specified for
newRemotePath. For example, if oldRemotePath equals "$/folder1/file1" and newRemotePath equals
"$/folder1/renamefile1", file1 is renamed renamefile1 and is located in folder1.
oldRemotePath equals "$/folder1/file1" and newRemotePath equals "$/folder1/subfolder1/file1",
If
file1 is moved to the subfolder1 folder.
To find out if an invocation of this function is a move or a rename, check the parent paths of the two input values; if
they are the same, the operation is a rename.
Arguments
void *connectionData, const char *oldRemotePath, const char *newRemotePath
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
• The oldRemotePath argument is a remote file or folder path to rename.
• The newRemotePath argument is the remote path of the new name for the file or folder.
oldRemotePath and
Returns
A Boolean value:
true if successful; false otherwise.
DREAMWEAVER CS3
API Reference
bool SCS_ItemExists()
Description
This function determines whether a file or folder exists on the server.
Arguments
void *connectionData, const char *remotePath
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
• The remotePath argument is a remote file or folder path.
Returns
A Boolean value:
true if successful; false otherwise.
The source control integration API optional functions
The source control integration API has required and optional functions. The functions in this section are optional.
91
bool SCS_GetConnectionInfo()
Description
This function displays a dialog box to let the user change or set the connection information for this site. It does not
make the connection. This function is called when the user clicks the Settings button in the Remote Info section of
the Edit Sites dialog box.
Arguments
void **connectionData, const char siteName[64]
• The connectionData argument is a handle to data that the agent wants Dreamweaver to pass it when calling
other API functions.
• The siteName argument is a string that points to the name of the site. The name cannot exceed 64 characters.
Returns
A Boolean value:
true if successful; false otherwise.
bool SCS_SiteDeleted()
Description
This function notifies the DLL that the site has been deleted or that the site is no longer tied to this source control
system. It indicates that the source control system can delete its persistent information for this site.
Arguments
const char siteName[64]
• The siteName argument is a string that points to the name of the site. The name cannot exceed 64 characters.
DREAMWEAVER CS3
API Reference
Returns
A Boolean value:
true if successful; false otherwise.
bool SCS_SiteRenamed()
Description
This function notifies the DLL when the user has renamed the site so that it can update its persistent information
about the site.
Arguments
const char oldSiteName[64], const char newSiteName[64]
• The oldSiteName argument is a string that points to the original name of the site before it was renamed. The
name cannot exceed 64 characters.
• The newSiteName argument is a string that points to the new name of the site after it was renamed. The name
cannot exceed 64 characters.
Returns
A Boolean value:
true if successful; false otherwise.
92
int SCS_GetNumNewFeatures()
Description
This function returns the number of new features to add to Dreamweaver (for example, File History, Differences,
and so on).
Arguments
None.
Returns
An integer that indicates the number of new features to add to Dreamweaver. If the function returns
< 0, Dream-
weaver considers it an error and tries to retrieve the error message from the DLL, if supported.
bool SCS_GetNewFeatures()
Description
This function returns a list of menu items to add to the Dreamweaver main and context menus. For example, the
Sourcesafe DLL can add History and File Differences to the main menu.
Arguments
char menuItemList[][32], scFunction functionList[], scFunction enablerList[], const int
numNewFeatures
• The menuItemList argument is a string list that is populated by the DLL; it specifies the menu items to add to
the main and context menus. Each string can contain a maximum of 32 characters.
• The functionList argument is populated by the DLL; it specifies the routines in the DLL to call when the user
selects the corresponding menu item.
DREAMWEAVER CS3
API Reference
• The enablerList argument is populated by the DLL; it specifies the routines in the DLL to call when Dream-
weaver needs to determine whether the corresponding menu item is enabled.
• The numNewFeatures argument is the number of items being added by the DLL; this value is retrieved from the
GetNumNewFeatures() call.
The following function signature defines the functions and enablers that passed to the
functionlist and enablerList arguments.
in the
bool (*scFunction)(void *connectionData, const char *remotePathList[],
const char *localPathList[], const int numItems)
SCS_GetNewFeatures() call
Returns
A Boolean value:
true if successful; false otherwise.
bool SCS_GetCheckoutName()
Description
This function returns the check-out name of the current user. If it is unsupported by the source control system and
this feature is enabled by the user, this function uses the Dreamweaver internal Check In/Check Out functionality,
which transports LCK files to and from the source control system.
93
Arguments
void *connectionData, char checkOutName[64], char emailAddress[64]
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
• The checkOutName argument is the name of the current user.
• The emailAddress argument is the e-mail address of the current user.
Returns
A Boolean value:
true if successful; false otherwise.
bool SCS_Checkin()
Description
This function checks a list of local files or folders into the source control system. The DLL is responsible for making
the file read-only. If it is unsupported by the source control system and this feature is enabled by the user, this
function uses the Dreamweaver internal Check In/Check Out functionality, which transports LCK files to and from
the source control system.
Arguments
void *connectionData, const char *localPathList[], const char *remotePathList[], bool
successList[], const int numItems
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
• The localPathList argument is a list of local filenames or folder paths to check in.
• The remotePathList argument is a mirrored list of remote filenames or folder paths.
DREAMWEAVER CS3
API Reference
• The successList argument is a list of Boolean values that are populated by the DLL to let Dreamweaver know
which of the corresponding files are checked in successfully.
• The numItems argument is the number of items in each list.
Returns
A Boolean value:
true if successful; false otherwise.
bool SCS_Checkout()
Description
This function checks out a list of local files or folders from the source control system. The DLL is responsible for
granting the privileges that let the file be writable. If it is unsupported by the source control system and this feature
is enabled by the user, this function uses the Dreamweaver internal Check In/Check Out functionality, which transports LCK files to and from the source control system.
Arguments
void *connectionData, const char *remotePathList[], const char *localPathList[], bool
successList[], const int numItems
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
• The remotePathList argument is a list of remote filenames or folder paths to check out.
94
• The localPathList argument is a mirrored list of local filenames or folder paths.
• The successList argument is a list of Boolean values that are populated by the DLL to let Dreamweaver know
which of the corresponding files are checked out successfully.
• The numItems argument is the number of items in each list.
Returns
A Boolean value:
true if successful; false otherwise.
bool SCS_UndoCheckout()
Description
This function undoes the check-out status of a list of files or folders. The DLL is responsible for making the file readonly. If it is unsupported by the source control system and this feature is enabled by the user, this function uses the
Dreamweaver internal Check In/Check Out functionality, which transports LCK files to and from the source control
system.
Arguments
void *connectionData, const char *remotePathList[], const char *localPathList[], bool
successList[], const int numItems
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
• The remotePathList argument is a list of remote filenames or folder paths on which to undo the check out.
• The localPathList argument is a mirrored list of local filenames or folder paths.
DREAMWEAVER CS3
API Reference
• The successList argument is a list of Boolean values that are populated by the DLL to let Dreamweaver know
which corresponding files’ check outs are undone successfully.
• The numItems argument is the number of items in each list.
Returns
A Boolean value:
true if successful; false otherwise.
int SCS_GetNumCheckedOut()
Description
This function returns the number of users who have a file checked out.
Arguments
void *connectionData, const char *remotePath
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
• The remotePath argument is the remote file or folder path to check to see how many users have it checked out.
Returns
An integer that indicates the number of people who have the file checked out. If the function returns
weaver considers it an error and tries to retrieve the error message from the DLL, if supported.
< 0, Dream-
95
bool SCS_GetFileCheckoutList()
Description
This function returns a list of users who have a file checked out. If the list is empty, no one has the file checked out.
Arguments
void *connectionData, const char *remotePath, char checkOutList[][64], char emailAd-
dressList[][64], const int numCheckedOut
• The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the
Connect() call.
• The remotePath argument is the remote file or folder path to check how many users have it checked out.
• The checkOutList argument is a list of strings that corresponds to the users who have the file checked out. Each
user string cannot exceed a maximum length of 64 characters.
• The emailAddressList argument is a list of strings that corresponds to the users’ e-mail addresses. Each e-mail
address string cannot exceed a maximum length of 64 characters.
• The numCheckedOut argument is the number of people who have the file checked out. This is returned from
GetNumCheckedOut().
Returns
A Boolean value:
true if successful; false otherwise.
Loading...