ADOBE Dreamweaver API CS5 User Manual [es, en]

Download

ADOBE® DREAMWEAVER® CS5 & CS5.5

API Reference

Legal notices

For legal notices, see http://help.adobe.com/en_US/legalnotices/index.html.

Last updated 6/15/2011

Chapter 1: Introduction

About extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Extending Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Additional resources for extension writers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

New functions in Dreamweaver CS5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Conventions used in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Chapter 2: The file I/O API

About configuration folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

About the file I/O API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 3: The HTTP API

How the HTTP API works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

The HTTP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Chapter 4: The Design Notes API

How Design Notes work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

The Design Notes JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

The Design Notes C API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

iii

Chapter 5: Fireworks integration

The FWLaunch API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Chapter 6: Flash integration

The Flash Objects API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Flash panels and dialogs functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Chapter 7: Photoshop integration

How Smart Objects work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

The Smart Objects API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Chapter 8: The database API

How database API functions work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Database connection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Database access functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Chapter 9: The database connectivity API

Select a new connection type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Develop a new connection type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

The Connection API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

The generated include file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

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

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Contents

Chapter 10: The source control integration API

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

Adding source control system functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

The source control integration API required functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

The source control integration API optional functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Enablers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Chapter 11: Application

External application functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Global application functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Bridge communication functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Chapter 12: Workspace

History functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Insert object functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Keyboard functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Menu functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Results window functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Toggle functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Toolbar functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Window functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Information bar functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Related files functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Vertical Split view functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Code collapse functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Code view toolbar functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Color functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Chapter 13: Site

Report functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Site functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Chapter 14: Document

Conversion functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Command functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

File manipulation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Global document functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Path functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Selection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

String manipulation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

Translation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

XSLT functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Chapter 15: Page content

Assets panel functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Behavior functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Clipboard functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

Library and template functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Contents

Snippets panel functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Spry widget editing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Inserting Spry widgets functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Browser compatibility check functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

Chapter 16: Dynamic documents

Server components functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Data source functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Extension Data Manager functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

Live data functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

Live view functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

Server behavior functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

Server model functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

Chapter 17: Design

CSS layout functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

Frame and frameset functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

Layer and image map functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

Layout environment functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

Layout view functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

Resolution management functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412

Media Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414

Zoom functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415

Guide functions and properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

Table editing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

Chapter 18: Code

Code functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435

Find and replace functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

General editing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445

Print function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461

Quick Tag Editor functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462

Code view functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464

Live Code view functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481

Tag editor and tag library functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482

Chapter 19: Enablers

Enabler functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487

Last updated 6/15/2011

Chapter 1: Introduction

The Adobe Dreamweaver CS5 API Reference describes the application programming interfaces (APIs). The APIs let you perform various supporting tasks when developing Adobe® Dreamweaver® CS5 extensions and adding program code to your Dreamweaver web pages. The APIs include the main JavaScript API which provides access to most of the core functionalities of Dreamweaver. Core functionalities of Dreamweaver means generally anything that can be done with a menu, and more. It also includes various utility APIs for performing such common tasks as reading and writing files, transferring information with HTTP, and communicating with Fireworks and Flash.

The extensive JavaScript API lets you perform a diverse set of smaller tasks. A user would perform many of these tasks when creating or editing Dreamweaver documents. These API functions are grouped by the parts of the Dreamweaver user interface that they affect. For example, the JavaScript API includes Workspace functions, Document functions, Design functions, and so on. The API functions let you perform some of the following tasks and much more in addition to these tasks:

• Opening a new document

• Getting or setting a font size

• Finding the occurrence of a search string in HTML code

• Making a toolbar visible

About extensions

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 serverside scripting on at least one platform, such as Active Server Pages (ASP), ASP.NET, PHP: Hypertext Preprocessor (PHP), Adobe ColdFusion, or Java Server Pages (JSP).

Extending Dreamweaver

To learn about the Dreamweaver framework and the API that enables you to build Dreamweaver extensions, see Extending Dreamweaver. Extending Dreamweaver describes the API functions that Dreamweaver calls to implement the objects, menus, floating panels, server behaviors, and so on, that comprise the various features of Dreamweaver. You can use those APIs to add objects, menus, floating panels, or other features to the product. Extending Dreamweaver also explains how to customize Dreamweaver by editing and adding tags to various HTML and XML files to add menu items or document types, and so on.

Additional resources for extension writers

To communicate with other developers who are involved in writing extensions, join the Dreamweaver extensibility news group. You can access the website for this news group at

http://www.adobe.com/cfusion/webforums/forum/categories.cfm?forumid=12&catid=190.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Introduction

New functions in Dreamweaver CS5

The following new functions are added to the Dreamweaver CS5 JavaScript API. The headings designate the chapters and sections that contain the new functions:

Dynamic documents

The following functions are added to the Dynamic documents chapter.

Live view functions

“dom.setLiveViewFollowsLinks()” on page 358

“dom.getLiveViewFollowsLinks()” on page 358

“dom.isLiveViewBrowsingHomeURI()” on page 358

“dreamweaver.findSiteForURI()” on page 359

“dom.browser.isPageNavigationHistoryEnabled()” on page 360

“dom.browser.enablePageNavigationHistory()” on page 361

“dom.browser.getPageNavigationHistoryLength()” on page 361

“dom.browser.getPageNavigationHistoryPosition()” on page 361

“dom.browser.goToPageNavigationHistoryPosition()” on page 362

“dom.browser.getPageNavigationHistoryItem()” on page 362

“dom.browser.setHomePage()” on page 363

“dom.browser.getHomePage()” on page 363

Workspace

The following new functions are added to the Workspace chapter.

Related files functions

“dreamweaver.getRelatedFilesFilter()” on page 190

“dreamweaver.setRelatedFilesFilter()” on page 190

“dreamweaver.getQuickRelatedFilesFilterStrings()” on page 190

“dreamweaver.invokeRelatedFilesCustomFilterDialog()” on page 191

“dreamweaver.getDynamicRelatedFilesDiscoverySetting()” on page 191

“dreamweaver.setDynamicRelatedFilesDiscoverySetting()” on page 192

“dreamweaver.refreshRelatedFiles()” on page 192

“dreamweaver.saveAllRelatedFiles()” on page 192

“dreamweaver.canSaveAllRelatedFiles()” on page 193

“document.isRelatedFileViewOpen()” on page 193

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Introduction

“document.getRelatedFiles()” on page 193

“document.addRelatedFile()” on page 194

“document.removeRelatedFile()” on page 195

“document.getDependentFiles()” on page 195

...and more.

Document

The following new functions are added to the Document chapter.

“DWUri.isValidURI()” on page 275

“DWUri.isAbsolute()” on page 275

“DWUri.isRelative()” on page 275

“DWUri.isDirectory()” on page 276

“DWUri.isHierarchical()” on page 276

“DWUri.isOfType()” on page 276

“DWUri.isOfFileType()” on page 277

...and more.

Code

The following new functions are added to the Code chapter.

“dom.getLiveCodeHighlightsChanges()” on page 481

“dom.setLiveCodeHighlightsChanges()” on page 481

...and more.

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.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Introduction

• 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

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

Last updated 6/15/2011

Chapter 2: The file I/O API

Adobe® Dreamweaver® CS5 includes a C shared library called DWfile. The DWfile lets authors of objects, commands, behaviors, data translators, floating panels, and Property inspectors read and write files on the local file system. The 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.

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

About the file I/O API

All functions in the file I/O API are methods of the DWfile object.

DWfile.copy()

Availability

Dreamweaver 3.

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:

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The file I/O API

var fileURL = "file:///c|/Config/myconfig.cfg"; var newURL ="file:///c|/Config/myconfig_backup.cfg"; DWfile.copy(fileURL, newURL);

DWfile.createFolder()

Availability

Dreamweaver 2.

Description

This function creates a folder at the specified location.

Arguments

folderURL

• The folderURL argument, which is expressed as a file:// URL, is the location of the folder you want to create.

Returns

A Boolean value: true if the folder is created successfully; false otherwise.

Example

The following code tries to create a folder called tempFolder at the top level of the C drive and displays an alert box that indicates whether the operation was successful:

var folderURL = "file:///c|/tempFolder"; if (DWfile.createFolder(folderURL)){

alert("Created " + folderURL);

}else{

alert("Unable to create " + folderURL);

}

DWfile.exists()

Availability

Dreamweaver 2.

Description

This function tests for the existence of the specified file.

Arguments

fileURL

• The fileURL argument, which is expressed as a file:// URL, is the requested file.

Returns

A Boolean value: true if the file exists; false otherwise.

Example

The following code checks for the mydata.txt file and displays an alert message that tells the user whether the file exists:

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The file I/O API

var fileURL = "file:///c|/temp/mydata.txt"; if (DWfile.exists(fileURL)){

alert(fileURL + " exists!");

}else{

alert(fileURL + " does not exist.");

}

DWfile.getAttributes()

Availability

Dreamweaver 2.

Description

This function gets the attributes of the specified file or folder.

Arguments

fileURL

• The fileURL argument, which is expressed as a file:// URL, is the file or folder for which you want to get attributes.

Returns

A string that represents the attributes of the specified file or folder. If the file or folder does not exist, this function returns a

null value. The following characters in the string represent the attributes:

• R is read only.

• D is folder.

• H is hidden.

• S is system file or folder.

Example

The following code gets the attributes of the mydata.txt file and displays an alert box if the file is read only:

var fileURL = "file:///c|/temp/mydata.txt"; var str = DWfile.getAttributes(fileURL); if (str && (str.indexOf("R") != -1)){

alert(fileURL + " is read only!");

}

DWfile.getModificationDate()

Availability

Dreamweaver 2.

Description

This function gets the time when the file was last modified.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The file I/O API

Arguments

fileURL

• The fileURL argument, which is expressed as a file:// URL, is the file for which you are checking the 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.

Example

It’s useful to call the function twice and compare the return values because the value that this function returns is platform-dependent and is not a recognizable date and time. The following code example gets the modification dates of file1.txt and file2.txt and displays an alert message that indicates which file is newer:

var file1 = "file:///c|/temp/file1.txt"; var file2 = "file:///c|/temp/file2.txt"; var time1 = DWfile.getModificationDate(file1); var time2 = DWfile.getModificationDate(file2); if (time1 == time2){

alert("file1 and file2 were saved at the same time");

}else if (time1 < time2){

alert("file1 older that file2");

}else{

alert("file1 is newer than file2");

}

DWfile.getCreationDate()

Availability

Dreamweaver 4.

Description

This function gets the time when the file was created.

