ADOBE Dreamweaver API CS4 User Manual [es, en]

ADOBE® DREAMWEAVER® CS4

API Reference

If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement. The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide.

Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner. Please be sure to obtain any permission required from the copyright owner. Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization.

Adobe, the Adobe logo, ColdFusion, Dreamweaver, Fireworks, Flash, Photoshop, and Shockwave are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States.

Java is a trademark or registered trademark of Sun Microsystems, Inc. in the United States and other countries. Windows is either a registered trademark or a trademark of Microsoft Corporation in the United States and/or other countries. Macintosh and Mac OS are trademarks of Apple Inc., registered in the United States and other countries. All other trademarks are the property of their respective owners.

This work is licensed under the Creative Commons Attribution Non-Commercial 3.0 License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc/3.0/us/

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

The Graphics Interchange Format © is the Copyright property of CompuServe Incorporated.

GIF is a Service Mark property of CompuServe Incorporated.

MPEG Layer-3 audio compression technology licensed by Fraunhofer IIS and Thomson Multimedia (http://www.mp3licensing.com). You cannot use the MP3 compressed audio within the Software for real time or live broadcasts. If you require an MP3 decoder for real time or live broadcasts, you are responsible for obtaining this MP3 technology license.

Speech compression and decompression technology licensed from Nellymoser, Inc. (www.nellymoser.com)

This product includes software developed by the OpenSymphony Group (http://www.opensymphony.com/)

Sorenson Spark™ video compression and decompression technology licensed from Sorenson Media, Inc.

1994. All Rights Reserved. Proximity Technology Inc. The Proximity/Merriam-Webster Inc./Franklin Electronic Publishers Inc. © 1990 Williams Collins Sons & Co. Ltd. © 1997 - All rights reserved Proximity Technology Inc. © 1990 Williams Collins Sons & Co. Ltd. © 1990 - All rights reserved Proximity Technology Inc. © Oxford University Press © 2000. All rights reserved Proximity Technology Inc. © 1990 IDE a.s. © 1990 - All rights reserved Proximity Technology Inc.

This product includes software developed by Fourthought, Inc. (http://www.fourthought.com).

This product includes software developed by CollabNet (http://www.Collab.Net/).

Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.

Notice to U.S. Government End Users. The Software and Documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101, consisting of “Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublishedrights reserved under the copyright laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA 95110-2704, USA. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference.

Chapter 1: Introduction

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

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

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

New functions in Dreamweaver CS4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Removed functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Conventions used in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2: The file I/O API

About configuration folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

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

Chapter 3: The HTTP API

How the HTTP API works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

The HTTP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

iii

Chapter 4: The Design Notes API

How Design Notes work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

The Design Notes JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

The Design Notes C API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 5: Fireworks integration

The FWLaunch API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Chapter 6: Flash integration

The Flash Objects API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Flash panels and dialogs functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Chapter 7: Photoshop integration

How Smart Objects work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

The Smart Objects API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Chapter 8: The database API

How database API functions work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Database connection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Database access functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Chapter 9: The database connectivity API

Select a new connection type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Develop a new connection type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

The Connection API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

The generated include file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

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

DREAMWEAVER CS4 API REFERENCE

Contents

Chapter 10: The source control integration API

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

Adding source control system functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

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

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

Enablers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Chapter 11: Application

External application functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Global application functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Bridge communication functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Chapter 12: Workspace

History functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Insert object functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Keyboard functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Menu functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Results window functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Toggle functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Toolbar functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Window functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Information bar functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Related files functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Vertical Split view functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Code collapse functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Code view toolbar functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Color functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Chapter 13: Site

Report functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

Site functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Chapter 14: Document

Conversion functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Command functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

File manipulation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Global document functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

Path functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

Selection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

String manipulation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Translation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

XSLT functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Chapter 15: Page content

Assets panel functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

Behavior functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Clipboard functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Library and template functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

DREAMWEAVER CS4 API REFERENCE

Contents

Snippets panel functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Spry widget editing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Inserting Spry widgets functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Browser compatibility check functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Chapter 16: Dynamic documents

Server components functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Data source functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Extension Data Manager functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Live data functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Live view functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Server behavior functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

Server model functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

Chapter 17: Design

CSS layout functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

Frame and frameset functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

Layer and image map functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

Layout environment functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

Layout view functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

Zoom functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

Guide functions and properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

Table editing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390

Chapter 18: Code

Code functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400

Find and replace functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404

General editing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

Print function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

Quick Tag Editor functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426

Code view functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

Tag editor and tag library functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445

Chapter 19: Enablers

Enabler functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

Index ...............................................................................................................487

Chapter 1: Introduction

The Adobe Dreamweaver CS4 API Reference describes the application programming interfaces (APIs). The APIs let you perform various supporting tasks when developing Adobe® Dreamweaver® CS4 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.

DREAMWEAVER CS4 API REFERENCE

Introduction

New functions in Dreamweaver CS4

The following new functions are added to the Dreamweaver CS4 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.getDesignViewMode()” on page 331

• “dom.setDesignViewMode()” on page 331

• “dom.getLiveViewUsingServer()” on page 332

• “dom.setLiveViewUsingServer()” on page 332

• “dom.getLiveViewDefaultsToUsingServer()” on page 332

• “dom.getLiveViewDependentsUsingServer()” on page 333

• “dom.setLiveViewDependentsUsingServer()” on page 333

• “dom.showLiveViewParamatersDialog()” on page 333

• “dom.browser.getSelection()” on page 334

• “dom.browser.getStatusText()” on page 334

• “dom.browser.getWindow()” on page 334

• “browserEle.loadHTML()” on page 335

Photoshop integration

The following new functions are added to the Photoshop integration chapter.

Smart Objects API

• “dreamweaver.assetPalette.canUpdateSmartObjectFromOriginal()” on page 51

• “dreamweaver.assetPalette.updateSmartObjectFromOriginal()” on page 51

• “dreamweaver.getSmartObjectState()” on page 52

• “dreamweaver.getSmartObjectOriginalWidth()” on page 52

• “dreamweaver.getImageWidth()” on page 53

• “dreamweaver.getImageHeight()” on page 53

• “dreamweaver.resolveOriginalAssetFileURLToAbsoluteLocalFilePath()” on page 53

• “dreamweaver.canUpdateSmartObjectFromOriginal()” on page 54

• “dreamweaver.updateSmartObjectFromOriginal()” on page 54

Workspace

The following new functions are added to the Workspace chapter.

Related files functions

• “dreamweaver.getRelatedFiles()” on page 190

• “dreamweaver.openRelatedFile()” on page 190

• “dreamweaver.getActiveRelatedFilePath()” on page 190

Information bar functions

• “dom.showInfoBar()” on page 189

• “dom.hideInfoBar()” on page 189

Vertical Split view functions

• “dreamweaver.getSplitViewOrientation()” on page 191

• “dreamweaver.setSplitViewOrientation()” on page 191

• “dreamweaver.getPrimaryView()” on page 192

• “dreamweaver.setPrimaryView()” on page 192

• “dom.isRelatedFileViewOpen()” on page 193

Toolbar functions

• “dreamweaver.reloadToolbars()” on page 178

DREAMWEAVER CS4 API REFERENCE

Introduction

Flash integration

The following new functions are added to the Flash integration chapter.

Flash panels and dialogs functions

• “dreamweaver.flash.newControl()” on page 43

• “dreamweaver.flash.requestStateChange()” on page 45

• “dreamweaver.flash.controlEvent()” on page 46

• “dreamweaver.flash.setMenu()” on page 47

• “dreamweaver.flash.evalScript()” on page 49

• “dreamweaver.flash.executeScript()” on page 49

• “dreamweaver.flash.controlExists” on page 50

Site

The following new functions are added to the Sites chapter.

• “site.getLocalRootURL()” on page 224

• “site.getSiteRootForURL()” on page 225

Document

The following new functions are added to the Document chapter.

• “dom.getSelectorsDefinedInStylesheet()” on page 267

• “dreamweaver.absoluteURLToDocRelative()” on page 263

DREAMWEAVER CS4 API REFERENCE

Introduction

Code

The following new functions are added to the Code chapter.

• “dom.source.doCodeNavItem()” on page 433

Removed functions

The following functions are removed from the Dreamweaver CS4 API because the associated features are removed from the product.

site.setShowPageTitles() site.removeLink()

site.canShowPageTitles() site.invertSelection()

site.getShowPageTitles() site.selectHomePage()

site.setShowHiddenFiles() site.newHomePage()

site.getShowHiddenFiles() site.setLayout()

site.setShowDependents() dom.createLayoutCell()

site.getShowDependents() dom.createLayoutTable()

site.canFindLinkSource() dom.setColumnAutostretch()

site.findLinkSource() dom.isColumnAutostretch()

site.viewAsRoot() dom.doesColumnHaveSpacer()

site.setAsHomePage() dom.doesGroupHaveSpacer()

site.canSetLayout() dom.addSpacerToColumn()

site.canRemoveLink() dom.removeSpacerFromColumn()

site.canChangeLink() dom.removeAllSpacers()

site.canAddLink() dom.makeCellWidthsConsistent()

site.addLinkToNewFile() dom.insertFlashElement()

site.getLinkVisibility() dreamweaver.exportCSS() (deprecated in CS3)

site.setLinkVisibility() dreamweaver.canExportCSS() (deprecated in CS3)

site.saveAsImage() dreamweaver.libraryPalette.deleteSelectedItem()

dreamweaver.libraryPalette.get SelectedItem() (deprecated in Dreamweaver 4)

dreamweaver.libraryPalette.recr eateFromDocument() (deprecated in Dreamweaver 4)

(deprecated in Dreamweaver 4)

dreamweaver.libraryPalette.newFromDocument() (deprecated in Dreamweaver 4)

dreamweaver.libraryPalette.renameSelectedItem() (deprecated in Dreamweaver 4)

dreamweaver.templatePalette.d eleteSelectedTemplate() (deprecated in Dreamweaver 4)

dreamweaver.templatePalette.getSelectedTempla te() (deprecated in Dreamweaver 4)

DREAMWEAVER CS4 API REFERENCE

Introduction

dreamweaver.templatePalette.r enameSelectedTemplate() (deprecated in Dreamweaver 4)

dom.clipPasteText() (deprecated in Dreamweaver 8)

dom.serverModel.getServerLan guage() (deprecated in Dreamweaver MX)

dreamweaver.getObjectRefs() (deprecated in Dreamweaver 3)

dreamweaver.getSelection() (deprecated in Dreamweaver 3)

dreamweaver.offsetsToNode() (deprecated in Dreamweaver 3)

dreamweaver.exportEditableRe gionsAsXML() (deprecated in Dreamweaver MX)

MMDB.getDriverUrlTemplateLis t() (deprecated in Dreamweaver MX)

dreamweaver.getBehaviorEvent() (deprecated in Dreamweaver 2)

dreamweaver.popupCommand() (deprecated in Dreamweaver 3)

dom.serverModel.getServerExtension() (deprecated in Dreamweaver MX)

dreamweaver.getObjectTags() (deprecated in Dreamweaver 3)

dreamweaver.nodeToOffsets() (deprecated in Dreamweaver 3)

dreamweaver.setSelection() (deprecated in Dreamweaver 3)

dreamweaver.cssStylePalette.getSelectedTarget() (deprecated in Dreamweaver MX)

For more information on these deprecated APIs, see Dreamweaver API Reference for CS3.

Conventions used in this guide

Typographical conventions

The following typographical conventions are used in this guide:

• Code font indicates code fragments and API literals, including class names, method names, function names, type

names, scripts, SQL statements, and both HTML and XML tag and attribute names.

• Italic code font indicates replaceable items in code.

• The continuation symbol (¬ ) indicates that a long line of code has been broken across two or more lines. Due to

margin limits in this book’s format, what is otherwise a continuous line of code must be split. When copying the lines of code, eliminate the continuation symbol and type the lines as one line.

• Curly braces ({}) that surround a function argument indicate that the argument is optional.

• Function names that have the prefix dreamweaver.funcname can be abbreviated to dw.funcname when you are

writing code. This manual uses the full examples use the

dw. prefix, however.

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

dreamweaver. prefix when defining the function and in the index. Many

Chapter 2: The file I/O API

Adobe® Dreamweaver® CS4 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:

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

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

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

DREAMWEAVER CS4 API REFERENCE

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 file I/O API

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

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

DREAMWEAVER CS4 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);

}

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

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

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.

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

DREAMWEAVER CS4 API REFERENCE

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

The HTTP API

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

DREAMWEAVER CS4 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 17 for a list of possible error codes.

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

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

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

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.

DREAMWEAVER CS4 API REFERENCE

Arguments

fileHandle

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

Returns

Nothing.

Example

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

MMNotes.filePathToLocalURL()

Description

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

Arguments

drivePath

The Design Notes API

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

DREAMWEAVER CS4 API REFERENCE

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.

The Design Notes API

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.

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

+ 482 hidden pages