Workshop 1: A Simple Property Inspector

Workshop #1: A Simple Property Inspector

If you understood everything in the practice session, you should be able to finish this workshop exercise with no difficulty. You'll be creating an inspector for a tag that always uses the same number of attributes, and has no competition from the Dreamweaver default inspectors.

Sample Inspector: Netscape Block Spacer

You created the block spacer object in Workshop #2 in Chapter 2, "Creating Custom Objects." Remember? You may have noticed, if you've ever tried using this object, that there's no way to inspect or edit it except by using the source code. That's because there's no inspector! Creating a fully functional object often involves creating an inspector to go with it.

note

Before you can inspect a Netscape block spacer, you will need to insert one. If you didn't create the spacer object back in Chapter 2, you can download the finished object file from the companion web site. (See Appendix F for more information about the web site.)

Task 1: Create the basic inspector file

If you went through the preceding practice exercise, you already have a framework file to start fromthe mood inspector file. If not, you have to create a file from scratch as you go.

note

To make the mood inspector more flexible as a template file, you might want to strip out all mood-specific code and save the gutted file as a template.

Duplicate the mood.htm file, or create a new text file containing the HTML framework from Listing 6.2. Save it in the Inspectors folder as Block Spacer.htm .

This is the same name you gave the object file back in Chapter 2. The names don't need to match, but using similar names for corresponding files makes it easier to keep track of files later. This is the way many of the standard extension files are named.
Change the opening comment to reflect the new tag being inspected, like this (new code is in bold):
```
 <! tag:  SPACER  ,priority:10,selection:within,hline > 
```
Change the document's <title> to reflect the new tag's identify. Like this:
```
 <title>  Block Spacer Inspector  </title> 
```

Task 2: Create the new layout and form

How you revise the inspector's layout depends on whether you're working in your text editor or in Dreamweaver Design view.

If you're coding your inspector by hand, change the <body> tag of the file to look like this (new code is in bold):

 <body>  <div id="iconLayer" style="position:absolute; left:3; top:2; width:40px;  height:40px; z-index:1"><img src="  blockspacer.gif  " width="36"  height="36"></div>  <div id="nameLayer" style="position:absolute; left:44px; top:4px;  width:75px; height:50px; z-index:2">  Spacer  </div>  <div id="widthLayer" style="position:absolute; left:128px; top:0px;   width:134px; height:40px; z-index:3">   <table>   <tr>   <td align="right" nowrap>Width:</td>   <td><input type="text" name="width" size="6"></td>   </tr>   </table>   </div>   <div id="heightlayer" style="position:absolute; left:286px; top:0px;   width:140px; height:41px; z-index:4">   <table>   <tr>   <td align="right" nowrap>Height:</td>   <td><input type="text" name="height" size="6"></td>   </tr>   </table>   </div>  </body>

If you're working in Dreamweaver, change your layout to look like the one shown in Figure 6.11. Make sure to name your form fields width and height .

Figure 6.11. Layout for the Block Spacer Property inspector, as seen in Dreamweaver Code and Design view.

graphics/06fig11.gif

For the inspector's icon, you can download blockspacer.gif from the companion web site, or make your own graphic.

note

If you don't like stopping to create icons when you're ready to design a new inspector, keep a blank or generic icon around to use as a placeholder while the inspector is in development. You can even save a copy of the blank icon with the proper name (for example, blockspacer.gif) in the Inspectors folder, so you don't have to change the file's code when you do eventually create a custom graphic for that file.

Task 3: Double-check the canInspectSelection() function

In the practice session, you created the simplest of all canInspectSelection() functions; it just returned true , no questions asked. When would you not want to do this? Remember, Dreamweaver calls this inspector only when the cursor is within a <spacer> tag. Can you think of any times when you wouldn't want this inspector called, given this situation? There are no alternative methods of inspecting spacers Dreamweaver hasn't provided one, and it's much too simple a tag to warrant you creating multiple inspectors. Therefore, you always want this function to return true . So leave it the way it is.

Task 4: Revise the inspectSelection() function

The purpose of inspecting a selection, remember, is to copy any attribute values from the selected object to the relevant form fields in the inspector. To accomplish this for the Block Spacer inspector, revise your inspectSelection() function to look like this (new code is in bold):

 function inspectSelection() {  myDOM = dw.getDocumentDOM();  myObject = myDOM.getSelectedNode();  findObject("width").value = myObject.width;   findObject("height").value = myObject.height;  }

Task 5: Create a setDimensions() function