Arguments

fileURL

• The fileURL argument, which is expressed as a file:// URL, is the file for which you are checking the creation time.

Returns

Example

You can call this function and the DWfile.getModificationDate() function on a file to compare the modification date to the creation date:

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The file I/O API

var file1 = "file:///c|/temp/file1.txt"; var time1 = DWfile.getCreationDate(file1); var time2 = DWfile.getModificationDate(file1); if (time1 == time2){

alert("file1 has not been modified since it was created");

}else if (time1 < time2){

alert("file1 was last modified on " + time2);

}

DWfile.getCreationDateObj()

Availability

Dreamweaver MX.

Description

This function gets the JavaScript object that represents the time when the file was created.

Arguments

fileURL

• The fileURL argument, which is expressed as a file:// URL, is the file for which you are checking the creation time.

Returns

A JavaScript Date object that represents the date and time when the specified file was created.

DWfile.getModificationDateObj()

Availability

Dreamweaver MX.

Description

This function gets the JavaScript Date object that represents the time when the file was last modified.

Arguments

fileURL

• The fileURL argument, which is expressed as a file:// URL, is the file for which you are checking the time of the most

recent modification.

Returns

A JavaScript Date object that represents the date and time when the specified file was last modified.

DWfile.getSize()

Availability

Dreamweaver MX.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The file I/O API

Description

This function gets the size of a specified file.

Arguments

fileURL

• The fileURL argument, which is expressed as a file:// URL, is the file for which you are checking the size.

Returns

An integer that represents the actual size, in bytes, of the specified file.

DWfile.listFolder()

Availability

Dreamweaver 2.

Description

This function gets a list of the contents of the specified folder.

Arguments

folderURL, {constraint}

• The folderURL argument is the folder for which you want a contents list, which is expressed as a file:// URL, plus

an optional wildcard file mask. Valid wildcards are asterisks (*), which match one or more characters, and question marks (?), which match a single character.

• The constraint argument, if it is supplied, must be either "files" (return only files) or "directories" (return

only folders). If it is omitted, the function returns files and folders.

Returns

An array of strings that represents the contents of the folder.

Example

The following code gets a list of all the text (TXT) files in the C:/temp folder and displays the list in an alert message:

var folderURL = "file:///c|/temp"; var fileMask = "*.txt"; var list = DWfile.listFolder(folderURL + "/" + fileMask, "files"); if (list){

alert(folderURL + " contains: " + list.join("\n"));

}

DWfile.read()

Availability

Dreamweaver 2.

Description

This function reads the contents of the specified file into a string.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The file I/O API

Arguments

fileURL

• The fileURL argument, which is expressed as a file:// URL, is the file you want to read.

Returns

A string that contains the contents of the file or a null value if the read fails.

Example

The following code reads the mydata.txt file and, if it is successful, displays an alert message with the contents of the file:

var fileURL = "file:///c|/temp/mydata.txt"; var str = DWfile.read(fileURL); if (str){

alert(fileURL + " contains: " + str);

}

DWfile.remove()

Availability

Dreamweaver 3.

Description

This function deletes the specified file.

Arguments

fileURL

• The fileURL argument, which is expressed as a file:// URL, is the file you want to remove.

Returns

A Boolean value: true value if the operation succeeds; false otherwise.

Example

The following example uses the DWfile.getAttributes() function to determine whether the file is read-only and

confirm() function to display a Yes/No dialog box to the user:

the

function deleteFile(){

var delAnyway = false; var selIndex = document.theForm.menu.selectedIndex;

var selFile = document.theForm.menu.options[selIndex].value;

if (DWfile.getAttributes(selFile).indexOf('R') != -1){

delAnyway = confirm('This file is read-only. Delete anyway?'); if (delAnyway){

DWfile.remove(selFile);

}

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The file I/O API

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.

• 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

Read only

Writable (overrides R)

Hidden

Visible (overrides H)

Acceptable values for the strAttrs string are R, W, H, V, RH, RV, WH, or WV.

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,

H becomes meaningless, and the file is set as visible (V).

W). You should not use H and V together because they are also mutually

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

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.

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.

Note: If the path contains spaces, this function will not write files.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The file I/O API

• The text argument indicates the string the function has to write.

• The mode argument, if it is supplied, must be append. If this argument is omitted, the string overwrites the contents

of the file.

Returns

A Boolean value: true if the string is successfully written to the file; false otherwise.

Example

The following code attempts to write the string xxx to the mydata.txt file and displays an alert message if the write operation succeeds. It then tries to append the string 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); }

aaa to the file and displays a second alert if the write operation

xxxaaa and nothing else.

Last updated 6/15/2011

Chapter 3: The HTTP API

Extensions are not limited to working in the local file system. Adobe® Dreamweaver® provides a mechanism to get information from and send information to a web server by using hypertext transfer protocol (HTTP). The chapter describes the HTTP API and how to use it.

How the HTTP API works

All functions in the HTTP API are methods of the MMHttp object. Most of these functions take a URL as an argument, and most return an object. The default port for URL arguments is 80. To specify a port other than 80, append a colon and the port number to the URL, as shown in the following example:

MMHttp.getText("http://www.myserver.com:8025");

For functions that return an object, the object has two properties: statusCode and data.

The statusCode property indicates the status of the operation; possible values include, but are not limited to, the following values:

• 200: Status OK

• 400: Unintelligible request

• 404: Requested URL not found

• 405: Server does not support requested method

• 500: Unknown server error

• 503: Server capacity reached

For a comprehensive list of status codes for your server, check with your Internet service provider or system administrator.

The value of the data property varies according to the function; possible values are specified in the individual function listings.

Functions that return an object also have a callback version. Callback functions let other functions execute while the web server processes an HTTP request. This capability is useful if you are making multiple HTTP requests from Dreamweaver. The callback version of a function passes its ID and return value directly to the function that is specified as its first argument.

The HTTP API

This section details the functions that are methods of the MMHttp object.

MMHttp.clearServerScriptsFolder()

Availability

Dreamweaver MX.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The HTTP API

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/server-model/_mmDBScripts folder.

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 data property of this object is a string that contains the contents of the deleted scripts. If an error occurs, Dreamweaver reports it in the

statusCode property of the returned

object.

Example

The following code, in a menu command file inside the Configuration/Menus folder, removes all the files from the _mmServerScripts folder when it is called from a menu:

<html> <head> <TITLE>Clear Server Scripts</TITLE> <SCRIPT SRC="ClearServerScripts.js"></SCRIPT> <SCRIPT LANGUAGE="javascript"> </SCRIPT> <body onLoad="MMHttp.clearServerScriptsFolder()"> </body> </html>

MMHttp.clearTemp()

Description

This function deletes all the files in the Configuration/Temp folder, which is located in the Dreamweaver application folder.

Arguments

None.

Returns

Nothing.

Example

The following code, when saved in a file within the Configuration/Shutdown folder, removes all the files from the Configuration/Temp folder when the user quits Dreamweaver:

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The HTTP API

<html> <head> <title>Clean Up Temp Files on Shutdown</title> </head> <body onLoad="MMHttp.clearTemp()"> </body> </html>

MMHttp.getFile()

Description

This function gets the file at the specified URL and saves it in the Configuration/Temp folder, which is located in the Dreamweaver application folder. Dreamweaver automatically creates subfolders that mimic the folder structure of the server; for example, if the specified file is at www.dreamcentral.com/people/index.html, Dreamweaver stores the index.html file in the People folder inside the www.dreamcentral.com folder.

Arguments

URL, {prompt}, {saveURL}, {titleBarLabel}

• The URL argument is an absolute URL on a web server; if http:// is omitted from the URL, Dreamweaver assumes

HTTP protocol.

• The prompt argument, which is optional, is a Boolean value that specifies whether to prompt the user to save the

file. If saveURL is outside the Configuration/Temp folder, a prompt value of

• The saveURL argument, which is optional, is the location on the user’s hard disk where the file should be saved,

which is expressed as a file:// URL. If prompt is a

true value or saveURL is outside the Configuration/Temp folder,

the user can override saveURL in the Save dialog box.

• The titleBarLabel argument, which is optional, is the label that should appear in the title bar of the Save dialog box.

false is ignored for security reasons.

Returns

An object that represents the reply from the server. The data property of this object is a string that contains the location where the file is saved, which is expressed as a file:// URL. Normally, the

statusCode property of the object

contains the status code that is received from the server. However, if a disk error occurs while Dreamweaver is saving the file on the local drive, the

statusCode property contains an integer that represents one of the following error codes

if the operation is not successful:

• 1: Unspecified error

• 2: File not found

• 3: Invalid path

• 4: Number of open files limit reached

• 5: Access denied

• 6: Invalid file handle

• 7: Cannot remove current working folder

• 8: No more folder entries

• 9: Error setting file pointer

• 10: Hardware error

• 11: Sharing violation

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The HTTP API

• 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}

• The callbackFunction argument is the name of the JavaScript function to call when the HTTP request is complete.

• The URL argument is an absolute URL on a web server; if http:// is omitted from the URL, Dreamweaver assumes

HTTP protocol.

• The prompt argument, which is optional, is a Boolean value that specifies whether to prompt the user to save the

file. If saveURL argument specifies a location outside the Configuration/Temp folder, a prompt value of

false is

ignored for security reasons.

• The saveURL argument, which is optional, is the location on the user’s hard disk where the file should be saved,

which is expressed as a file:// URL. If prompt is a

true value or saveURL is outside the Configuration/Temp folder,

the user can override saveURL in the Save dialog box.

• The titleBarLabel argument, which is optional, is the label that should appear in the title bar of the Save dialog box.

Returns

An object that represents the reply from the server. The data property of this object is a string that contains the location where the file was saved, which is expressed as a file:// URL. Normally the

statusCode property of the object

contains the status code that is received from the server. However, if a disk error occurs while Dreamweaver is saving the file on the local drive, the

statusCode property contains an integer that represents an error code. See

“MMHttp.getFile()” on page 16 for a list of possible error codes.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The HTTP API

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 Configuration

folder on the application server—from which you want to retrieve server scripts. To retrieve the scripts, Dreamweaver uses the appropriate transfer protocol (such as FTP, WebDAV, or Remote File System). Dreamweaver copies these files to the _mmServerScripts subfolder under the root folder for the current site.

If an error occurs, Dreamweaver reports it in the statusCode property of the returned object.

MMHttp.getTextCallback()

Availability

Dreamweaver UltraDev 4, enhanced in Dreamweaver MX.

Description

Retrieves the contents of the document at the specified URL and passes it to the specified function.

Arguments

callbackFunc, URL, {serverScriptsFolder}

• The callbackFunc argument is the JavaScript function to call when the HTTP request is complete.

