User manual MACROMEDIA DREAMWEAVER 8 - DREAMWEAVER API REFERENCE

Dreamweaver API Reference Trademarks 1 Step RoboPDF, ActiveEdit, ActiveTest, Authorware, Blue Sky Software, Blue Sky, Breeze, Breezo, Captivate, Central, ColdFusion, Contribute, Database Explorer, Director, Dreamweaver, Fireworks, Flash, FlashCast, FlashHelp, Flash Lite, FlashPaper, Flex, Flex Builder, Fontographer, FreeHand, Generator, HomeSite, JRun, MacRecorder, Macromedia, MXML, RoboEngine, RoboHelp, RoboInfo, RoboPDF, Roundtrip, Roundtrip HTML, Shockwave, SoundEdit, Studio MX, UltraDev, and WebHelp are either registered trademarks or trademarks of Macromedia, Inc. and may be registered in the United States or in other jurisdictions including internationally. Other product names, logos, designs, titles, words, or phrases mentioned within this publication may be trademarks, service marks, or trade names of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally. Third-Party Information This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia endorses or accepts any responsibility for the content on those third-party sites. Opera ® browser Copyright © 1995-2002 Opera Software ASA and its suppliers. All rights reserved. Copyright © 2005 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced, translated, or converted to any electronic or machine-readable form in whole or in part without written approval from Macromedia, Inc. Notwithstanding the foregoing, the owner or authorized user of a valid copy of the software with which this manual was provided may print out one copy of this manual from an electronic version of this manual for the sole purpose of such owner or authorized user learning to use such software, provided that no part of this manual may be printed out, reproduced, distributed, resold, or transmitted for any other purposes, including, without limitation, commercial purposes, such as selling copies of this documentation or providing paid-for support services. Acknowledgments Project Management: Charles Nadeau, Robert Berry Writing: Anne Sandstrom Editing: Anne Szabla, John Hammett Production and Editing Management: Patrice O'Neill and Rosana Francescato Media Design and Production: Adam Barnett, Aaron Begley, Paul Benkman, John Francis, Geeta Karmarkar Localization Management: Melissa Baerwald Special thanks to Jay London, Raymond Lim, Alain Dumesny, and the entire Dreamweaver engineering and QA teams. First Edition: September 2005 Macromedia, Inc. 601 Townsend St. San Francisco, CA 94103 Contents Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Extending Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Additional resources for extension writers . . . . . . . . . . . . . . . . . . . . . . . . . 8 New functions in Dreamweaver 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Removed functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Errata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Conventions used in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 PART 1: UTILITY APIS Chapter 1: The File I/O API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Accessing configuration folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 The File I/O API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Chapter 2: The HTTP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 How the HTTP API works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 The HTTP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Chapter 3: The Design Notes API . . . . . . . . . . . . . . . . . . . . . . . . . 39 How Design Notes work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 The Design Notes JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 The Design Notes C API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Chapter 4: Fireworks Integration . . . . . . . . . . . . . . . . . . . . . . . . . 53 The FWLaunch API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Chapter 5: Flash Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 How Flash elements work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Inserting Flash elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 The Flash Objects API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 3 Chapter 6: The Database API . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69 How Database API functions work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Database connection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Database access functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Chapter 7: The Database Connectivity API . . . . . . . . . . . . . . . . . 101 How to develop a new connection type . . . . . . . . . . . . . . . . . . . . . . . . . .101 The Connection API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 The generated include file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 The definition file for your connection type . . . . . . . . . . . . . . . . . . . . . . 109 Chapter 8: The JavaBeans API. . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 The JavaBeans API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Chapter 9: The Source Control Integration API . . . . . . . . . . . . . .117 How source control integration with Dreamweaver works. . . . . . . . . . 118 Adding source control system functionality. . . . . . . . . . . . . . . . . . . . . . . 118 The Source Control Integration API required functions . . . . . . . . . . . .119 The Source Control Integration API optional functions . . . . . . . . . . . 126 Enablers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 PART 2: JAVASCRIPT API Chapter 10: Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 External application functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Global application functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Chapter 11: Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 History functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161 Insert object functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Keyboard functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 Menu functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 Results window functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Toggle functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Toolbar functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222 Window functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229 Code collapse functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 Code view toolbar functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 4 Contents Chapter 12: Site. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Report functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Site functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Chapter 13: Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 Conversion functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 Command functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 File manipulation functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 Global document functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321 Path functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 Selection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 String manipulation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 Translation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 XSLT functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351 Chapter 14: Page Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 Assets panel functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 Behavior functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 Clipboard functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 Library and template functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 Snippets panel functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .391 Chapter 15: Dynamic Documents . . . . . . . . . . . . . . . . . . . . . . . . 397 Server Components functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 Data source functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 Extension Data Manager functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 Live data functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 Server behavior functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 Server model functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .410 Chapter 16: Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 CSS functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419 Frame and frameset functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .441 Layer and image map functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443 Layout environment functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446 Layout view functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 Zoom functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464 Guide functions and properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 Table editing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 Contents 5 Chapter 17: Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 Code functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 Find/replace functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494 General editing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500 Print function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520 Quick Tag Editor functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 Code view functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524 Tag editor and tag library functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 Chapter 18: Enablers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551 Enablers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599 6 Contents Introduction The Dreamweaver API Reference describes two application programming interfaces (APIs) that let you perform various supporting tasks when developing Macromedia Dreamweaver 8 extensions and adding program code to your Dreamweaver web pages. These two APIs are the utility API and the JavaScript API. The utility API contains subsets of related functions that let you perform specific types of tasks. The utility API includes the following API subsets: The File I/O API, which lets you read and write files on the local file system The HTTP API, which lets you send and receive information from a web server The Design Notes API, which lets you store and retrieve notes about Dreamweaver documents The Fireworks Integration API, which lets you communicate with Macromedia Fireworks Flash Integration, which contains information about adding Flash elements to the Dreamweaver user interface (UI) and details on the Flash Objects API (which lets you build objects that create Macromedia Flash content) The Database API, which lets you access information stored in databases and manage database connections The Database Connectivity API, which lets you create a new connection type and corresponding dialog boxes for new or existing server models The JavaBeans API, which retrieves class names, methods, properties, and events for JavaBeans that you have defined The Source Control Integration API, which lets you write shared libraries to extend the Dreamweaver Check In/Check Out feature The extensive JavaScript API lets you perform a diverse set of smaller tasks, many of which are tasks that a user would perform when creating or editing Dreamweaver documents. These API functions are grouped by the parts of the Dreamweaver UI that they affect. For example, the JavaScript API includes Workspace functions, Document functions, Design functions, and so on. These functions let you perform tasks such as opening a new document, getting or setting a font size, finding the occurrence of a search string in HTML code, making a toolbar visible, and much more. 7 Background This book assumes that you are familiar with Dreamweaver, HTML, XML, JavaScript programming and, if applicable, C programming. If you are writing extensions for building web applications, you should also be familiar with server-side scripting on at least one platform, such as Active Server Pages (ASP), ASP.net, PHP: Hypertext Preprocessor (PHP), ColdFusion, or Java Server Pages (JSP). Extending Dreamweaver To learn about the Dreamweaver framework and the API that enables you to build Dreamweaver extensions, see Extending Dreamweaver. Extending Dreamweaver describes the API functions that Dreamweaver calls to implement the objects, menus, floating panels, server behaviors, and so on, that comprise the various features of Dreamweaver. You can use those APIs to add objects, menus, floating panels, or other features to the product. Extending Dreamweaver also explains how to customize Dreamweaver by editing and adding tags to various HTML and XML files to add menu items or document types, and so on. Additional resources for extension writers To communicate with other developers who are involved in writing extensions, you might want to join the Dreamweaver extensibility newsgroup. You can access the website for this newsgroup at www.macromedia.com/go/extending_newsgrp/. New functions in Dreamweaver 8 The following new functions have been added to the Dreamweaver 8 JavaScript API. The headings designate the chapters and sections that contain the new functions: Application The following Global application functions have been added to the Application chapter. Global application dreamweaver.showPasteSpecialDialog() dreamweaver.showPreferencesDialog() on page 158 on page 159 (added new argument) 8 Introduction Workspace The following new Window, Code collapse, and Code view toolbar functions have been added to the Workspace chapter. Window dreamweaver.cascade() on page 231 (added support for the Macintosh) on page 239 (added support for the Macintosh) on page 240 (added support for the Macintosh) dreamweaver.tileHorizontally() dreamweaver.tileVertically() Code collapse dom.collapseFullTag() on page 241 on page 243 on page 243 dom.collapseSelectedCodeFragment() dom.collapseSelectedCodeFragmentInverse() dom.expandAllCodeFragments() on page 244 on page 245 on page 245 on page 246 dom.expandSelectedCodeFragments() dreamweaver.htmlInspector.collapseFullTag() dreamweaver.htmlInspector.collapseSelectedCodeFragment() dreamweaver.htmlInspector.collapseSelectedCodeFragmentInverse() on page 247 dreamweaver.htmlInspector.expandAllCodeFragments() on page 248 on page 248 dreamweaver.htmlInspector.expandSelectedCodeFragments() Code view toolbar dom.getOpenPathName() on page 249 on page 249 on page 250 dom.getShowHiddenCharacters() dom.setShowHiddenCharacters() dom.source.applyComment() on page 251 on page 251 on page 252 on page 253 dom.source.removeComment() dreamweaver.htmlInspector.getShowHiddenCharacters() dreamweaver.htmlInspector.setShowHiddenCharacters() Site The following new Site functions have been added to the Site chapter. New functions in Dreamweaver 8 9 Site dom.getSiteURLPrefixFromDoc() dom.localPathToSiteRelative() dom.siteRelativeToLocalPath() dreamweaver.compareFiles() on page 256 on page 257 on page 257 on page 259 on page 260 on page 261 on page 262 on page 260 on page 261 on page 258 dreamweaver.siteSyncDialog.compare() dreamweaver.siteSyncDialog.markDelete() dreamweaver.siteSyncDialog.markGet() dreamweaver.siteSyncDialog.markIgnore() dreamweaver.siteSyncDialog.markPut() dreamweaver.siteSyncDialog.markSynced() site.compareFiles() on page 267 on page 274 on page 280 on page 294 site.getAppURLPrefixForSite() site.getSiteURLPrefix() site.serverActivity() on page 290 site.siteRelativeToLocalPath() Document The following new File manipulation functions have been added to the Document chapter. File manipulation dreamweaver.getNewDocumentDOM() MMXSLT.getXMLSchema() on page 312 (added new argument) on page 351 on page 352 on page 353 MMXSLT.getXMLSourceURI() MMXSLT.launchXMLSourceDialog() Page content The following new Clipboard functions have been added to the Page content chapter: Clipboard dreamweaver.clipPaste() on page 383 (added new argument) 10 Introduction Design The following new CSS, Layout view, and Zoom functions have been added to the Design chapter: CSS cssStylePalette.getInternetExplorerRendering() cssStylePalette.setInternetExplorerRendering() dom.getElementView() on page 419 on page 420 on page 421 on page 422 on page 422 on page 423 on page 424 on page 426 dom.getShowDivBackgrounds() dom.getShowDivBoxModel() dom.getShowDivOutlines() dom.resetAllElementViews() dom.setElementView() on page 425 on page 426 on page 427 on page 428 (added new on page 429 (added new on page 430 (added dom.setShowDivBackgrounds() dom.setShowDivBoxModel() dom.setShowDivOutlines() dreamweaver.cssStylePalette.applySelectedStyle() argument) dreamweaver.cssStylePalette.deleteSelectedStyle() argument) dreamweaver.cssStylePalette.duplicateSelectedStyle() new argument) dreamweaver.cssStylePalette.editSelectedStyle() on page 430 (added new on page 431 argument) dreamweaver.cssStylePalette.editSelectedStyleInCodeview() dreamweaver.cssStylePalette.getDisplayStyles() on page 432 on page 436 on page 436 dreamweaver.cssStylePalette.renameSelectedStyle() dreamweaver.cssStylePalette.setDisplayStyles() dreamweaver.getBlockVisBoxModelColors() on page 437 on page 438 on page 439 dreamweaver.getBlockVisOutlineProperties() dreamweaver.getDivBackgroundColors() on page 439 on page 440 dreamweaver.setBlockVisOutlineProperties() dreamweaver.setDivBackgroundColors() New functions in Dreamweaver 8 11 Layout view dom.getShowBlockBackgrounds() dom.getShowBlockBorders() dom.getShowBlockIDs() dom.getShowBoxModel() on page 459 on page 459 on page 460 on page 461 on page 461 on page 462 dom.setShowBlockBackgrounds() dom.setShowBlockBorders() dom.setShowBlockIDs() dom.setShowBoxModel() on page 462 on page 463 Zoom dreamweaver.activeViewScale() dreamweaver.fitAll() on page 464 on page 465 on page 465 on page 466 dreamweaver.fitSelection() dreamweaver.fitWidth() dreamweaver.zoomIn() on page 466 on page 467 dreamweaver.zoomOut() Guide dom.clearGuides() on page 468 on page 468 on page 470 on page 469 on page 470 dom.createHorizontalGuide() dom.createVerticalGuide() dom.deleteHorizontalGuide() dom.deleteVerticalGuide() dom.guidesColor on page 471 on page 471 on page 473 on page 472 on page 473 on page 474 dom.guidesDistanceColor dom.guidesLocked dom.guidesSnapToElements dom.guidesVisible dom.hasGuides() on page 474 on page 475 dom.hasHorizontalGuide() dom.hasVerticalGuide() 12 Introduction Enablers The following new functions have been added to the Enablers chapter: dreamweaver.canFitSelection() dreamweaver.canPasteSpecial() dreamweaver.canZoom() on page 568 on page 568 on page 575 (added new on page 575 (added on page 576 (added on page 574 dreamweaver.cssStylePalette.canApplySelectedStyle() argument) dreamweaver.cssStylePalette.canDeleteSelectedStyle() new argument) dreamweaver.cssStylePalette.canDuplicateSelectedStyle() new argument) dreamweaver.cssStylePalette.canEditSelectedStyle() on page 577 (added new on page 577 argument) dreamweaver.cssStylePalette.canEditSelectedStyleInCodeview() dreamweaver.cssStylePalette.canRenameSelectedStyle() dreamweaver.siteSyncDialog.canCompare() on page 578 on page 582 on page 583 on page 584 on page 585 on page 583 on page 584 dreamweaver.siteSyncDialog.canMarkDelete() dreamweaver.siteSyncDialog.canMarkGet() dreamweaver.siteSyncDialog.canMarkIgnore() dreamweaver.siteSyncDialog.canMarkPut() dreamweaver.siteSyncDialog.canMarkSynced() site.canCompareFiles() on page 589 Removed functions The following functions have been removed from the Dreamweaver 8 API because the associated features have been removed from the product. Errata A current list of known issues can be found in the Extensibility section of the Dreamweaver Support Center (www.macromedia.com/go/extending_errata). Errata 13 Conventions used in this guide The following typographical conventions are used in this guide: Code font indicates code fragments and API literals, including class names, method names, function names, type names, scripts, SQL statements, and both HTML and XML tag and attribute names. font indicates replaceable items in code. Italic code The continuation symbol (¬) indicates that a long line of code has been broken across two or more lines. Due to margin limits in this book's format, what is otherwise a continuous line of code must be split. When copying the lines of code, eliminate the continuation symbol and type the lines as one line. Curly braces ({ }) that surround a function argument indicate that the argument is optional. Function names that have the prefix dreamweaver.funcname can be abbreviated to dw.funcname when you are writing code. This manual uses the full dreamweaver. prefix when defining the function and in the index. Many examples use the dw. prefix, however. You--the developer who is responsible for writing extensions The user--the person using Dreamweaver The following naming conventions are used in this guide: 14 Introduction PART 1 Utility APIs Learn about the Macromedia Dreamweaver 8 utility functions that you can use to access local and web-based files, work with Macromedia Fireworks, and Macromedia Flash objects, manage database connections, create new database connection types, access JavaBeans fscomponents, and integrate Dreamweaver with various source control systems. Chapter 1: The File I/O API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Chapter 2: The HTTP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29 Chapter 3: The Design Notes API . . . . . . . . . . . . . . . . . . . . . . . . . . .39 Chapter 4: Fireworks Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . .53 Chapter 5: Flash Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Chapter 6: The Database API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69 Chapter 7: The Database Connectivity API . . . . . . . . . . . . . . . . . . 101 Chapter 8: The JavaBeans API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Chapter 9: The Source Control Integration API. . . . . . . . . . . . . . . .117 1 15 CHAPTER 1 The File I/O API Macromedia Dreamweaver 8 includes a C shared library called DWfile, which gives authors of objects, commands, behaviors, data translators, floating panels, and Property inspectors the ability to read and write files on the local file system. This chapter describes the File I/O API and how to use it. For general information on how C libraries interact with the JavaScript interpreter in Dreamweaver, see "C-Level Extensibility" in Extending Dreamweaver. 1 Accessing configuration folders On Microsoft Windows 2000 and Windows XP, and Mac OS X platforms, users have their own copies of configuration files. Whenever Dreamweaver writes to a configuration file, Dreamweaver writes it to the user's Configuration folder. Similarly, when Dreamweaver reads a configuration file, Dreamweaver searches for it first in the user's Configuration folder and then in the Dreamweaver Configuration folder. DWfile functions use the same mechanism. In other words, if your extension reads or writes a file in the Dreamweaver Configuration folder, your extension also accesses the user's Configuration folder. For more information about configuration folders on multiuser platforms, see Extending Dreamweaver. The File I/O API All functions in the File I/O API are methods of the DWfile object. DWfile.copy() Availability Dreamweaver 3. 17 Description This function copies the specified file to a new location. Arguments originalURL, copyURL The originalURL argument, which is expressed as a file:// URL, is the file you want to copy. The copyURL argument, which is expressed as a file:// URL, is the location where you want to save the copied file. Returns A Boolean value: true if the copy succeeds; false otherwise. Example The following code copies a file called myconfig.cfg to myconfig_backup.cfg: var fileURL = "file:///c|/Config/myconfig.cfg"; var newURL ="file:///c|/Config/myconfig_backup.cfg"; DWfile.copy(fileURL, newURL); DWfile.createFolder() Availability Dreamweaver 2. Description This function creates a folder at the specified location. Arguments folderURL The folderURL argument, which is expressed as a file:// URL, is the location of the folder you want to create. Returns A Boolean value: true if the folder is created successfully; false otherwise. 18 The File I/O API Example The following code tries to create a folder called tempFolder at the top level of the C drive and displays an alert box that indicates whether the operation was successful: var folderURL = "file:///c|/tempFolder"; if (DWfile.createFolder(folderURL)){ alert("Created " + folderURL); }else{ alert("Unable to create " + folderURL); } DWfile.exists() Availability Dreamweaver 2. Description This function tests for the existence of the specified file. Arguments fileURL The fileURL argument, which is expressed as a file:// URL, is the requested file. Returns A Boolean value: true if the file exists; false otherwise. Example The following code checks for the mydata.txt file and displays an alert message that tells the user whether the file exists: var fileURL = "file:///c|/temp/mydata.txt"; if (DWfile.exists(fileURL)){ alert(fileURL + " exists!"); }else{ alert(fileURL + " does not exist."); } DWfile.getAttributes() Availability Dreamweaver 2. The File I/O API 19 Description This function gets the attributes of the specified file or folder. Arguments fileURL The fileURL argument, which is expressed as a file:// URL, is the file or folder for which you want to get attributes. Returns A string that represents the attributes of the specified file or folder. If the file or folder does not exist, this function returns a null value. The following characters in the string represent the attributes: R D H S is read only. is folder. is hidden. is system file or folder. Example The following code gets the attributes of the mydata.txt file and displays an alert box if the file is read only: var fileURL = "file:///c|/temp/mydata.txt"; var str = DWfile.getAttributes(fileURL); if (str && (str.indexOf("R") != -1)){ alert(fileURL + " is read only!"); } DWfile.getModificationDate() Availability Dreamweaver 2. Description This function gets the time when the file was last modified. Arguments fileURL The fileURL argument, which is expressed as a file:// URL, is the file for which you are checking the last modified time. 20 The File I/O API