| Property inspectors that are coded as extensions share the following API structure and functional procedure. Property Inspectors in the Configuration Folder In the Configuration folder, Property inspector extensions live in the Inspectors folder. All inspectors are at the root level of this folder; there are no subfolders . Figure 6.1 shows the default Inspectors folder, with only Macromedia's standard inspectors showing. Note that Property inspectors and objects often go together, so if you have used the Extension Manager to add objects to your copy of Dreamweaver, you may see extra items in this folder. Figure 6.1. The Configuration/Inspectors folder, as it appears in its default state (no third-party extensions added).  Property Inspector Files Each Property inspector is created from one, two, or three files in the Inspectors folder. These files are discussed in the following sections. HTML File (Required) As usual, the HTML file is the inspector file itself. Without this file, there is no inspector. The filename will never be seen by the user , but it can be important in determining priority. (Dreamweaver sometimes uses alphabetical sorting of names to determine which inspector to use in a given situation. This is discussed in more detail in the later section "The API Procedure for Property Inspectors.") JavaScript File (Optional) Again as usual, the JavaScript portion of the inspector can be saved in the HTML file, or it can be saved separately in a linked JS file. It's customary, though not required, to match this file's name with the filename of the HTML file (for example, My Inspector.htm and My Inspector.js). GIF File (Optional, but Usually Present) This file contains a 36x36-pixel icon to be used in the upper-left corner of the inspector, to identify the object being inspected. Figure 6.2 shows some sample icons. The icon isn't required, but it is important for good user interface design. The Macromedia standard icons all have a "depressed button" frame and a transparent background, so they blend in well with the inspector. It's customary, though not required, to match this file's name with the filename of the main object file. Figure 6.2. Some GIF icons from the Macromedia standard Property inspectors.  Other Image Files Depending on the complexity of your Property inspector's layout, you may want to use additional images to enhance it. You can use your own custom images, or take advantage of the handy image files already stored in the Inspectors folder or in the Configuration/Shared/MM/Images folder. The Structure of an Inspector File At their simplest, inspector files are indeed simple, with few required elements. At their fanciest, they can get pretty detailed. Required Elements Each Property inspector file requires at least these elements: -
Opening line/comment. The first line of every inspector file above the <HTML> tag must be a comment in this format: <! tag: tagNameOrKeyword ,priority: 1-10 ,selection: exactOrWithin ,hline,vline > Without this line, Dreamweaver won't recognize the file as an inspector. The values entered into the comment refer to the following: -
tagNameOrKeyword (required). This is the tag to be inspected, or one of the following keywords: *COMMENT* (for comments), *LOCKED* (for locked regions ), *ASP* (for ASP tags). -
110 (required). This rates the priority Dreamweaver should give the inspector ( 1 is lowest ; 10 is highest). Any time Dreamweaver has a choice between using two or more inspectors to inspect a user selection, the higher-priority inspector wins. (You can use this to force the program to override its own built-in inspectors.) -
exactOrWithin (required). This indicates whether the user's selection must exactly contain the tag named above ( exact ), or whether it can be within that tag ( within ). -
hline (optional). If this parameter is present, a gray horizontal line is used to divide the upper and lower halves of the expanded Property inspector. -
vline (optional). If this parameter is present, a gray vertical line is used to divide the tag name field from the rest of the properties in the inspector. This line is used as a visual cue for the user, in order to organize the interface clearly. Here are some sample opening tags for inspectors: <!tag:LINK,priority:5,selection:within,vline,hline> (from "link.htm") <!tag:META,priority:6,selection:within> (from "keywords.htm") <!tag:*LOCKED*,priority:5,selection:within,vline,hline> (from "date.htm") -
canInspectSelection() function. This function returns true or false , determining whether the inspector is appropriate for the current user selection. This is usually done by using the dom.getSelectedNode() function to access the currently selected object, and comparing that to the allowable tags for this inspector. This function is part of the API, and is called automatically. A simple example of this function is found in title.js (one of the more straightforward inspector files): function canInspectSelection(){ var titleObj = getSelectedObj(); //accept if the selected node is text or if it is the title tag return (titleObj.nodeType==Node.TEXT_NODE (titleObj.nodeType=Node.ELEMENT_NODE && titleObj.tagName=="TITLE")); } -
Body/Form Elements. The content in the <body> tag becomes the interface for the inspectorit's what will show up in the Property inspector floating panel. In order for the inspector to process user input and display values, the <body> must contain a <form> and form elements, as well. -
Event Handlers. The inspectSelection() function allows the inspector to display only the current settings for the selection. If the inspector is to process user input, changing the document as the user enters changes into the inspector, each form field must have an event handler that calls a local function. The <title> Property inspector, for instance, includes one text input field, which calls a local function, onBlur : <input type="text" name="Title" size="57" onBlur="setTitleTag()"> After the user has typed in a title and left the input field, the setTitleTag() function then changes the innerHTML property of the <title> tag: function setTitleTag(){ var titleObj = getSelectedObj(); //while an element node (the title one) is not selected while (titleObj.nodeType!=Node.ELEMENT_NODE ) titleObj=titleObj.parentNode; //traverse up the tree if (titleObj.innerHTML != findObject("Title").value){ titleObj.innerHTML = findObject("Title").value; } } Listing 6.1 shows the HTML code for a very simple Property inspector. Listing 6.1 Framework Code for a Basic Property Inspector, Containing Required Elements Only <! tag:MYTAG,priority:10,selection:within,hline > <html> <head> <title>MYTAG Inspector</title> <script language="JavaScript"> function canInspectSelection() { return true; } </script> </head> <body> This is the body. </body> </html> Semi-Required Element If you want your Property inspector to collect and display any values from the user's selection, one more element is required: -
inspectSelection() function. This function populates the input fields of the Property inspector form based on an inspection of the current selection. Dreamweaver automatically feeds one argument into the function: max (if the Property inspector is in its expanded state, with both halves visible, when the inspector is called) or min (if the Property inspector is abbreviated, with only the top half visible). This function is part of the API, and is called automatically. Most examples of this function are fairly extensive because this is one-half of the functionality of the inspector. One of the simplest examples is from title.js, for creating the <title> inspector: function inspectSelection(){ var titleObj = getSelectedObj(); while (titleObj.nodeType!=Node.ELEMENT_NODE ) //while an element node (the title one) is not selected titleObj=titleObj.parentNode; //traverse up the tree findObject("Title").value = titleObj.innerHTML showHideTranslated(); } note The preceding code calls the findObject() function, a handy utility function for use with inspectors. It's found in the shared file _pi_common.js , and is discussed in more detail later in this chapter.
A few Property inspectors, howeverthe Date inspector, for instancedon't display attribute information about the selected object and therefore don't use the inspectSelection() function. They still work as inspectorsthat is, they show up when the specified page element is selected and they present functional form elementswithout the inspectSelection() function. Optional Elements An inspector with only the preceding elements will function just fine, but it will probably be fairly crude to look at. Consequently, most inspectors use at least some of these optional elements to dress themselves up: note Why use layers ? You may decide not to. Their presence certainly complicates the HTML and JavaScript coding for your inspector. Layers are covered in this chapter as a way of introducing you to these special requirements, and because they are commonly used in inspectors.
-
Layers. All the Macromedia standard inspectors, and probably all inspectors you will download from the Exchange as well, use CSS layers to define the layout of the form elements. Either the <div> or <span> tag can be used for these layers. Figure 6.3 shows a standard Property inspector as it appears in the Dreamweaver interface and as its file appears in the Dreamweaver design and code views. Figure 6.3. The Link Property inspector, shown as a functioning part of the Dreamweaver interface and as a document in the Dreamweaver Design/Code view.  -
findObject() function ( _pi_common.js ). Of course, if the inspector includes form elements that are in layers, the <form> tag ceases functioning, so user input must be collected in some other way. The findObject() function allows scripts to access named form elements as objects rather than as form elements, and collect their values for processing in scripts. For instance, this code myVariable = document.myForm.userchoice.value can be re-coded as myVariable = findObject("userchoice").value Any Property inspector that uses layers to control its layout almost certainly uses findObject() to process form elements. The findObject() function is not part of the API. Rather, it's a local function defined in the _pi_common.js file, which is located in the Configuration/ Inspectors folder. To use this function, the inspector file must link to _pi_common.js . -
Icons and other images. We've already discussed the GIF icon file. Using it isn't required, but it is recommended for good interface design. Use other images as well, if your interface calls for them. To include an image in your inspector, save the image file in the Inspectors folder, and link to it using a relative URL. To keep your inspector's visual interface compact and efficient, don't use images larger than about 36x36. The API Procedure for Property Inspectors The procedure for inspectors begins when the user makes a selection or moves the insertion point in a document. Every time this happens, the following events occur: -
Dreamweaver looks through the valid inspector files for any file with a selection type of within . -
If there are any within inspectors, Dreamweaver starts from the current selection and searches up the document hierarchy, comparing tags in the user document to the tag parameter in the within inspector file until it finds a tag surrounding the selection that has an inspector associated with it. -
If there are no within inspectors, Dreamweaver looks for an inspector file with a selection type of exact . -
After Dreamweaver finds a match between tag and inspector, it calls the canInspectSelection() function. If this function returns false , the inspector is no longer considered . If only one inspector returns true , Dreamweaver moves on to the next step. If, however, more than one potential inspector returns true , the following occurs: -
Dreamweaver compares the priority values for each candidate. The inspector with the highest priority rating (10 is highest) is chosen . -
If the priority ratings are equal, Dreamweaver chooses an inspector alphabetically by filename. -
After an inspector file has been chosen, its <body> content appears in the Property inspector floating panel. If a displayHelp() function is defined, the "?" icon is displayed in the panel's upper-right corner. Dreamweaver calls the inspectSelection() function to populate the input fields of the form. -
From this point on, event handlers attached to individual input fields in the inspector form call local functions that edit the document in response to user input. Figure 6.4 shows a diagram of this procedure. Figure 6.4. The API procedure for Property inspectors.   |