• The URL argument is an absolute URL on a web server; if http:// is omitted from the URL, Dreamweaver assumes

HTTP protocol.

• The serverScriptsFolder argument is an optional string that names a particular folder—relative to the Configuration

folder on the application server—from which you want to retrieve server scripts. To retrieve the scripts, Dreamweaver uses the appropriate transfer protocol (such as FTP, WebDAV, or Remote File System). Dreamweaver retrieves these files and passes them to the function that callbackFunc identifies.

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.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The HTTP API

Description

Performs an HTTP post of the specified data to the specified URL. Typically, the data associated with a post operation is form-encoded text, but it could be any type of data that the server expects to receive.

Arguments

URL, dataToPost, {contentType}, {serverScriptsFolder}

• The URL argument is an absolute URL on a web server; if http:// is omitted from the URL, Dreamweaver assumes

HTTP protocol.

• The dataToPost argument is the data to post. If the third argument is "application/x-www-form-urlencoded"

or omitted, dataToPost must be form-encoded according to section 8.2.1 of the RFC 1866 specification (available

www.faqs.org/rfcs/rfc1866.html).

• The contentType argument, which is optional, is the content type of the data to post. If omitted, this argument

defaults to

"application/x-www-form-urlencoded".

• The serverScriptsFolder argument is an optional string that names a particular folder—relative to the Configuration

folder on the application server—to which you want to post the data. To post the data, Dreamweaver uses the appropriate transfer protocol (such as FTP, WebDAV, or Remote File System).

If an error occurs, Dreamweaver reports it in the 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:

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.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The HTTP API

Arguments

callbackFunc, URL, dataToPost, {contentType}, {serverScriptsFolder}

• The callbackFunc argument is the name of the JavaScript function to call when the HTTP request is complete.

• The URL argument is an absolute URL on a web server; if http:// is omitted from the URL, Dreamweaver assumes

HTTP protocol.

• The dataToPost argument is the data to be posted. If the third argument is "application/x-www-form-

urlencoded" or omitted, data must be form-encoded according to section 8.2.1 of the RFC 1866 specification

(available at

www.faqs.org/rfcs/rfc1866.html).

• The contentType argument, which is optional, is the content type of the data to be posted. If omitted, this argument

defaults to

"application/x-www-form-urlencoded".

• The serverScriptsFolder argument is an optional string. It names a particular folder, relative to the Configuration

folder on the application server—to which you want to post the data. To post the data, Dreamweaver uses the appropriate transfer protocol (such as FTP, WebDAV, or Remote File System). Dreamweaver retrieves these data and passes them to the function identified by callbackFunc.

If an error occurs, Dreamweaver reports it in the statusCode property of the returned object.

Last updated 6/15/2011

Chapter 4: The Design Notes API

Adobe® Dreamweaver®, Adobe® Fireworks®, and Adobe® Flash® give web designers and developers a way to store and retrieve extra information about documents. The information is stored in files that are called Design Notes. It gives extra information about documents like review comments, change notes, or the source file for a GIF or JPEG.

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:

<?xml version="1.0" encoding="iso-8859-1" ?> <info>

<infoitem key="FW_source" value="file:///C|sites/dreamcentral/images/sourceFiles/¬

foghorn.png" /> <infoitem key="Author" value="Heidi B." /> <infoitem key="Status" value="Final draft, approved by Jay L." />

</info>

The Design Notes JavaScript API

All functions in the Design Notes JavaScript API are methods of the MMNotes object. MMNotes 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. The functions are called from objects, commands, behaviors, floating panels, Property inspectors, and data translators in the library. The MMNotes shared library can be used independently, even if Dreamweaver is not installed.

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 deletes the folder also.

Note: Always call the MMNotes.close() function when you finish with Design Notes so Dreamweaver writes to the file.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The Design Notes API

Arguments

fileHandle

• The fileHandle argument is the file handle that the MMNotes.open() function returns.

Returns

Nothing.

Example

See “MMNotes.set()” on page 26.

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 MMNotes.filePathToLocalURL('C:\sites\webdev\index.htm') returns

"file:///c|/sites/webdev/index.htm".

MMNotes.get()

Description

This function gets the value of the specified key in the specified Design Notes file.

Arguments

fileHandle, keyName

• The fileHandle argument is the file handle that MMNotes.open() returns.

• The keyName argument is a string that contains the name of the key.

Returns

A string that contains the value of the key.

Example

See “MMNotes.getKeys()” on page 23.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The Design Notes API

MMNotes.getKeyCount()

Description

This function gets the number of key/value pairs in the specified Design Notes file.

Arguments

fileHandle

• The fileHandle argument is the file handle that the MMNotes.open() function returns.

Returns

An integer that represents the number of key/value pairs in the Design Notes file.

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.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The Design Notes API

Arguments

fileURL

• The fileURL argument, which is expressed as a file:// URL, is the path to a local file.

Returns

A string that contains the path of the Local Root folder for the site, which is expressed as a file:// URL, or an empty string if Dreamweaver is not installed or the Design Notes file is outside any site that is defined with Dreamweaver. This function searches for all the sites that are defined in Dreamweaver.

MMNotes.getVersionName()

Description

This function gets the version name of the MMNotes shared library, which indicates the application that implemented it.

Arguments

None.

Returns

A string that contains the name of the application that implemented the MMNotes shared library.

Example

Calling the MMNotes.getVersionName() function from a Dreamweaver command, object, behavior, Property inspector, floating panel, or data translator returns function from Fireworks also returns was created by the Dreamweaver engineering team.

"Dreamweaver" because Fireworks uses the same version of the library, which

"Dreamweaver". Calling the MMNotes.getVersionName()

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.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The Design Notes API

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 MMNotes.localURLToFilePath('file:///MacintoshHD/images/moon.gif') returns

"MacintoshHD:images:moon.gif".

MMNotes.open()

Description

This function opens the Design Notes file that is associated with the specified file or creates one if none exists.

Arguments

filePath, {bForceCreate}

• The filePath argument, which is expressed as a file:// URL, is the path to the main file with which the Design Notes

file is associated.

• The bForceCreate argument is a Boolean value that indicates whether to create the note even if Design Notes is

turned off for the site or if the 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 26.

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.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The Design Notes API

MMNotes.set()

Description

This function creates or updates one key/value pair in a Design Notes file.

Arguments

fileHandle, keyName, valueString

• The fileHandle argument is the file handle that the MMNotes.open() function returns.

• The keyName argument is a string that contains the name of the key.

• The valueString argument is a string that contains the value.

Returns

A Boolean value: true indicates the operation is successful; false otherwise.

Example

The following example opens the Design Notes file that is associated with a file in the dreamcentral site called peakhike99/index.html, adds a new key/value pair, changes the value of an existing key, and then closes the Design Notes file:

var noteHandle = MMNotes.open('file:///c|/sites/dreamcentral/peakhike99/

index.html',true);

if(noteHandle > 0){

MMNotes.set(noteHandle,"Author","M. G. Miller"); MMNotes.set(noteHandle,"Last Changed","August 28, 1999"); MMNotes.close(noteHandle);

}

The Design Notes C API

In addition to the JavaScript API, the MMNotes shared library also exposes a C API that lets other applications create Design Notes files. It is not necessary to call these C functions directly if you use the MMNotes shared library in Dreamweaver because the JavaScript versions of the functions call them.

This section contains descriptions of the functions, their arguments, and their return values. You can find definitions for the functions and data types in the MMInfo.h file in the Extending/c_files folder inside the Dreamweaver application folder.

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.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The Design Notes API

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.

Arguments

const char* drivePath, char* localURLBuf, int localURLMaxLen

• The drivePath argument is a string that contains the full drive path.

• The localURLBuf argument is the buffer where the file:// URL is stored.

• The localURLMaxLen argument is the maximum size of localURLBuf.

Returns

A Boolean value: true indicates the operation is successful; false otherwise. The localURLBuf argument receives the file:// URL value.

BOOL GetNote()

Description

This function gets the value of the specified key in the specified Design Notes file.

Arguments

FileHandle noteHandle, const char keyName[64], char* valueBuf, int valueBufLength

• The noteHandle argument is the file handle that the OpenNotesFile() function returns.

• The keyName[64] argument is a string that contains the name of the key.

• The valueBuf argument is the buffer where the value is stored.

• The valueBufLength argument is the integer that GetNoteLength(noteHandle, keyName) returns, which

indicates the maximum length of the value buffer.

Returns

A Boolean value: true indicates the operation is successful; false otherwise. The valueBuf argument receives the value of the key.

Example

The following code gets the value of the comments key in the Design Notes file that is associated with the welcome.html file:

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The Design Notes API

FileHandle noteHandle = OpenNotesFile("file:///c|/sites/avocado8/iwjs/welcome.html"); if(noteHandle > 0){

int valueLength = GetNoteLength( noteHandle, "comments"); char* valueBuffer = new char[valueLength + 1]; GetNote(noteHandle, "comments", valueBuffer, valueLength + 1); printf("Comments: %s",valueBuffer); CloseNotesFile(noteHandle);

}

int GetNoteLength()

Description

This function gets the length of the value that is associated with the specified key.

Arguments

FileHandle noteHandle, const char keyName[64]

• The noteHandle argument is the file handle that the OpenNotesFile() function returns.

• The keyName[64] argument is a string that contains the name of the key.

Returns

An integer that represents the length of the value.

Example

See “BOOL GetNote()” on page 27.

int GetNotesKeyCount()

Description

This function gets the number of key/value pairs in the specified Design Notes file.

Arguments

FileHandle noteHandle

• The noteHandle argument is the file handle that the OpenNotesFile() function returns.

Returns

An integer that represents the number of key/value pairs in the Design Notes file.

BOOL GetNotesKeys()

Description

This function gets a list of all the keys in a Design Notes file.

Arguments

FileHandle noteHandle, char* keyBufArray[64], int keyArrayMaxLen

• The noteHandle argument is the file handle that OpenNotesFile() returns.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The Design Notes API

• 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);

BOOL GetSiteRootForFile()

Description

This function determines the site root for the specified Design Notes file.

Arguments

const char*filePath, char*siteRootBuf, intsiteRootBufMaxLen, {InfoPrefs* infoPrefs}

• The filePath argument is the file://URL of the file for which you want the site root.

• The siteRootBuf argument is the buffer where the site root is stored.

• The siteRootBufMaxLen argument is the maximum size of the buffer that siteRootBuf references.

• The infoPrefs argument, which is optional, is a reference to a struct in which the preferences for the site are stored.

Returns

A Boolean value: true indicates the operation is successful; false otherwise. The siteRootBuf argument receives the address of the buffer that stores the site root. If you specify the infoPrefs argument, the function also returns the Design Notes preferences for the site. The both of type

BOOL.

