How Objects Are Constructed | 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.

graphics/02fig01.gif

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.

HTML file (required). This is the main object file. Without it, there is no object! The <head> section of the file may contain JavaScript functions for constructing and inserting the object code, or it may contain a link to an external JS file that contains those functions. If the object includes a dialog box for user input, the dialog box will be created as an HTML form in the <body> section of the file. As an HTML file, the filename must have an extension of .htm or .html (either will work, although Macromedia extensions all use .htm). Unlike files intended for use on Web servers, the filename may include spaces or special characters for easier reading.
JS file (optional). The JavaScript functions for constructing the object code may be placed in this separate file instead of embedding them in the <head> section of the main object file (the HTML file). For easier access during editing and updating, Macromedia recommends creating separate JS files for all but the simplest objects. It's customary, although not required, to match this file's name with the filename of the HTML file.
GIF file (optional). This file contains an 18x18-pixel GIF image that will be displayed in the Insert bar to represent the object. This file isn't required for an object to function; if it isn't present, Dreamweaver will use the object's name to represent it in the Insert bar. The filename must include the .gif extension. It's customary to match this file's name with the filename of the HTML file.

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.

graphics/02fig02.gif

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 :

Dreamweaver scans the object file (the HTML file) for a <form> tag.
- If it finds a <form> tag, it displays the form as a dialog box with OK and Cancel buttons, and waits for the user to enter information and click OK. If it finds a displayHelp() function in the object file, it adds a Help button to the dialog box. If any functions are called from the <body> tag using the onLoad event handler, they're executed before the form is loaded. If any functions are called from event handlers (such as onChange or onBlur ) added to form elements, they're executed as those events occuras the user changes text in a text field, chooses from a popup menu, and so forth.
- If there isn't a <form> tag, it moves on to the next step.
Dreamweaver scans the <head> section of the object file for an objectTag() function and executes it. Whatever code the objectTag() function returns is inserted into the user's document at the insertion point.

Figure 2.3 shows a flowchart diagramming this process.

Figure 2.3. The API process for objects.

graphics/02fig03.gif

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.