Extending Dreamweaver MX ™ macromedia ®
Trademarks Afterburner, AppletAce, Attain, Attain Enterprise Learning System, Attain Essentials, Attain Objects for Dreamweaver, Authorware, Authorware Attain, Authorware Interactive Studio, Authorware Star, Authorware Synergy, Backstage, Backstage Designer, Backstage Desktop Studio, Backstage Enterprise Studio, Backstage Internet Studio, Design in Motion, Director, Director Multimedia Studio, Doc Around the Clock, Dreamweaver, Dreamweaver Attain, Drumbeat, Drumbeat 2000, Extreme 3D, Fireworks, Flash, Fonto
CONTENTS Part I Overview CHAPTER 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Customizing or extending? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing an extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional resources available to extension writers . . . . . . . . . . . . . . . . . . . . . . . . . . .
Part II Extension APIs CHAPTER 5 Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 How object files work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Defining the Insert bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Insert bar definition tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CHAPTER 12 Floating Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 How floating panel files work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 The Floating panel API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 CHAPTER 13 Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CHAPTER 20 JavaScript Debugger Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 How the JavaScript Debugger module works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 The JavaScript Debugger module API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 CHAPTER 21 C-Level Extensibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CHAPTER 29 The JavaBeans API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 CHAPTER 30 The Source Control Integration API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 Integration with Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding source control system functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Report Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 Results window functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 Selection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546 Server behavior functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Orient yourself to concepts fundamental to writing Dreamweaver extensions These concepts include understanding available API categories, creating new document types, working effectively with the Dreamweaver user interface, and understanding the Dreamweaver Document Object Model (DOM).
CHAPTER 1 Introduction This book contains descriptions of the tools that are available for developers to extend Dreamweaver using Dreamweaver application programming interfaces (APIs) and provides basic information about their use. It assumes that you are familiar with Dreamweaver, HTML and XML markup, and JavaScript programming. For users who are implementing C extensions, the book assumes that you know how to create and use C dynamic linked libraries (DLLs).
4 Save the extension package in the Dreamweaver MX\Downloaded Extensions folder of your installed Dreamweaver folder. 5 In the Extension Manager, select File > Install Extension. In Dreamweaver, select Commands > Manage Extensions to launch the Extension Manager. The Extension Manager automatically installs the extension from the Downloaded Extension folder into Dreamweaver. Some extensions need Dreamweaver to restart before you can use them.
What’s new in Extending Dreamweaver MX Dreamweaver MX includes the following new features and interfaces that you can access to develop extensions for the product: • • • • • • • An enhanced user interface Multiple user configurations Enhanced code editing Expanded document type support Enhanced server model extensibility Improved database connection handling Enhanced external application integration The following sections describe how you can use these features and interfaces to extend Dreamweaver MX.
Importing/exporting sites You can programmatically export a Dreamweaver MX site to an XML file, which can then be imported by any Dreamweaver instance on any computer. This feature lets users share sites and move them among host computers. For more information on importing and exporting sites, see “Site functions” on page 558. Resource cloaking In Dreamweaver MX, you can hide from view (cloak) selected files and folders.
New document types Extensible document types Dreamweaver MX lets you create new document types, including types that have file extensions that are identical to those of built-in Dreamweaver document types (such as .asp, which is associated with the default ASP-JS document type).
Enhanced database exploration Dreamweaver MX enhances database exploration in the following ways. • For ColdFusion, you have the option of accessing the RDS server using ColdFusion data sources. • When working with connection dialog boxes you can create new types of connections and let users duplicate or edit an existing connection.
CHAPTER 2 Extending Dreamweaver MX Most Dreamweaver extensions are written in HTML and JavaScript.
Extension APIs The extension APIs provide the framework that you use to add functionality to Dreamweaver. You write the bodies of the functions as described in these APIs, and you specify the return values as required. After writing an extension, you must save it to the correct folder for it to work properly. The Extension Manager facilitates the process of saving extensions correctly.
You can use the files that come with the product within the Configuration folder as examples, but these files are generally more complex than the average extension that is available on the Macromedia Exchange website. For more information on the contents of each subfolder within the Configuration folder, view the Configuration_ReadMe.htm file. One folder within the Configuration folder does not correspond to a specific extension type.
Types of extension APIs in Dreamweaver The following list describes the types of extension APIs that are documented in this guide: extensions create changes in the Insert bar. An object is typically used to automate the inserting code into a document. It can also contain a form that gathers input from the user and JavaScript that processes the input. Object files are stored in the Configuration/Objects folder. Object extensions can perform almost any specific task, with or without input from the user.
Data Translator extensions convert non-HTML code into HTML that appears in the Design view of the Document window. These extensions also lock the non-HTML code to prevent it from being parsed by Dreamweaver. Translator files are stored in the Configuration/Translators folder. extensions let you build a connection to a custom data source. Data source extensions appear in the plus (+) menu of the Bindings panel. Data source files are stored in the Configuration/Data Sources folder.
For all extensions, Dreamweaver executes code in other event handlers (for example, onBlur="alert(’This is a required field.’)") when the user interacts with the form fields to which they are attached. Dreamweaver MX supports the use of links within extensions. Event handlers in links must use syntax as shown in the following example: link text Plug-ins (set to play at all times) are supported in the BODY of extensions. The document.
Document type definition file The central component of extensible document types is the document type definition file. There might be several definition files, all of which are located in the Configuration/DocumentTypes folder. Each definition file contains information about at least one document type. For each document type, essential information such as server model, color coding style, descriptions, and so forth, is described.
Document Type Server Model Internal Type File Extensions Text Text txt EDML XML edml TLD XML tld VTML XML vtm, vtml WML XML wml XML XML xml Previous Server Model If you need to create a new document type, you can either add your entry to the document definition file that Macromedia provides (MMDocumentTypes.xml) or add your own definition file to the Configuration/DocumentTypes folder. Note: The NewDocuments subfolder resides in the Configuration/DocumentTypes folder.
The following table describes the tags and attributes that you can use within a document type definition file. Element Type Tag Attribute Required Description Yes Parent node id Yes Unique identifier across all document type definition files. servermodel No Specify the associated server model (case sensitive); by default, these are the valid values: ASP.NET C# ASP.
Element Type Tag Attribute Required Description winfileextension Yes The file extension that is associated with the document type on Windows. You specify multiple file extensions by using a comma-separated list. The first extension in the list is the extension that Dreamweaver MX uses when the user saves a document of type documenttype. If two nonserver model-associated document types have the same file extension, Dreamweaver recognizes the first one as the document type for the extension.
When Dreamweaver MX launches, it reads all document type definition files and builds a list of valid document types. Dreamweaver treats any entries within the definition files that have nonexistent server models as nonserver model document types. Dreamweaver ignores entries that have bad contents or IDs that are not unique.
Document extensions After creating a new document type, extension developers need to update the appropriate Extensions.txt file. If the user is on a system that supports multiple users (such as Windows XP, Windows 2000, or Mac OS X), the user has another Extensions.txt file in their Configuration folder. This Extensions.txt file is the one that the user needs to update because this file is the instance that Dreamweaver looks for and parses.
To provide localized strings, perform the following steps: 1 Place the following statement at the top of the document type definition file: 2 Declare the MMString name space in the tag: PAGE 30Opening a document in Dreamweaver When a user opens a file, Dreamweaver MX follows a series of steps to identify the document type based on the file’s extension. If Dreamweaver successfully finds a unique document type, Dreamweaver uses that type and loads the associated server model (if any) for the document that the user is opening. If the user has selected to use Dreamweaver UltraDev 4 server behaviors, Dreamweaver MX loads the appropriate UltraDev 4 server model.
CHAPTER 3 User Interfaces for Extensions Most extensions are built to receive information from the user through a user interface (UI). If you plan to submit your extension for Macromedia certification, you need to follow the guidelines that are available within the Extension Manager files (http://www.macromedia.com/ exchange/).
Consider the following basic guidelines as you design an extension UI: • If you want a name for your extension, place the name in the Title Tag of your HTML file. Dreamweaver displays the name in the Extension title bar. • Keep text labels on the left side of your UI, aligned right, with text boxes on the right side, aligned left. This arrangement lets the user’s eyes easily locate the beginning of any text box. Minimal text can follow the text box as explanation or units of measure.
In addition to letting you make extension UIs more closely match the built-in dialog boxes and panels, the new DOCTYPE statements also let you view your extensions in the Dreamweaver Design view as they appear when viewed by users. The Base Property inspector as it appears in Design view without the DOCTYPE statement. The Base Property inspector as it appears in Design view with the DOCTYPE statement (and after a few adjustments to accommodate the new rendering).
The following example illustrates the settings for an editable select list: When you use select lists in your extensions, you can check for the presence and value of the editable attribute.
The following example creates a command that contains an editable select list using common JavaScript functions:
Editable Dropdown Test