InfoPrefs struct has two variables: bUseDesignNotes and bUploadDesignNotes,

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The Design Notes API

BOOL GetVersionName()

Description

This function gets the version name of the MMNotes shared library, which indicates the application that implemented it.

Arguments

char* versionNameBuf, intversionNameBufMaxLen

• The versionNameBuf argument is the buffer where the version name is stored.

• The versionNameBufMaxLen argument is the maximum size of the buffer that the versionNameBuf argument

references.

Returns

A Boolean value: true indicates the operation is successful; false otherwise. Dreamweaver stores "Dreamweaver" in versionNameBuf argument.

BOOL GetVersionNum()

Description

This function gets the version number of the MMNotes shared library, which lets you determine whether certain functions are available.

Arguments

char* versionNumBuf, intversionNumBufMaxLen

• The versionNumBuf argument is the buffer where the version number is stored.

• The versionNumBufMaxLen argument is the maximum size of the buffer that versionNumBuf references.

Returns

A Boolean value: true indicates the operation is successful; false otherwise. The versionNumBuf argument stores the version number.

BOOL LocalURLToFilePath()

Description

This function converts the specified file:// URL to a local drive path.

Arguments

const char* localURL, char* drivePathBuf, int drivePathMaxLen

• The localURL argument, which is expressed as a file:// URL, is the path to a local file.

• The drivePathBuf argument is the buffer where the local drive path is stored.

• The drivePathMaxLen argument is the maximum size of the buffer that the drivePathBuf argument references.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The Design Notes API

Returns

A Boolean value: true indicates the operation is successful; false otherwise. The drivePathBuf argument receives the local drive path.

FileHandle OpenNotesFile()

Description

This function opens the Design Notes file that is associated with the specified file or creates one if none exists.

Arguments

const char* localFileURL, {BOOL bForceCreate}

• The localFileURL argument, which is expressed as a file:// URL, is a string that contains the path to the main file

with which the Design Notes file is associated.

• The bForceCreate argument is a Boolean value that indicates whether to create the Design Notes file even if Design

Notes is turned off for the site or if the path specified by the localFileURL argument is not associated with any site.

FileHandle OpenNotesFilewithOpenFlags()

Description

This function opens the Design Notes file that is associated with the specified file or creates one if none exists. You can open the file in read-only mode.

Arguments

const char* localFileURL, {BOOL bForceCreate}, {BOOL bReadOnly}

• The localFileURL argument, which is expressed as a file:// URL, is a string that contains the path to the main file

with which the Design Notes file is associated.

• The bForceCreate argument is a Boolean value that indicates whether to create the Design Notes file even if Design

Notes are turned off for the site or the path is not associated with any site. The default value is is optional, but you need to specify it if you specify the third argument.

false. This 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 MMNotes.dll file.

false. You can specify the bReadOnly argument starting in version 2 of the

BOOL RemoveNote()

Description

This function removes the specified key (and its value) from the specified Design Notes file.

Arguments

FileHandlenoteHandle, 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.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The Design Notes API

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.

Last updated 6/15/2011

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 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® CS5, and for details on C-level extensibility see Extending Dreamweaver.

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.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Fireworks integration

FWLaunch.execJsInFireworks()

Availability

Dreamweaver 3, Fireworks 3.

Description

This function passes the specified JavaScript, or a reference to a JavaScript file, to Fireworks to execute.

Arguments

javascriptOrFileURL

• The javascriptOrFileURL argument, which is expressed as a file:// URL, is either a string of literal JavaScript or

the path to a JavaScript file.

Returns

A cookie object if the JavaScript passes successfully or a nonzero error code that indicates one of the following errors occurred:

• Invalid usage, which indicates that the javascriptOrFileURL argument is specified as a null value or as an empty

string, or the path to the JS or JSF file is invalid.

• File I/O error, which indicates that Fireworks cannot create a Response file because the disk is full.

• Error notifying Dreamweaver that the user is not running a valid version of Dreamweaver (version 3 or later).

• Error starting Fireworks process, which indicates that the function does not open a valid version of Fireworks

(version 3 or later).

• User cancelled the operation.

FWLaunch.getJsResponse()

Availability

Dreamweaver 3, Fireworks 3.

Description

This function determines whether Fireworks is still executing the JavaScript passed to it by the

FWLaunch.execJsInFireworks() function, whether the script completed successfully, or whether an error occurred.

Arguments

progressTrackerCookie

• The progressTrackerCookie argument is the cookie object that the FWLaunch.execJsInFireworks() function

returns.

Returns

A string that contains the result of the script passed to the FWLaunch.execJsInFireworks() function if the operation completes successfully, a that one of the following errors occurred:

• Invalid usage, which indicates that a JavaScript error occurred while Fireworks executed the script.

null value if Fireworks is still executing the JavaScript, or a nonzero error code that indicates

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Fireworks integration

• 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 "prompt('Please enter your name:')" to

FWLaunch.execJsInFireworks() and checks for the result:

var progressCookie = FWLaunch.execJsInFireworks("prompt('Please enter your name:')"); var doneFlag = false; while (!doneFlag){

// check for completion every 1/2 second setTimeout('checkForCompletion()',500);

} function checkForCompletion(){

if (progressCookie != null) {

var response = FWLaunch.getJsResponse(progressCookie);

if (response != null) {

if (typeof(response) == "number") {

// error or user-cancel, time to close the window // and let the user know we got an error window.close(); alert("An error occurred.");

}else{

// got a valid response! alert("Nice to meet you, " + response); window.close();

}

doneFlag = true;

} }

}

FWLaunch.mayLaunchFireworks()

Availability

Dreamweaver 2, Fireworks 2.

Description

This function determines whether it is possible to open a Fireworks optimization session.

Arguments

None.

Returns

A Boolean value that indicates whether the platform is Windows or Macintosh; if it is Macintosh, the value indicates if another Fireworks optimization session is already running.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Fireworks integration

FWLaunch.optimizeInFireworks()

Availability

Dreamweaver 2, Fireworks 2.

Description

This function opens a Fireworks optimization session for the specified image.

Arguments

docURL, imageURL, {targetWidth}, {targetHeight}

• The docURL argument is the path to the active document, which is expressed as a file:// URL.

• The imageURL argument is the path to the selected image. If the path is relative, it is relative to the path that you

specify in the 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 that 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.

Arguments

{versionNumber}

• The versionNumber argument is an optional floating-point number that is greater than or equal to 2; it represents

the required version of Fireworks. If this argument is omitted, the default is 2.

Returns

A Boolean value that indicates whether the specified version of Fireworks was found.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Fireworks integration

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 || ¬ 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(); }

}

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Fireworks integration

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 + "!");

} }

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

Last updated 6/15/2011

Chapter 6: Flash integration

Adobe® Dreamweaver® provides support for the Flash Object API, which leverages the Flash Generator Template file to create new Flash objects. The Flash Objects API topic provides details for the creation of Flash objects (SWF files) from Flash Generator templates (SWT files).

For information about adding Flash content to Dreamweaver objects or commands, see Extending Dreamweaver.

The Flash Objects API

The Flash Objects API lets extension developers build objects that create simple SWF files through Flash Generator. This API provides a way to set parameters in a Flash Generator template and output as a SWF file, or image file. The API lets you create new Flash objects as well as read and manipulate existing Flash objects.

The SWT file is a Flash Generator Template file, which contains all the information necessary for you to construct a Flash Object file. These API functions let you create a SWF file (or image file) from an SWT file. The SWF file is created by replacing the parameters of the SWT file with real values. For more information on Flash, see the Flash documentation. The following functions are methods of the

SWFFile object.

SWFFile.createFile()

Description

This function generates a new Flash Object file with the specified template and array of parameters. It also creates a GIF, PNG, JPEG, and MOV versions 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 object type, such as

• The swfFileName argument, which is expressed as a file:// URL, is the output filename of an SWF file or an empty

string to ignore.

• The gifFileName argument, which is expressed as a file:// URL, is the output filename of a GIF file. This argument

is optional.

• The pngFileName argument, which is expressed as a file:// URL, is the output filename of a PNG file. This argument

is optional.

"Flash Text".

"dwType". Its value should be a string that represents the name of the

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Flash integration

• 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 arguments’ name/value pairs is invalid.

• "initGeneratorFailed" means the Generator cannot be initialized.

• "outOfMemory" means there is insufficient memory to complete the operation.

• "unknownError" means an unknown error occurred.

Example

The following JavaScript creates a Flash object file of type "myType", which replaces any occurrences of the string

"text" inside the Template file with the string, "Hello World". It creates a GIF file as well as a SWF file.

var params = new Array; params[0] = "dwType"; params[1] = "myType"; params[2] = "text"; params[3] = "Hello World"; errorString = SWFFile.createFile( "file:///MyMac/test.swt", ¬ params, "file:///MyMac/test.swf", "file:///MyMac/test.gif");

SWFFile.getNaturalSize()

Description

This function returns the natural size of any uncompressed Flash content.

Arguments

fileName

• The fileName argument, which is expressed as a file:// URL, is a path to the Flash content.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Flash integration

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 dwType parameter when 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 myType:

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 it is not a Flash Object file.

Example

Calling var params = SWFFile.readFile("file:///MyMac/test.swf") returns the following values in the parameters array:

"dwType", followed by its value. The function returns a null value if the file cannot be found or if

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Flash integration

"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

Flash panels and dialogs functions

The following APIs enable you to add SWF files in panels and dialogs.

dreamweaver.flash.newControl()

Availability

Dreamweaver CS4.

Description

This function enables you to create a Flash control. It is referred to later through the controlID parameter. The control displays the Flash file (.swf) specified by the SWF path. The control is positioned and has the size specified in

defaultGeometry parameter.

the

Note: Dreamweaver displays the Flash controls when you call flash.requestStateChange. Dreamweaver displays the Dialog controls when you call

newControl; you need not call flash.requestStateChange.

Arguments

controlID, controlType, controlData

• The controlID argument is a string value.

• The controlType argument specifies whether the panel is a standard extension ("standard"), a trusted standard

extension ("trusted"), or a plus extension (any other value). If it is a plus extension, the value is an identifier known specially to the host application that indicates the type of custom integration required. If the application does not understand the custom integration type, it returns an error.

• The controlData is an object. Some of the following are the key properties of this argument:

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Flash integration

Property Description Values

controlData.swfUTF8Path Location of the SWF. This property is required

{controlData.scriptPath} Path to .js file that contains the functions to

controlData.defaultGeometry The defaultGeometry values are represented

and it is passed in as a string of Unicode characters, since all characters in JavaScript are in unicode.

execute from .swf using External Interface call. This property is optional. If you want to call back into JavaScript code of Dreamweaver from the .swf file using an External Interface. You can provide a .js file containing functions that you can then call from the .swf file. For more information, see the

