Dreamweaver MX Extensions
| Each Dreamweaver object is created from two or three files stored in one of the subfolders in the Configuration/Objects folder. Exactly where and how the object will appear in the Dreamweaver interface is determined by two XML configuration files: insertbar.xml (in Configuration/Objects) determines the object's placement in the Insert bar; and menus.xml (in Configuration/ Menus ) determines its placement in the Insert menu. Object Files in the Configuration Folder
If you open the Configuration/Objects folder, you'll see that object files are not stored directly inside this folder; instead, they're stored in various subfolders. The subfolder names are probably familiar to you because most of them match the names of the categories in the Insert bar: Common, Forms, Frames, Head, and so on (see Figure 2.1). Figure 2.1. The Objects folder and its subdirectories.
Within the Configuration folder, if you open one of the subfolders (such as Common, for instance) and examine its contents, you'll see that each object that normally appears in that category of the Insert bar is represented by two or three files. These files, taken together, form the object. The files that make up each object are:
note If you've already customized your copy of Dreamweaver by using the Extensions Manager, you may have more subfolders in your Objects folder than those shown in Figure 2.1.
Figure 2.2 shows the files that constitute two typical Dreamweaver objects. Figure 2.2. The Date object (top) consists of two files. The more complex E-Mail Link object (bottom) consists of three files.
Objects in the Insert bar (insertbar.xml)
The insertbar.xml file, located in the Configuration/Objects folder, controls the appearance and functionality of the Insert bar. If you open this XML file in a text editor, you'll see that it contains a <category> tag for each tab, or category, of the Insert bar, and a <button/> tag for each object within a category. A typical entry looks like this: <category id="DW_Insertbar_Common" folder="Common"> <button id="DW_Hyperlink" image="Common\Hyperlink.gif" enabled="" showIf="" file="Common\Hyperlink.htm"/> ... </category> As this example shows, each category is identified with a certain folder within the Objects folderin this case the Common folder. Each button is linked to a specific object file and image. Objects in the Insert Menu
By default, the Insert menu contains an item for every object file within the Objects folder, with item names determined by the object filename (minus its .htm or .html extension) and the order of items determined alphabetically . The menus.xml file, however, located in the Configuration/Menus folder, can be used to override these defaults (changing names, controlling the order of entries, creating submenus). (See Chapter 5, "Creating Custom Commands and Menu Commands," for a more in-depth discussion of working with menus.xml.) Structure of an Object File
Like anything else in life, Dreamweaver objects can be simple or they can be complex. Simple objects just insert codethe same code, every time, without allowing for user customization. Fancier, more full-featured objects include such niceties as help screens, context-sensitivity, and dialog boxes that allow users to customize what code the object inserts . Simple Object Files
At its simplest, an object file must contain the basic framework for an HTML page and should include a recognizable filename, a <title> tag containing a recognizable object title, and an objectTag() function. Let's take a moment to look at these individual requirements. Recognizable Filename
As mentioned in the previous section, by default the filename appears in the Insert menu to represent the object, so in creating your own objects it's a good idea to take advantage of the Dreamweaver program's flexible approach to filenames to make your object's entry in the Insert menu as easily understood as possible. "Copyright Statement" makes a much better menu item than "copy_st", don't you think? The filename's capitalization will also be carried into the menu item, so capitalize nicely . Title
The information in the object file's <title> tag becomes the ToolTip that appears when the user hovers over the object in the Insert bar. It's standard practice, although not required, to use the object's name for the title. objectTag() function
The code that makes the object actually workin other words, the code that tells Dreamweaver what HTML to insert in the user's document when the object is chosenis the objectTag() function. This function can exist inside a <script> tag in the object file's <head> , or it can exist in a JS file linked to the object file. This function needn't be explicitly called (Dreamweaver will do this automatically). It should include a return statement that contains the HTML you want the object to insert. A good objectTag() function might look like any of these: function objectTag() { return "Copyright John Smith, 2001."; } function objectTag() { return '<font face="Arial, Helvetica, sans-serif" size="1">Copyright John Smith, 2001</font>'; } function objectTag() { var username = "John Smith"; return "Copyright " + username + ", 2001."; } Listing 2.1 shows the code for a very simple object file. The object shown will insert the text "This is my simple object" into the user's document. Listing 2.1 Code for a Very Simple Object File
<html> <head> <title>My Simple Object</title> <script language="JavaScript"> function objectTag() { return "My object inserted this text."; } </script> </head> <body> </body> </html>
note It is possible to create simpler objects than this without any scripting. Any file residing in the correct place in the Objects folder, and containing only a code snippet with no HTML framework, can be used as an object. When Dreamweaver encounters a file like this, it simply inserts the file's contents into the user's document. This kind of file does not offer much flexibility, though, and the object created by this file is not a full-featured object. This book covers only standard scripted objects.
Full-Featured Object Files
Fancier object files can include all sorts of additional elements, building on the basic framework shown in Listing 2.1. Form
If an object file contains a <form> tag in its <body> section, Dreamweaver displays a dialog box when the object is inserted. The contents of the form become the contents of the dialog box. Any information collected by the form can be processed by the objectTag() function and built into its return statementwhich is how user-customized objects are created. The form shouldn't include OK or Cancel buttons because Dreamweaver adds these automatically. A plain and simple form will work fine: <form name="myForm"> Enter your name: <input type="text" name="username"> </form> However, using a table for layout will create a nicer looking form (and is recommended by Macromedia): <form name="myForm"> <table border="0"> <tr align="baseline"> <td align="right">Enter your name:</td> <td align="left"><input type="text" name="username"></td> </tr> </table> </form>
note Macromedia has created a full set of User Interface Guidelines for extensions. See Appendix C, "Packaging Extensions for Use with the Extension Manager," for more about these guidelines.
If you want your object to call up a dialog box that provides information about your object, but don't need to ask for user input, you can even omit input fields altogetherbut you still need the <form> tag: <form name="myForm"> This object will insert a copyright statement for John Smith, 2001. The text will appear in a small, sans-serif typeface. </form> displayHelp() function
If an object that calls up a dialog box also includes a displayHelp() function in its <head> section (or in a linked JS file), Dreamweaver adds a Help button to the dialog box. This function is called when the user clicks on the Help button. The displayHelp() function can contain instructions for opening an alert window that contains brief help information, launching a browser and going online to display a remote HTML page, or launching the user's OS help application to display a locally stored help page. The code for displayHelp() might look like any of the following: function displayHelp() { window.alert("How much help can you put in an alert window, anyway?"); } function displayHelp() { dw.browseDocument("http://www.mywebdomain.com/dreamweaverhelp/copyright.html"); } function displayHelp() { var myURL = dw.getConfigurationPath(); myURL += "/Shared/MySharedFiles/CopyrightHelp.html"; dw.browseDocument(myURL); } Building and displaying help pages is covered in more detail in Chapters 5 and 6. isDomRequired() function
The isDomRequired() function determines whether Code view and Design view need to be synchronized before the new object's code can be inserted. Dreamweaver calls it automatically, so it needn't be called in the object file. It should return true or false . If it's not present, Dreamweaver assumes Code view and Design view don't need to by synchronizedso the only reason to include it, really, is if you want it to return true . Local Functions
In addition to the standard functions already listed, which are part of the object API, you can add any other functions you want to further refine your object. The Macromedia documentation refers to these as local functions. Common uses for local functions include initializing the dialog box and adding special functionality to individual form input elements. Local functions must be explicitly called, usually by adding an onLoad() event handler to the object file's <body> tag, or adding onChange() or onBlur() handlers to <input> tags. Listing 2.2 shows a more full-featured object file.
note See Appendix A, "JavaScript Primer," for more information on calling functions from form elements.
Listing 2.2 A More Full-Featured Object File
<html> <head> <title>My Fancier Object</title> <script language="JavaScript"> function objectTag() { var myName=document.myForm.username.value; return "This document was created by "+myName+"."; } function isDomRequired() { return true; } function displayHelp() { window.alert("This is a brief help statement for my object."); } function initializeUI() { document.myForm.username.focus(); document.myForm.username.select(); } </script> </head> <body onLoad="initializeUI()"> <form name="myForm"> <table> <tr valign="baseline"> <td align="right" nowrap>Your name:</td> <td align="left"><input type="text" name="username"></td> </tr> </table> </form> </body> </html> The API Procedure for Objects
Not only does the object API specify certain functions, but it also determines the procedure that Dreamweaver will use to process the object. Every time a user clicks an icon in the Insert bar or chooses an object from the Insert menu, Dreamweaver executes a sequence of events that form the API procedure for this type of extension. The main events in this procedure are as follows :
Figure 2.3 shows a flowchart diagramming this process. Figure 2.3. The API process for objects.
note The Extending Dreamweaver manual mentions one other automatically called API function, the windowDimensions() function. This optional function can be used any time you ask Dreamweaver to display a dialog box; its purpose is to specify dimensions for the dialog box. If it isn't present, Dreamweaver will size the dialog box automatically based on its contents. Macromedia doesn't recommend using the windowDimensions() function, however, unless the contents are so extensive that they would otherwise result in the dialog box being automatically sized larger than 640x480 pixels. Because that's hardly ever the case, I haven't included it in the samples or discussion here. For more information, see the Extending Dreamweaver manual.
|