In addition to inspecting properties, your inspector needs to change the document based on user input. For that, you need a local function. (If you're adapting the mood inspector code, you can remove the makeMeHappy() functionyou no longer need to make anyone happy.)

Write a function that will change two properties, width and height , and pass it a parameter. Call the function setDimensions() . The code should look like this:
```
 function setDimensions(dim) {  myDOM = dw.getDocumentDOM();  myObject = myDOM.getSelectedNode();  if (dim == "width") {        myObject.width = findObject("width").value;        }  if (dim == "height") {        myObject.height = findObject("height").value;        }  } 
```
Can you tell what this code is doing? The passed parameter can be either width or height . The function gains access to the selected object (lines 2 and 3) and, depending on which of those two values is passed in the function call, sets either the width (line 5) or the height (line 8) attribute of the selected <spacer> tag to the value entered in the appropriate form field.

Now, add function calls to the two text fields in the form, making sure each one passes the correct parameter, like this (new code is in bold):

 <input type="text" name="width" size="6"  onBlur = "setDimensions('width')"  >  <input type="text" name="height" size="6"  onBlur = "setDimensions('height')"  >

Try it out! You've built a simple but complete inspector. Launch (or re-launch) Dreamweaver, create a new document, and insert a <spacer> element using your Block Spacer object or coding it by hand. When you select it, your Block Spacer inspector should appear. Changing either value in the inspector should change the spacer. (Because Dreamweaver doesn't display spacers in Design view, you'll have to work in Code and Design view to see the results of your inspection.) Figure 6.12 shows the Block Spacer inspector in action.

Figure 6.12. The Block Spacer inspector, inspecting a <spacer> tag surrounded by some sample text.

Task 6: Refine and bulletproof!

In a perfect world, in which no one ever makes unusual demands, tinkers with the code when Dreamweaver isn't looking, or imports code from other programs, your object and inspector would now work nicely hand in hand. Right. But what if a user didn't want to insert a block spacer, and so hand-coded the spacer to be vertical or horizontal only? What if

What if a user, faced with your inspector, decides to delete the width attribute and leave only the height attribute? You could always rewrite the canInspectSelection() function to return true only if the spacer has a type of block , but that would cause more problems than it solves .

Instead, revise the setDimensions() function to detect whether both width and height values are present; and if not, to change the type to horizontal or vertical and remove the unused attribute. And vice versa, if a user adds a width or height where there was none before, the function adds the attribute and changes the type accordingly .

Create a new function, errorChecking() , to take care of this. The code for the new function should look like this:
```
 function errorChecking() {  var myDOM = dw.getDocumentDOM();  var myObject = myDOM.getSelectedNode();  if (!myObject.height) {     myObject.removeAttribute("height");     }  if (!myObject.width) {     myObject.removeAttribute("width");     }  if (myObject.height && myObject.width) {        myObject.type = "block";        } else if (myObject.width && !myObject.height) {        myObject.type = "horizontal";        myObject.removeAttribute("height");        } else if (myObject.height && !myObject.width) {        myObject.type = "vertical";        myObject.removeAttribute("width");        }  } 
```
What's happening here? As in other functions, lines 2 and 3 gain access to the selected object, so it can be inspected. Lines 46 determine if there is no height value specified in the object, and if so remove the height attribute; this is to eliminate code like this:
```
 <spacer width="50" height=""> 
```
Lines 79 do the same error-checking for the width attribute, removing it from the code if there is no value for it.

Starting in line 10, an if-else statement sets the object's type attribute to block , vertical , or horizontal , based on the presence or absence of width and height attributes in the code.

Now, what if a pesky user insists on removing both the width and height values? A spacer isn't a spacer without some dimensions. How you treat such a problem is partly scripting and partly strategic interface design. What do you want to happen in such a case? The least- intrusive solution is to ignore the problem, and let the invalid code stay on the page. A broken spacer doesn't break the web page; it just doesn't function as a spacer . A more hands-on solution is to insert default values, and bring up an alert window to let the user know what's happening.

Take care of this by adding another conditional to the end of the errorChecking() function (new code is in bold):

 function errorChecking(dim) {  [etc]  if (!myObject.height && !myObject.width) {   window.alert("Spacers must have at least one dimension.\nDefault   values have been inserted.");   myObject.height = 10;   myObject.width = 10;   myObject.type = "block";   }  }

You now have your errorChecking() function all set, but it won't be able to catch any errors unless you call it! To do this, add the following statement of the setDimensions() function:
```
 function setDimensions(dim) {  myDOM = dw.getDocumentDOM();  myObject = myDOM.getSelectedNode();  if (dim == "width") {        myObject.width =  findObject("width").value;        }  if (dim == "height") {        myObject.height = findObject("height").value;        }  errorChecking();  } 
```
tip

Here's a tip from this last bit of code: The Dreamweaver alert windows do not wrap text unless you tell them to. Notice that the alert statement here uses a new line character to force a line break between the two sentences.
Finally, the preceding error-checking function catches any strange input the user puts into the inspector, but what if a user starts out with a <spacer> that's missing somethinga width or height parameter, or both? You can detect such problems as soon as the inspector appears, using inspectSelection() but you can't fix them at this point. (The inspectSelection() function isn't allowed to make document edits.) What you don't want is for the inspector to show up with undefined as one of its values. That would definitely be bad interface design.

Eliminate that potential problem by tweaking the inspectSelection() function (new code is in bold):
```
 function inspectSelection() {  myDOM = dw.getDocumentDOM();  myObject = myDOM.getSelectedNode();  if (myObject.getAttribute('width')) {  findObject("width").value = myObject.width;  }   if (myObject.getAttribute('height')) {  findObject("height").value = myObject.height;  }  } 
```
What does this code do? The form fields for width and height will be filled in with a value only if the <spacer> object has the specified attribute. (For more information on the getAttribute() method, see Table 4.5 in Chapter 4.)
That's it! Try out your revised inspector. Go aheadtry to break it. Insert a <spacer> tag in a document with information missing. How does the inspector respond? Once you've got the <spacer> selected, try deleting the information from either the width or height form input field. If you can get the inspector to break, see if you can fix it. Keep doing that until you can't break it anymore. Congratulations! You're probably bulletproof.