dw.flash.executeScript call.

as screen coordinates from the upper left of the screen. This property is required.

Object /*!< default creation geometry, including positioning */ { topleftx: Number, toplefty: Number, width: Number, height: Number }

The following table lists the PanelWindow specifications:

Options Type Descriptions

The possible values for

controlData.windowType

• PanelWindow.The table following

this table lists the specifications for this value.

• ModalDialogWindow

name String The name of the panel that appears on the tab. If you don't specify it, it is

{controlData.minSize} Object minSize only applies to controls of type PanelWindow. This option

{controlData.maxSize} Object maxSize applies to controls of type PanelWindow only. This option is

{iconPathNormal} String Path to icon that must be used in the floating panel when the panel is

{iconPathRollOver} String Path to icon that must be used in the floating panel when the panel is

{iconPathDisable} String Path to icon that must be used in the floating panel when the panel is

named "UNDEFINED". All panel names appear in uppercase. You cannot change it to lowercase.

controls the minimum size that the panel can be resized to. This option is optional. If specified in

{ width: Number, height: Number }

optional. This option controls the maximum size that the panel can be resized to. If maxSize is not specified, it defaults to the width and height specified in

{ width: Number, height: Number }

collapsed in icon mode. This option is optional.

collapsed in icon mode and the user rolls over it. This option is optional.

collapsed in icon mode and it is disabled. This option is optional.

minSize is not specified, it defaults to the width and height

defaultGeometry and the panel cannot be resized.

defaultGeometry and the panel cannot be resized..

Returns

One of the following success or error codes:

• The code PlugPlugErrorCode_success indicates that creating the control succeeded.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Flash integration

• The code PlugPlugErrorCode_extensionRegistrationFailed indicates that you were unable to register the

control.

dreamweaver.flash.requestStateChange()

Availability

Dreamweaver CS4.

Description

This function changes the state of the floating panel identified by uniqueID for the extension with extensionID.

Arguments

controlID, stateChange, stateData

• The controlID argument is a string value.

• The stateChange argument is a string with the following possible values:

Value Description

Move Change of origin but not the size

Resize New size and possibly a new origin

Show Visibility only, but no geometric changes

Hide Visibility only, but no geometric changes

Minimize Like hide, but explains why it is hidden

Restore Like show, but explains why it is displayed

Open The window is created and its extension is loaded

Close The contained extension is unloaded

• The values of the stateData argument are strings as shown in the following table:

Value of stateChange Value of stateData

Move

Resize

eventData = { topleftx: Number, toplefty: Number }

eventData = { width: Number, height: Number }

Returns

The following table contains the return values, which are strings:

Value Description

RequestPosted An event or command to execute the request has been queued in the host application.

RequestComplete The host application has successfully completed the request.

RequestFailed The host application attempted to complete the request, but failed.

RequestDenied The host application refused the request, typically because it doesn't support the action requested.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Flash integration

Example

controlData = {}; controlData.defaultGeometry = {topleftx : 100, toplefty : 100, width : 200, height : 200 }; controlData.minSize = {width : 100; height : 100 }; controlData.maxSize = {width : 300; height : 300 }; var swfPath = dw.getConfigurationPath(); swfPath += '/flash/PhotoAlbum.swf'; controlData.swfUTF8Path = swfPath; // open the window flash.requestStateChange("com.adobe.extension.foo","Open",controlData.defaultGeometry);

dreamweaver.flash.controlEvent()

Availability

Dreamweaver CS4.

Description

This function is used to pass events to a flash control. Event calls are passed as an XML string that captures the function and the relevant parameters. The XML string captures the function in the SWF files that must be started.

Arguments

inControlID, inXMLString

• The inControlID argument is a string.

• The inXMLString argument is a string. Pass the following inXMLString to call the function in the flashCallback

flash file and pass a single string, 'Hello' as an argument.

<string>Hello</string>

</arguments>

</invoke>

Returns

Returns an XML string.

Example

The following example calls the flashCallback function from JavaScript. In this example, you pass the callback function name and its arguments as an XML string.

var xmlString = '<invoke name="flashCallback" returntype="xml"> <arguments> <string>Hello</string> </arguments> </invoke>';

In this example, you use dw.flash.controlEvent to call back into the flash file (.swf):

dw.flash.controlEvent('Flickr', xmlString);

The following arguments are used in this function:

• Flickr, which is the ID of the extension that is passed in when the .swf control was created with

dw.flash.newControl.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Flash integration

• The XML string containing call back function and arguments.

The following example is the implementation of the flashcallback function implemented in flashcallback.mxml. In the following example, add the

public function initApp():void { ExternalInterface.addCallback("flashCallback",flashCallback); }

flashcallback function. This function must be called from external applications.

This function is called back from outside the flash file(.swf).

Note: Ensure that you call the ExternalInterface.addCallback ("flashCallback",flashCallback) before trying to call this function.

public function flashCallback(inputStr:String):String {

out.text += inputStr + " got flashCallback!\n"; return "it worked!";

}

dreamweaver.flash.setMenu()

Availability

Dreamweaver CS4.

Description

This function enables you to provide Fly Out commands for extensions of type "PanelWindow".

Arguments

inControlID, inMenuPosition, inMenu

• The inControlID is an extension ID. Calling the function affects the Fly Out menu of an open panel housing the

extension. If this argument is undefined, the call affects the main menus of the application.

• The inMenuPosition is a string describing where the given commands must be placed.

• If this string is undefined, an entire menu is replaced.

• If this string is for a panel, the entire user-settable area of the Fly Out menu is replaced. (The application reserves

some fixed flyout items.)

• If this string is for the application, the entire default Controls submenu of the Windows menu is replaced.

• If this string is an XML string in a to-be-determined schema for setting sections of menus, this form is provided

for future compatibility.

• inMenu is equivalent to MenuItem . This argument indicates a list of commands, which are added at the indicated

menu position. It replaces any previous items that are added at that position by an earlier call.

Returns

One of the following success or error codes:

• The code PlugPlugErrorCode_success indicates success.

• The code PlugPlugErrorCode_extensionMenuCreationFailed indicates that the extension menu creation

failed.

• The code PlugPlugErrorCode_unknown indicates that the function failed for unknown reasons.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Flash integration

Example

The following example is used for setting up the menu:

function initializeMenuItem(menuID, menuName,extensionID, submenu) {

var menuItem = {}; menuItem.menuId = menuID; //!< unique menu ID, if NULL menu is disabled menuItem.nameUtf8 = menuName; //!< Item title, if "---" item is a separator menuItem.extensionId = extensionID; //!< optional extension ID, used for panels only menuItem.submenu = submenu; //!< if non-NULL, this is a submenu return menuItem;

} function setupMenu() {

var menuItems = new Array(); menuItems.push(initializeMenuItem('id1','Call .swf

ActionScript',undefined,undefined)); menuItems.push(initializeMenuItem('id0','---',undefined,undefined)); menuItems.push(initializeMenuItem('id2','Call Dw JavaScript',undefined,undefined)); dw.flash.setMenu('Flickr',controlID,menuItems);

}

Note: Specify a function named "onSelectMenuItem" in the JavaScript file specified in the scriptPath in the object passed to newControl.

The onSelectMenuItem is a menu Item Handler. It gets called with the corresponding menu ID when a command is selected from the Floater's Fly Out menu.

The following example specifies the Callback handler definition in 'Configuration/flash/Flickr.js':

function onSelectMenuItem(menuID) {

if (menuID == 'id1') {

var flashCallbackString = '<invoke name= " flash Callback" returntype="xml"> <arguments><string>Hello</string></arguments></invoke>'; dw.flash.control Event('Flickr', flashCallbackString); return("PlugPlugRequestCompleted");

} else {

alert ( ' You selected: menuID = ' + menuID); return ( " PlugPlugRequestCompleted"); }

}

dreamweaver.flash.evalScript()

Availability

Dreamweaver CS4.

Description

This function is used to call a JavaScript function for one of the following purposes:

• To execute a JavaScript function defined in the script file associated with the extension (for CSXS extensions).

• The .js file defined in the scriptPath parameter for non-CSXS based Extensions.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Flash integration

Arguments

controlID, javascript function call

• The controlID argument is the ID of the extension to execute the script. This ID must match with the ID specified

as the first parameter to the

dw.flash.newControl().

• The JavaScript function call argument enables the user to call a function with any number of parameters.

Returns

A Boolean value: true if the function executed successfully; false otherwise.

dreamweaver.flash.executeScript()

Availability

Dreamweaver CS4.

Description

The function is used to execute functions in a .js file. The ActionScript in the .swf file starts the

dreamweaver.flash.executeScript() function.

Arguments

javascript function call

Note: Specify a path to the .js file that contains the functions you want to call.

Returns

An XML string that serializes into an ActionScript object.

Example

The following example contains a sample file, Sample.mxml and a JavaScript function in a JavaScript file, Sample.js.

private function executeScript():void

{

if(ExternalInterface.available) {

out.text += "SwfCalledHost\n"; var scriptText:String = "helloWorld('scott');\n"; var resultStr:Object =

ExternalInterface.call("dw.flash.executeScript",scriptText);

out.text += "Result: " + resultStr.strResult + '\n';

}

The following JavaScript file contains a JavaScript function helloWorld() that is called from the .swf. This function uses the

dw.getAppLanguage() call to return a five-letter language code that Dreamweaver is running in Sample.js.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Flash integration

function helloWorld(nameStr) {

alert('hello ' + nameStr); var appLanguage = dw.getAppLanguage(); var returnStr = '<object><property id="strResult"><string>Language: ' + appLanguage

+ '</string></property></object>' alert(returnStr); return (returnStr);

}

dreamweaver.flash.controlExists

Availability

Dreamweaver CS4.

Description

This function is used to check the existence of the controls. PanelWindow controls are saved between the launches of Dreamweaver.

Arguments

controlID

Returns

A Boolean value: true if the control has already been created, false otherwise.

Last updated 6/15/2011

Chapter 7: Photoshop integration

Adobe® Dreamweaver CS5® facilitates a compact integration with Adobe® Photoshop®. Users can insert Photoshop images as Smart Objects in Dreamweaver. Smart Objects automatically updates images in Dreamweaver if changes are made to the original images using Photoshop.

How Smart Objects work

Photoshop images are inserted as Smart Objects in Dreamweaver. The Smart Objects stay linked to the original Photoshop images. When users edit the image in Photoshop, they view an updated image in Dreamweaver. A Smart Object has a specific state, mainly resulting from the connection of the web image to its original asset file. Users can view the status of a Smart Object visually. The sync state of a Smart Object is indicated with the Sync badge.

The Smart Objects API

The Smart Object functions handle operations related to Dreamweaver and Photoshop integration. The functions enable you to perform the following tasks:

• Retrieve the state of an image

• Retrieve the height and width of an image

dreamweaver.assetPalette.canUpdateSmartObjectFromOriginal()

Availability

Dreamweaver CS4.

Description

Enabler: This function checks to see whether a Smart Object, on which we can issue the command "Update From Original," is selected in the Assets panel.

Arguments

None.

Returns

A Boolean value: true if "Update From Original" can be applied to current selection. false otherwise.

dreamweaver.assetPalette.updateSmartObjectFromOriginal()

Availability

Dreamweaver CS4.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Photoshop integration

Description

This function re-creates the selected web image based on the current contents of the connected original source file.

Arguments

None.

Returns

None.

dreamweaver.getSmartObjectState()

Availability

Dreamweaver CS4.

Description

This function returns the state of a web image in terms of Smart Objects functionality.

Arguments

Absolute local URL of a web image.

Returns

The state of the Smart Object as a numeric value such as:

Numeric value Description

-10 Unknown error

0 No Smart Object

1 In sync with contents of the original asset file

100 Web image modified after last sync

200 Original asset modified after last sync

+2 Dimensions of the original asset differ from width and height attributes in HTML

+4 Dimensions of web image differ from width and height attributes in HTML

10 Unable to access the original asset file

20 Unable to access web image file

dreamweaver.getSmartObjectOriginalWidth()

Availability

Dreamweaver CS4.

Description

This function evaluates and returns the pixel width of the original asset file of a Smart Object.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Photoshop integration

Arguments

Absolute local URL of the web image.

Returns

Pixel width of the original asset file.

dreamweaver.getImageWidth()

Availability

Dreamweaver CS4.

Description

This function evaluates and returns the pixel width of an image.

Arguments

Absolute local URL of a web image.

Returns

Pixel width of the image.

dreamweaver.getImageHeight()

Availability

Dreamweaver CS4.

Description

This function evaluates and returns the pixel height of an image.

Arguments

Absolute local URL of a web image.

Returns

Pixel height of the image.

dreamweaver.resolveOriginalAssetFileURLToAbsoluteLocalFilePath()

Availability

Dreamweaver CS4.

Description

This function resolves a file path to an original asset file (as it is stored in Design Notes). The path can be empty, site relative, or absolute.

Arguments

Absolute local URL or site relative URL to the web image. This URL is required to resolve the site.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

Photoshop integration

Returns

Absolute local file path.

dreamweaver.canUpdateSmartObjectFromOriginal()

Availability

Dreamweaver CS4.

Description

This function answers the question whether a Smart Object can be updated from its original asset file.

Arguments

Numeric status of Smart Object. ImageManipulatorSettings:GetSmartObjectStatus() returns this status.

Returns

A Boolean value: true if an update from the original image can be performed according to the status; false otherwise.

dreamweaver.updateSmartObjectFromOriginal()

Availability

Dreamweaver CS4.

Description

This function updates a web image based on the current contents of an original asset file.

Arguments

Absolute local URL of a web image.

Returns

None.

Last updated 6/15/2011

Chapter 8: 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 database connections and accessing database connections.

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® CS5 server behavior, data format, and data sources APIs all use these database functions.

How database API functions work

The following example shows how the server behavior function, getDynamicBindings(), is defined for Recordset.js. This example uses the

function getDynamicBindings(ss) {

var serverModel = dw.getDocumentDOM().serverModel.getServerName(); var bindingsAndTypeArray = new Array(); var connName=ss.connectionName; var statement = ss.source; var rsName= ss.rsName;

// remove SQL comments statement = statement.replace(/\/\*[\S\s]*?\*\//g, " "); 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++) {

} }

var statement = replaceParamsWithVals(statement, pa, serverModel);

}

bindingsAndTypeArray = MMDB.getColumnAndTypeList(connName, statement); return bindingsAndTypeArray;

}

