Extending Dreamweaver
Trademarks Add Life to the Web, Afterburner, Aftershock, Andromedia, Allaire, Animation PowerPack, Aria, Attain, Authorware, Authorware Star, Backstage, Bright Tiger, Clustercats, Cold Fusion, Contribute, Design in Motion, Director, Dream Templates, Dreamweaver, Drumbeat 2000, EDJE, EJIPT, Extreme 3D, Fireworks, Flash, Fontographer, FreeHand, Generator, HomeSite, JFusion, JRun, Kawa, Know Your Site, Knowledge Objects, Knowledge Stream, Knowledge Track, LikeMinds, Lingo, Live Effects, MacRecorder Logo and De
CONTENTS CHAPTER 1: Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Background. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing an extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional resources for extension writers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What’s new in Extending Dreamweaver. . . . . .
Changing the default file type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Customizing the interpretation of third-party tags . . . . . . . . . . . . . . . . . . . . . . 34 Working with browser profiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 About browser-profile formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Creating and editing a browser profile . . . . . . . . . . . . . . . . . . . . . . . .
PART II: Extension APIs CHAPTER 6: Insert Bar Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 How object files work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 The Insert bar definition file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Insertbar.xml tag hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Insert bar definition tags. . . . . .
Menu Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Modifying the Commands menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 How menu commands work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 The Menu Commands API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 canAcceptCommand() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
file="command_file_path" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . domRequired="true" or "false" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . enabled="script" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . checked="script". . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . value="script" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CHAPTER 12: Property Inspectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 How Property inspector files work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 The Property inspector API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 canInspectSelection() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 displayHelp() . . . . . . . . . . . . . . . . . . . . . . . . . . . .
deleteServerBehavior() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 displayHelp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 findServerBehaviors() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 inspectServerBehavior() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 pasteServerBehavior() . . . . . . . . . . . . . . . . . . . . .
CHAPTER 16: Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 How data sources work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 The Data Sources API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 addDynamicSource() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 deleteDynamicSource(). . . . . . . . . . . . . . . . . . . . .
CHAPTER 19: Server Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 How customizing server models works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Server Model API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . canRecognizeDocument(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getFileExtensions() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JSObject *JS_NewArrayObject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 long JS_GetArrayLength() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 JSBool JS_GetElement(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 JSBool JS_SetElement() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 JSBool JS_ExecuteScript() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CHAPTER 1 Introduction This book describes the Macromedia Dreamweaver MX 2004 framework and application programming interface (API) that lets you build extensions to Dreamweaver.
Background Most Dreamweaver extensions are written in HTML and JavaScript. This book assumes that you are familiar with Dreamweaver, HTML, XML, and JavaScript programming. If you are implementing C extensions, the book assumes that you know how to create and use C dynamic linked libraries (DLLs). 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.
What’s new in Extending Dreamweaver Dreamweaver MX 2004 includes the following new features and interfaces that are extensible. • New Insert Bar • • • • • The Insert Bar is now divided into separate categories (instead of tabs) for grouping various objects, and also supports pop-up menus. This new grouping and functionality presents a less cluttered user interface. Users can now group their favorite objects into a Favorites category for their own quick reference.
• New and updated examples • • • New examples have been added for the Insert Bar, Components, Data Sources, Flash Integration, and the Shared folder. The examples in the Commands, Menu Commands, Toolbars, and Floating Panels chapters have been updated with graphics and explanations to make them easier to understand. New organization Some material has been reorganized to improve clarity.
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. 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.
Chapter 1: Introduction
Learn the fundamental concepts of the Macromedia Dreamweaver MX 2004 interface and how to customize and extend Dreamweaver to suit your web development needs. These fundamental concepts include the Dreamweaver folders, extension APIs, Dreamweaver interface components, the Dreamweaver Document Object Model (DOM), and Dreamweaver document types. Chapter 2: Extending Dreamweaver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CHAPTER 2 Extending Dreamweaver The following features of Macromedia Dreamweaver MX 2004 let you create extensions: • An HTML parser (also called a renderer), which makes it possible to design user interfaces • • • (UIs) for extensions using form fields, layers, images, and other HTML elements. Dreamweaver has its own HTML parser. A tree of folders that organize and store the files that implement and configure Dreamweaver elements and extensions.
Tag Library and Editor extensions work with the associated tag library files. Tag Library and Editor extensions can modify attributes of existing Tag Dialogs, create new Tag Dialogs, and add tags to the tag library. Tag Library and Editor extension files are stored in the Configuration/ TagLibraries folder. Property Inspector extensions appear in the Property inspector panel.
Code Hints are menus that offer a typing shortcut by displaying a list of strings that potentially complete the string you are typing. If one of the strings in the menu matches the string that you started to type, you can select it to insert it in place of the string that you are typing. Code Hints menus are defined in the codehints.xml file in the Configuration/CodeHints folder, and you can add new code hints menus to it for new tags or functions that you have defined. Menus are defined in the menus.
The Configuration/Shared folder does not correspond to a specific extension type. It is the central repository for utility functions, classes, and images that are used by more than one extension. The files in the Configuration/Shared/Common folder are designed to be useful to a broad range of extensions. These files are useful as examples of JavaScript techniques and as utilities.
Multiuser Configuration folders For the multiuser operating systems of Windows XP, Windows 2000, and Macintosh OS X, Dreamweaver creates a separate Configuration folder for each user in addition to the Dreamweaver Configuration folder. Any time Dreamweaver or a JavaScript extension writes to the Configuration folder, Dreamweaver automatically writes to the user Configuration folder instead.
How Dreamweaver processes JavaScript in extensions Dreamweaver checks the Configuration/extension_name folder during startup.
Displaying Help The displayHelp() function, which is part of several extension APIs, causes Dreamweaver to do the following two things when you include it in your extension: • Add a Help button to the interface. • Call displayHelp() when the user clicks the Help button. You must write the body of the displayHelp() function to display Help. How you code the displayHelp() function determines how your extension displays Help. You can call the dreamweaver.
Now your JavaScript files can refer to these translatable strings by calling the dw.loadString() function, as shown in the following example: function initializeUI() { ... if (problemYhasOccured) { alert(dw.loadString("featureX/subProblemY"); } } You can use slash (/) characters in your string identifiers, but do not use spaces. Using slashes, you can create a hierarchy to suit your needs, and include all the strings in a single XML file.
Customizing Dreamweaver You can customize Dreamweaver in many ways, which lets you work in a manner that’s familiar, comfortable, and efficient for you. This section describes advanced methods for customizing Dreamweaver, with a focus on editing configuration files. About customizing Dreamweaver There are several general approaches to customizing Dreamweaver. Some of these approaches are covered in Dreamweaver Help (Help > Using Dreamweaver). These approaches let you customize your workspace.
For Mac OS X platforms: :Users::Library:Application Support: ¬ Macromedia:Dreamweaver MX 2004:Configuration Note: To install extensions that all users can use in a multiuser operating system, you must be logged in as Administrator (Windows) or root (Mac OS X). Dreamweaver copies only some of the configuration files into your user Configuration folder the first time you run the application. (The files that it copies are specified in the version.xml file in the Configuration folder.
About mm_deleted_files.xml tag syntax The mm_deleted_files.xml file contains a structured list of items that describe configuration files that Dreamweaver is to ignore. These items are described by XML tags, which you can edit in a text editor. The following sections describe the syntax of the mm_deleted_files.xml tags. Optional attributes are marked in the attribute lists with curly braces ({}); all attributes not marked with curly braces are required.
Reinstalling and uninstalling Dreamweaver in a multiuser environment After you install Dreamweaver, if you later reinstall it or upgrade to a later version, Dreamweaver automatically makes backup copies of existing user configuration files, so that if you’ve customized those files, you can still access the changes you made. When you uninstall Dreamweaver from a multiuser system (which you can do only if you have administrative privileges), Dreamweaver can remove each user Configuration folder for you.
To change the appearance of a dialog box: 1 In Dreamweaver, select Edit > Preferences, and then select the Code Rewriting category. 2 Unselect the Rename Form Items when Pasting option. 3 4 5 6 7 8 9 Unselecting this option ensures that form items retain their original names when you copy and paste them. Click OK to close the Preferences dialog box. On your disk, find the appropriate HTM file in the Configuration/Objects, Configuration/ Commands, or Configuration/Behaviors folders.
To add new file types to the menu in the File > Open dialog box: 1 Make a backup copy of the Extensions.txt file in the Configuration folder. 2 Open Extensions.txt in Dreamweaver or a text editor. 3 Add a new line for each new file type. In capital letters, enter the filename extensions that the new file type can have, separated by commas; then add a colon and a brief descriptive phrase to show in the pop-up menu for file types that appears in the File > Open dialog box.
You can define two kinds of tags using tagspec: normal HTML-style tags and string-delimited tags. String-delimited tags start with one string and end with another string; they’re like empty HTML tags (such as img) in that they don’t surround content and don’t have closing tags. The happy tag example is a normal HTML-style tag; it starts with an opening tag, contains data between opening and closing tags, and ends with a closing tag.
• • • • • • • • 36 describes what kinds of content the tag can contain and where in an HTML file the tag can appear. Valid values are "block_model", "head_model", "marker_model", and "script_model": ■ block_model specifies that the tag can contain block-level elements such as div and p, and that the tag can appear only in the body section or inside other body-content tags such as div, layer, or td.
• • • equivalent_tag specifies simple HTML equivalents for certain ColdFusion form-related tags. Not intended for use with other tags. is_visual indicates whether the tag has a direct visual effect on the page. For example, the ColdFusion tag cfgraph doesn’t specify a value for is_visual (so the value defaults to "true"); the ColdFusion tag cfset is specified as having is_visual set to "false".
To change the highlighting color of third-party tags: 1 Select Edit > Preferences, and select the Highlighting category. 2 Click the Third-Party Tags color box to display the color picker. 3 Select a color, and click OK to close the Preferences dialog box. For information about selecting a color, see Dreamweaver Help (Help > Using Dreamweaver). Avoiding rewriting third-party tags Dreamweaver corrects certain kinds of errors in HTML code; for details, see Dreamweaver Help (Help > Using Dreamweaver).
To turn off Dreamweaver encoding options: 1 Select Edit > Preferences, and select the Code Rewriting category. 2 Deselect either or both Special Characters options. For information on the other Code Rewriting preferences, see Dreamweaver Help (Help > Using Dreamweaver). Working with browser profiles Browser profiles are the files Dreamweaver uses to check your documents when you run a target browser check (see Dreamweaver Help [Help > Using Dreamweaver]).
The following example shows the syntax for a tag entry:
Creating and editing a browser profile You can create a browser profile by modifying an existing profile. For example, to create a profile for a future version of Microsoft Internet Explorer, you can open the profile for the most recent version of Internet Explorer that has a profile, add any new tags or attributes introduced in the new version, and save it as a profile for the new version.
Changing FTP mappings The FTPExtensionMap.txt file (Windows) and the FTPExtensionMapMac.txt file (Macintosh) map filename extensions to FTP transfer modes (ASCII or BINARY). Each line in each of the two files includes a filename extension (such as GIF) and either the word ASCII or the word BINARY, to indicate which of the two FTP transfer modes should be used when transferring a file with that extension.
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 Previous server model CSS Text css Java Text java JavaScript Text js VB Text vb VBScript Text vbs Text Text txt EDML XML edml TLD XML tld VTML XML vtm, vtml WML XML wml XML XML xml 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 a custom definition file to the Configuration/DocumentTypes folder.
In the previous example, the loadstring element identifies the localized strings that Dreamweaver should use for the title and description for ASP-JS type documents. For more information about localized strings, see “Localized strings” on page 50. 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.
Element Type Tag Attribute Required Description internaltype Yes A broad classification of how Dreamweaver treats a file. The internaltype identifies whether the Design view is enabled for this document and handles special cases such as Dreamweaver templates or extensions.
Element Type Tag Attribute Required Description macfileextension Yes The file extension that is associated with the document type on the Macintosh. You specify multiple file extensions by using a commaseparated list. The first extension in the list is the extension that Dreamweaver uses when the user saves a documenttype document. 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 starts, 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 and file types By default, Dreamweaver shows all the file types it recognizes in the File > Open dialog box. After creating a new document type, extension developers need to update the appropriate Extensions.txt file. If the user is on a multiuser system (such as Windows XP, Windows 2000, or Mac OS X), the user has another Extensions.txt file in their Configuration folder. The user must update the Extensions.txt file because it is the instance that Dreamweaver looks for and parses.
To change the Dreamweaver default File > 0pen file type: 1 Make a backup copy of the Extensions.txt file in the Configuration folder. 2 Open Extensions.txt in Dreamweaver or a text editor. 3 Cut the line that corresponds to the new default, and paste it at the beginning of the file, to make it the first line of the file. 4 Save the Extensions.txt file. 5 Restart Dreamweaver. To see the changes, select File > Open and click the pop-up menu of file types.
Note: String identifiers, such as myJSPDocType/Description in the previous example, must be unique within the application. Dreamweaver, when it starts, parses all XML files within the Configuration/Strings folder and loads these unique strings. Rules for document type definition files Dreamweaver lets document types that are associated with a server model share file extensions. For example: ASP-JS and ASP-VB can claim .asp as their file extension.
Chapter 2: Extending Dreamweaver
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 on the Macromedia Exchange website (www.macromedia.com/exchange).
Consider the following basic guidelines when 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.
The following examples show the Base Property inspector without the DOCTYPE statement, which improves form-control rendering, and then with the DOCTYPE statement. 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).
As with normal (noneditable) select lists, editable select lists have a selectedIndex property (see “Objects, properties, and methods of the Dreamweaver DOM” on page 68). This property returns -1 if the text box is selected. To read the value of an active editable text box into an extension, read the value of the editText property.
| Editable DropDown without default text: | |