MMDB.getColumnAndTypeList() function:

pa[i] = new Array();

pa[i][0] = ss.ParamArray[i].name;

pa[i][1] = ss.ParamArray[i].value;

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

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

In managing database connections, you can get the user name and password to perform activities including:

• Making a connection to a database

• Opening a database connection dialog box

MMDB.deleteConnection()

Availability

Dreamweaver MX.

Description

This function deletes the named database connection.

“Database access functions” on page 67.

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();

}

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

MMDB.getColdFusionDsnList()

Availability

Dreamweaver UltraDev 4.

Description

This function gets the ColdFusion data source names (DSNs) from the site server, using the getRDSUserName() and

getRDSPassword() functions.

Arguments

None.

Returns

An array that contains the ColdFusion DSNs that are defined on the server for the current site.

MMDB.getConnection()

Availability

Dreamweaver UltraDev 4, enhanced in Dreamweaver MX.

Description

This function gets a named connection object.

Arguments

name

• The name argument is a string variable that specifies the name of the connection that you want to reference.

Returns

A reference to a named connection object. Connection objects contain the following properties:

Property Description

name Connection name

type Indicates, if useHTTP is a value of false, which DLL to use for connecting to a database at runtime

string Runtime ADO connection string or JDBC URL

dsn ColdFusion DSN

driver Runtime JDBC driver

username Runtime user name

password Runtime password

useHTTP 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)

includePattern Regular expression used to find the file include statement on the page during Live Data and Preview

In Browser

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

Property Description

variables Array of page variable names and their corresponding values used during Live Data and Preview In

catalog Used to restrict the metadata that appears (for more information, see “MMDB.getProcedures()” on

schema Used to restrict the metadata that appears (for more information, see “MMDB.getProcedures()” on

filename Filename of dialog box that was used to create the connection

Browser

page 70)

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"].

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:

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

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

TdsDriver driver. You should pass the driver name to this function to fully qualify the connection name

you want to return.

Arguments

connString, {driverName}

• The connString argument is the connection string that gets the connection name.

• The driverName argument, which is optional, further qualifies the connString argument.

Returns

A connection name string that corresponds to the connection string.

Example

The following code returns the string "EmpDB":

var connectionName = MMDB.getConnectionName ¬ ("dsn=EmpDB;uid=;pwd=");

MMDB.getConnectionString()

Availability

Dreamweaver UltraDev 1.

Description

This function gets the connection string that is associated with the named connection.

Arguments

connName

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the

connection string that Dreamweaver should use to make a database connection to a live data source.

Returns

A connection string that corresponds to the named connection.

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"

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

MMDB.getDriverName()

Availability

Dreamweaver UltraDev 1.

Description

This function gets the driver name that is associated with the specified connection. Only a JDBC connection has a driver name.

Arguments

connName

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the

connection string that Dreamweaver should use to make a database connection to a live data source.

Returns

A string that contains the driver name.

Example

The statement MMDB.getDriverName ("EmpDB"); might return the following string:

"jdbc/oracle/driver/JdbcOracle"

MMDB.getLocalDsnList()

Availability

Dreamweaver UltraDev 4.

Description

This function gets ODBC DSNs that are defined on the user’s system.

Arguments

None.

Returns

An array that contains the ODBC DSNs that are defined on the user’s system.

MMDB.getPassword()

Availability

Dreamweaver UltraDev 1.

Description

This function gets the password that is used for the specified connection.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

Arguments

connName

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the

connection string that Dreamweaver should use to make a database connection to a live data source.

Returns

A password string that is associated with the connection name.

Example

The statement MMDB.getPassword ("EmpDB"); might return "joessecret".

MMDB.getRDSPassword()

Availability

Dreamweaver UltraDev 4.

Description

This function gets the Remote Development Services (RDS) password (for use with ColdFusion connections).

Arguments

None.

Returns

A string that contains the RDS password.

MMDB.getRDSUserName()

Availability

Dreamweaver UltraDev 4.

Description

This function gets the RDS user name (for use with ColdFusion connections).

Arguments

None.

Returns

A string that contains the RDS user name.

MMDB.getRemoteDsnList()

Availability

Dreamweaver UltraDev 4, enhanced in Dreamweaver MX.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

Description

This function gets the ODBC DSNs from the site server. The getRDSUserName() and getRDSPassword() functions are used when the server model of the current site is ColdFusion. This function provides an option for a developer to specify a URL parameter string to be appended to the Remote Connectivity URL that

MMDB.getRemoteDsnList()

generates. If the developer provides a parameter string, this function passes it to the HTTP connectivity scripts.

Arguments

{urlParams}

• The urlParams argument, which is optional, is a string that contains a list of name=value expressions, which are

separated by ampersand (&) characters. You must not enclose values with quotes. Some characters, such as the space in the value 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.

Returns

A string that corresponds to the connection type. This function can return one of the following values: "ADO",

"ADODSN", "JDBC", or "CFDSN".

Example

The following code returns the string "ADO" for an ADO connection:

var connectionType = MMDB.getRuntimeConnectionType ("EmpDB")

MMDB.getUserName()

Availability

Dreamweaver UltraDev 1.

Description

This function returns a user name for the specified connection.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

Arguments

connName

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the

connection string that Dreamweaver should use to make a database connection to a live data source.

Returns

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

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

Returns

A Boolean value: true indicates that the user needs to be prompted for RDS login information; false otherwise.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

MMDB.needToRefreshColdFusionDsnList()

Availability

Dreamweaver MX.

Description

This function tells the Connection Manager to empty the cache and get the ColdFusion data source list from the application server the next time a user requests the list.

Arguments

None.

Returns

Nothing.

MMDB.popupConnection()

Availability

Dreamweaver MX.

Description

This function starts a connection dialog box. This function has the following three signatures:

• If the argument list consists only of dialogFileName (a string), the popupConnection() function makes

Dreamweaver open the Connection dialog box so you can define a new connection.

• If the argument list consists only of connRec (a connection reference), the popupConnection() function makes

Dreamweaver launch the Connection dialog box in edit mode for editing the named connection. In this mode, the name text field is dimmed.

• If the argument list consists of connRec and the Boolean value bDuplicate, the popupConnection() function makes

Dreamweaver open the Connection dialog box in duplicate mode. In this mode, the name text field is blanked out, and the remaining properties are copied to define a duplicate connection.

Arguments

dialogFileName or connRec or connrec, bDuplicate

• The dialogFileName argument is a string that contains the name of an HTML file that resides in the

Configuration/Connections/server-model folder. This HTML file defines the dialog box that creates a connection. This file must implement three JavaScript API functions:

applyConnection(). Typically, you create a JavaScript file that implements these functions and then include that

file in the HTML file. (For more information on creating a connection, see page 79.)

findConnection(), inspectConnection(), and

“The database connectivity API” on

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

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

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()

Availability

Dreamweaver MX.

Description

This function displays the ColdFusion Administrator dialog box.

Arguments

None.

Returns

Nothing. The ColdFusion Administrator dialog box appears.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

MMDB.showConnectionMgrDialog()

Availability

Dreamweaver UltraDev 1.

Description

This function displays the Connection Manager dialog box.

Arguments

None.

Returns

Nothing. The Connection Manager dialog box appears.

MMDB.showOdbcDialog()

Availability

Dreamweaver UltraDev 4 (Windows only).

Description

This function displays the System ODBC Administration dialog box or the ODBC Data Source Administrator dialog box.

Arguments

None.

Returns

Nothing. The System ODBC Administration dialog box or the ODBC Data Source Administrator dialog box appears.

MMDB.showRdsUserDialog()

Availability

Dreamweaver UltraDev 4.

Description

This function displays the RDS user name and password dialog box.

Arguments

username, password

• The username argument is the initial user name.

• The password argument is the initial password.

Returns

An object that contains the new values in the username and password properties. If either property is not defined, it indicates that the user cancelled the dialog box.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

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.

Returns

An object that contains the new values in the catalog and schema properties. If either property is not defined, it indicates that the user cancelled the dialog box.

MMDB.testConnection()

Availability

Dreamweaver UltraDev 4.

Description

This function tests connection settings. It displays a modal dialog box that describes the results.

Arguments

serverPropertiesArray

This function expects a single argument, an array object that contains values from the following list, which are appropriate for the current server model. For properties that do not apply to the connection being tested, set them to

"").

empty (

• The type argument indicates, when useHTTP is a false value, which DLL to use for connecting to a database at

design time to test connection settings.

• The string argument is the ADO connection string or JDBC URL.

• The dsn argument is the data source name.

• The driver argument is the JDBC driver.

• The username argument is the user name.

• The password argument is the password.

• The useHTTP argument is a Boolean value. A value of true specifies that Dreamweaver should use an HTTP

connection at design time; otherwise, Dreamweaver uses a DLL.

Returns

A Boolean value: true if the connection test is successful; false otherwise.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

Database access functions

Database access functions let you query a database.

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.

For the collection of functions that manage a database connection, see “Database connection functions” on page 55.

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 connection names programmatically.

• Stored procedures often require parameters. You can specify parameter values for database access functions in two

ways. First, you can provide an array of parameter values ( values, the values must 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 parameter

names, the values that you specify in specify in

paramNameArray.

paramValuesArray must be in the sequence of the parameter names that you

MMDB.getConnectionList() function to get a list of all the

paramValuesArray). If you specify only parameter

paramNameArray). You can use the

MMDB.getColumnAndTypeList()

Availability

Dreamweaver UltraDev 1.

Description

This function gets a list of columns and their types from an executed SQL SELECT statement.

Arguments

connName, statement

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the

connection string that Dreamweaver should use to make a database connection to a live data source.

• The statement argument is the SQL SELECT statement to execute.

Returns

An array of strings that represents a list of columns (and their types) that match the SELECT statement, or an error if the SQL statement is invalid or the connection cannot be made.

Example

The code var columnArray = MMDB.getColumnAndTypeList("EmpDB","Select * from Employees") returns the following array of strings:

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

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 SELECT statement.

Arguments

connName, statement

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the

connection string that Dreamweaver should use to make a database connection to a live data source.

• The statement argument is the SQL SELECT statement to execute.

Returns

An array of strings that represents a list of columns that match the SELECT statement, or an error if the SQL statement is invalid or the connection cannot be made.

Example

The code var columnArray = MMDB.getColumnList("EmpDB","Select * from Employees") 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.

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.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

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 Name of the column (for example, price)

datatype Data type of the column (for example, small money)

definedsize Defined size of the column (for example, 8)

nullable Indicates whether the column can contain null values

Example

The following example uses MMDB.getColumns() to set the tooltip text value:

var columnNameObjs = MMDB.getColumns(connName,tableName); var databaseType = MMDB.getDatabaseType(connName); for (i = 0; i < columnNameObjs.length; i++)

{

var columnObj = columnNameObjs[i]; var columnName = columnObj.name; var typename = columnObj.datatype; if (dwscripts.isNumber(typename)) {

// it already is a num

typename = dwscripts.getDBColumnTypeAsString(typename, databaseType);

}

var tooltiptext = typename;

}

MMDB.getColumnsOfTable()

Availability

Dreamweaver UltraDev 1.

Description

This function gets a list of all the columns in the specified table.

Arguments

connName, tableName

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the

connection string that Dreamweaver should use to make a database connection to a live data source.

• The tableName argument is the name of a table in the database that is specified by the connName argument.

Returns

An array of strings where each string is the name of a column in the table.

Example

The statement MMDB.getColumnsOfTable ("EmpDB","Employees"); returns the following strings:

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

["EmpID", "FirstName", "LastName"]

MMDB.getPrimaryKeys()

Availability

Dreamweaver MX.

Description

This function returns the column names that combine to form the primary key of the named table. A primary key serves as the unique identifier for a database row and consists of at least one column.

Arguments

connName, tableName

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the

connection string that Dreamweaver should use to make a database connection to a live data source.

• The tableName argument is the name of the table for which you want to retrieve the set of columns that comprises

the primary key of that table.

Returns

An array of strings. The array contains one string for each column that comprises the primary key.

Example

The following example returns the primary key for the specified table.

var connName = componentRec.parent.parent.parent.name; var tableName = componentRec.name; var primaryKeys = MMDB.getPrimaryKeys(connName,tableName);

MMDB.getProcedures()

Availability

Dreamweaver MX.

Description

This function returns an array of procedure objects that are associated with a named connection.

Arguments

connName

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the

connection string that Dreamweaver should use to make a database connection to a live data source.

Returns

An array of procedure objects where each procedure object has the following set of three properties:

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

Property Name Description

schema Name of the schema that is associated with the object.

This property identifies the user that is associated with the stored procedure in the SQL database that the

getProcedures() function accesses. The database that this function accesses depends on the type of

connection.

• For ODBC connections, the ODBC data source defines the database. The DSN is specified by the 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 Name of the catalog that is associated with the object (owner qualifier).

The value of the catalog property is defined by an attribute of the OLE DB driver. This driver attribute defines a default database.

procedure Name of the procedure.

user.database property to use when the OLE DB connection string does not specify a

Note: Dreamweaver connects to and gets all the tables in the database whenever you modify a recordset. If the database has many tables, Dreamweaver might take a long time to retrieve them on certain systems. If your database contains a schema or catalog, you can use the schema or catalog to restrict the number of database items Dreamweaver gets at design time. You must first create a schema or catalog in your database application before you can apply it in Dreamweaver. Consult your database documentation or your system administrator.

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()

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.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

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

MMDB.getSPParamsAsString() function to get the parameters for the stored procedure.

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"

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.getSPParamsAsString() function to get the parameters of the stored procedure.

• The paramValuesArray argument is an array that contains a list of design-time parameter test values. You can

specify if the procedure requires parameters when it executes. If you have provided parameter names in paramNameArray, specify the parameter values in the same order that their corresponding parameter names appear in paramNameArray. If you did not provide paramNameArray, specify the values in the order in which the stored procedure expects them.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

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

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the

connection string that Dreamweaver should use to make a database connection to a live data source.

• The procName argument is the name of the procedure.

Returns

An array of parameter objects, each specifying the following set of properties:

Property name Description

name Name of the parameter (for example, @@lolimit)

datatype Datatype of the parameter (for example, smallmoney)

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

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

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.

Returns

A comma-delimited string that contains the list of parameters that the stored procedure requires. The parameters’ names, direction, and data type are included, separated by semicolons (;).

Example

The code MMDB.getSPParamsAsString ("EmpDB","getNewEmployeesMakingAtLeast") can return a string of form name

startDate;direction:in;datatype:date, salary;direction:in;datatype:integer.

In this example, the stored procedure, getNewEmployeesMakingAtLeast, has two parameters: startDate and

Salary. For startDate, the direction is in and the data type is date. For salary, the direction is in and the data type

date.

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:

table, schema, and catalog.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

Arguments

connName

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the

connection string that Dreamweaver should use to make a database connection to a live data source.

Returns

An array of objects where each object has three properties: 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.

table.

Example

The statement MMDB.getTables ("EmpDB"); might produce an array of two objects. The first object’s properties might be similar to the following example:

object1[table:"Employees", schema:"personnel", catalog:"syscat"]

The second object’s properties might be similar to the following example:

object2[table:"Departments", schema:"demo", catalog:"syscat2"]

MMDB.getViews()

Availability

Dreamweaver UltraDev 4.

Description

This function gets a list of all the views that are defined for the specified database. Each view object has catalog,

schema, and view 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 view objects where each object has three properties: catalog, schema, and view. Use catalog or schema to restrict or filter the number of views that pertain to an individual schema name or catalog name that is defined as part of the connection information.

Example

The following example returns the views for a given connection value, CONN_LIST.getValue():

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

var viewObjects = MMDB.getViews(CONN_LIST.getValue()) for (i = 0; i < viewObjects.length; i++) {

thisView = viewObjects[i] thisSchema = Trim(thisView.schema) if (thisSchema.length == 0) {

thisSchema = Trim(thisView.catalog) } if (thisSchema.length > 0) {

thisSchema += "." } views.push(String(thisSchema + thisView.view))

}

MMDB.showResultset()

Availability

Dreamweaver UltraDev 1.

Description

This function displays a dialog box that contains the results of executing the specified SQL statement.The dialog box displays a tabular grid in which the header provides column information that describes the result set. If the connection string or the SQL statement is invalid, an error appears. This function validates the SQL statement.

Arguments

connName, SQLstatement

• The connName argument is a connection name that is specified in the Connection Manager. It identifies the

connection string that Dreamweaver should use to make a database connection to a live data source.

• The SQLstatement argument is the SQL SELECT statement.

Returns

Nothing. This function returns an error if the SQL statement or the connection string is invalid.

Example

The following code displays the results of the executed SQL statement:

MMDB.showResultset("EmpDB","Select EmpName,EmpFirstName,Age ¬ from Employees")

MMDB.showSPResultset()

Availability

Dreamweaver UltraDev 1.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

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

MMDB.getSPParamsAsString() function to get the parameters of the stored procedure.

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 of the order in which the stored procedure expects them.

Arguments

connName, procName, paramNameArray, paramValuesArray

• The connName argument is a connection name that is specified in the Connection 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.getSPParamsAsString() function to get the parameters of the stored procedure.

• The paramValuesArray argument is an array that contains a list of design-time parameter test values.

MMDB.showSPResultset() function because you can specify the parameter values by name instead

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database API

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)

Last updated 6/15/2011

Chapter 9: 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®. Then, a user can create a connection object when setting up a site to start building pages. To create a connection object, the user has to first select the particular type of connection that you created.

Select a new connection type

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 pop-up menu.

• On the Database tab of the Databases panel, the user can click the Plus (+) button and select Data Source Name.

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, as shown in the following example:

<head>

</head>

Store this HTML file, which defines your connection dialog box, in the Configuration/Connections/servermodel/platform folder (where the platform is either Windows or Macintosh).

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

getServerModelFolderName() function, which returns the name of the folder that is associated with the

the server model. The following example shows the function for the ASP JavaScript document type:

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database connectivity API

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

A set of variables Each variable defines a specific connection

property

A set of buttons Each button appears in the connection dialog box Test, Help, and so on (OK and Cancel are

Connectivity functions Together, these functions define the Connectivity

API

Type of connection, data source name, and so on

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, 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 55.

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:).

findConnection(), inspectConnection(), and applyConnection(). You write these

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database connectivity API

The applyConnection() function returns an HTML source within an include file. You can see examples of the HTML source in

“The generated include file” on page 83. The findConnection() function takes the HTML source and extracts its properties. You can implement findConnection() to use the search patterns in XML files to extract the information that returns from

applyConnection(). For an example of such an implementation, see the following

two JavaScript files:

• The connection_ado_conn_string.js file is located in Configuration/Connections/ASP_Js folder.

• The connection_common.js file 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

findConnection(). If the contents of a file match the criteria for a valid connection, findConnection()

returns a connection object. Dreamweaver then lists all the connection objects in the Database Explorer panel.

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

inspectConnection() function and passes back the same connection object that

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

applyConnection() function returns an empty string that indicates there is an error in one of the fields and 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, connection object; otherwise, this function returns a

null value.

Argument

htmlSource

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

findConnection() returns a

name Name of the connection

type If useHTTP is false, indicates which DLL to use for connecting to database at runtime

string Runtime connection string. For ADO, it is a string of connection parameters; for JDBC, it is a

dsn Data source name used for ODBC or Cold Fusion runtime connections

connection URL

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database connectivity API

Property Description

driver Name of a JDBC driver used at runtime

username Name of the user for the runtime connection

password Password used for the runtime connection

designtimeString Design-time connection string (see string)

designtimeDsn Design-time data source name (see dsn)

designtimeDriver Name of a JDBC driver used at design time

designtimeUsername Name of the user used for the design-time connection

designtimePassword Password used for the design-time connection

designtimeType Design-time connection type

usesDesigntimeInfo When false, Dreamweaver uses runtime properties at design time; otherwise, Dreamweaver uses

useHTTP String containing either true or false:true specifies to use HTTP connection at design time;

includePattern Regular expression used to find the file include statement on the page during Live Data and Preview

variables Object with a property for each page variable that is set to its corresponding value. This object is

catalog String containing a database identifier that restricts the amount of metadata that appears

schema String containing a database identifier that restricts the amount of metadata that appears

filename Name of the dialog box used to create the connection

design-time properties

false specifies to use DLL

In Browser

used during Live Data and Preview In Browser

If a connection is not found in htmlSource, a null value returns.

Note: Developers can add custom properties (for example, metadata) to the HTML source, which applyConnection() returns along with the standard properties.

inspectConnection()

Availability

Dreamweaver UltraDev 4.

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.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database connectivity API

applyConnection()

Availability

Dreamweaver UltraDev 4.

Description

Dreamweaver calls this function when the user clicks OK in the connection dialog box. The applyConnection() 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

“Develop a new connection type” on page 79), and .ext is the default extension that is associated with the server

(see model.

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. It has the filename extension that is defined for the server model associated with the current site.

Note: Connections are shared, so set the allowMultiple value to false. It ensures that the connection file is included in the document only once. It also ensures that the server script remains in the page if any other server behaviors use it.

You can see some sample include files that applyConnection() generates for various default server models illustrated in the coming sections.

Note: To create a connection include file format, define a new EDML mapping file, which is like connection_includefile.edml, as shown in

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_ado_conn_string.htm" // Type="ADO" // HTTP="true" // Catalog="" // Schema="" var MM_MyConnection1_STRING = "dsn=pubs";

“The definition file for your connection type” on page 84.

The server behavior file includes this connection by using the relative file include statement, as shown in the following example:

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database connectivity API

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.

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:

<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:

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.

Dreamweaver provides 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 VBScrip ASP.NET_VB

ASP VBScript ASP_Vbs

ColdFusion ColdFusion

JavaServer Page JSP

PHP MySql PHP_MySql

Dreamweaver uses the quickSearch and searchPattern parameters to recognize connection blocks and the

insertText parameter to create connection blocks. For more information on EDML tags and attributes, and regular

expression search patterns, see “Server Behaviors” in Extending Dreamweaver.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The database connectivity API

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.

<![CDATA[// HTTP=]]></quickSearch>

</insertText>

<![CDATA[/\/\/\s*FileName="([^"]*)"/]]></searchPattern>

<![CDATA[/\/\/\s+Type="(\w*)"([^\r\n]*)/]]></searchPattern>

<![CDATA[/\/\/\s*DesigntimeType="(\w*)"/]]></searchPattern>

<![CDATA[/\/\/\s*HTTP="(\w+)"/]]></searchPattern>

<![CDATA[/\/\/\s*Catalog="(\w*)"/]]></searchPattern>

<![CDATA[/\/\/\s*Schema="(\w*)"/]]></searchPattern>

<![CDATA[/var\s+MM_(\w*)_STRING\s*=\s*([^\r\n]+)/]]></searchPattern>

</searchPatterns> </participant>

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 to the

PARTICIPANT_FILE variable, as shown in the following example:

var PARTICIPANT_FILE = "myConnection_mappingfile";

Last updated 6/15/2011

Chapter 10: The source control integration API

The source control integration API lets you write shared libraries. These APIs enable you to extend the Adobe® Dreamweaver® 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 CS5/Configuration/SourceControl folder.

When Dreamweaver starts, it loads each library. Dreamweaver determines which features the library supports by

GetProcAddress() for each API function. If an address does not exist, Dreamweaver assumes that the library

calling does not support the API. If the address exists, Dreamweaver uses the library 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 appear on the tab. These choices appear in addition to the standard items on the tab. The DLLs are loaded from the Program Files/Adobe/Adobe Dreamweaver CS5/Configuration/SourceControl folder.

To create a Site > Source Control menu to which you can add custom items, add the following code. Add the code in the Site menu in the menus.xml file:

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(),

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The source control integration API

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 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 item

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

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

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The source control integration API

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

Returns

A Boolean value: true if successful; false otherwise.

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

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.

Connect()

call.

Arguments

void *connectionData

•

The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the

Last updated 6/15/2011

Connect()

call.

DREAMWEAVER API REFERENCE

The source control integration API

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

• 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

GetRootFolderLength returns.

Returns

A Boolean value: true if successful; false otherwise.

Connect()

call.

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.

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

Last updated 6/15/2011

Connect()

call.

DREAMWEAVER API REFERENCE

The source control integration API

• 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

GetFolderListLength).

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.

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.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The source control integration API

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()

• 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

call.

•

The connectionData argument is a pointer to the agent’s data that passed into Dreamweaver during the

• 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

• The remotePathList argument is a list of remote filenames or folder paths to delete.

• The numItems argument is the number of items in remotePathList.

Returns

A Boolean value: true if successful; false otherwise.

Connect()

call.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The source control integration API

bool SCS_Rename()

Description

This function renames or moves a file or folder, depending on the values that are specified for oldRemotePath and newRemotePath. For example, if oldRemotePath equals

"$/folder1/renamefile1", file1 is renamed renamefile1 and is located in folder1.

If oldRemotePath equals "$/folder1/file1" and newRemotePath equals "$/folder1/subfolder1/file1", 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

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

"$/folder1/file1" and newRemotePath equals

Connect()

call.

Returns

A Boolean value: true if successful; false otherwise.

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()

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

call.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The source control integration API

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

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.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The source control integration API

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

• The enablerList argument is populated by the DLL; it specifies the routines in the DLL to call when Dreamweaver

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 SCS_GetNewFeatures() call

functionlist and enablerList arguments.

in the

bool (*scFunction)(void *connectionData, const char *remotePathList[],

const char *localPathList[], const int numItems)

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.

Last updated 6/15/2011

DREAMWEAVER API REFERENCE

The source control integration API

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.

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

• The localPathList argument is a mirrored list of local filenames or folder paths.

Last updated 6/15/2011

ADOBE Dreamweaver API CS5 User Manual [es, en]

Specifications and Main Features

Frequently Asked Questions

User Manual

Legal notices

Contents

Chapter 1: Introduction

About extensions

Extending Dreamweaver

Additional resources for extension writers

New functions in Dreamweaver CS5

Dynamic documents

Workspace

Document

Code

Conventions used in this guide

Chapter 2: The file I/O API

About configuration folders

About the file I/O API

DWfile.copy()

DWfile.createFolder()

DWfile.exists()

DWfile.getAttributes()

DWfile.getModificationDate()

DWfile.getCreationDate()

DWfile.getCreationDateObj()

DWfile.getModificationDateObj()

DWfile.getSize()

DWfile.listFolder()

DWfile.read()

DWfile.remove()

DWfile.setAttributes()

DWfile.write()

Chapter 3: The HTTP API

How the HTTP API works

The HTTP API

MMHttp.clearServerScriptsFolder()

MMHttp.clearTemp()

MMHttp.getFile()

MMHttp.getFileCallback()

MMHttp.getText()

MMHttp.getTextCallback()

MMHttp.postText()

MMHttp.postTextCallback()

Chapter 4: The Design Notes API

How Design Notes work

The Design Notes JavaScript API

MMNotes.close()

MMNotes.filePathToLocalURL()

MMNotes.get()

MMNotes.getKeyCount()

MMNotes.getKeys()

MMNotes.getSiteRootForFile()

MMNotes.getVersionName()

MMNotes.getVersionNum()

MMNotes.localURLToFilePath()

MMNotes.open()

MMNotes.remove()

MMNotes.set()

The Design Notes C API

void CloseNotesFile()

BOOL FilePathToLocalURL()

BOOL GetNote()

int GetNoteLength()

int GetNotesKeyCount()

BOOL GetNotesKeys()

BOOL GetSiteRootForFile()

BOOL GetVersionName()

BOOL GetVersionNum()

BOOL LocalURLToFilePath()

FileHandle OpenNotesFile()

FileHandle OpenNotesFilewithOpenFlags()

BOOL RemoveNote()

BOOL SetNote()

Chapter 5: Fireworks integration

The FWLaunch API

FWLaunch.bringDWToFront()

FWLaunch.bringFWToFront()

FWLaunch.execJsInFireworks()

FWLaunch.getJsResponse()