Creating Object Extensions

[ LiB ]

The simplest kind of Dreamweaver extension to understand and create is the object. An object , in terms of the Dreamweaver API, is an HTML file that contains, or uses JavaScript to construct, a string of HTML code to insert into the user's document. The user clicks an icon in the Insert bar or selects an item from the Insert menu, and the specified code is inserted into the current document, usually at the insertion point.

Objects in the Configuration Folder

As you learned in the preceding chapter, object files are stored in subfolders of the Configuration/Objects folder that correspond to object categories in the Insert bar. Most objects consist of from one to three files, all with the same name but different extensions:

• An HTML file (such as table.htm) This is the object file itselfthe file that contains or returns the code to be inserted. This is the only file that must be present to constitute an object.

• A JavaScript file (such as table.js) This file contains JavaScript instructions for constructing the code to be inserted, in the form of one or more JavaScript functions, and is called on from the HTML file. This file is optional. It is entirely legal to contain the JavaScript functions in the head section of the object file instead of saving it to an external file. As experienced scripters know, it can be easier to keep track of and update JavaScripts if the code is in a separate filebut this isn't necessary.

• An image file (such as table.png) This file contains an 18x18-pixel image that Dreamweaver uses to represent the object in the Insert bar. This file is also optional: If there is no image file, Dreamweaver supplies a generic image icon to represent the object in the panel.

Figure 29.1 shows some typical sets of object files.

Figure 29.1. Files for the Date object (two files only) and the Image object (three files), both found in the Configuration/Objects/Common folder.

Objects in the Insert Bar: insertbar.xml

Dreamweaver MX 2004 relies heavily on XML files to help construct a unified interface from its many files and extensions. The insertbar.xml file, stored in the Configuration/Objects folder, contains a series of nested XML tags that govern what objects appear where in the Insert bar. Examine this file in a text editor, and you'll see that each object category is created from a pair of category tags. Within a category, subcategories are created by a pair of menubutton tags. Each object's presence in the panel is determined by a button tag. The button tag includes attributes specifying what files the object will call on, when it will appear in the panel, and what its unique identifier is. The Table object, which appears inside the Layout objects subcategory of the Common objects category, looks like this:

  <category id="DW_Insertbar_Common" MMString:name=    "insertbar/category/common" folder="Common">   [etc]  <menubutton id="DW_LayoutTools" MMString:name=  "insertbar/layoutTools"  image="Common\Table.png" folder="Tables">  [etc]  <button id="DW_Table" image="Common\Table.png" enabled=  "!_VIEW_LAYOUT" MMString:name="insertbar/table"  file="Common\Table.htm"/>  [etc]  </menubutton> [etc]  </category>  

The API for Objects

Some objects, such as the Email Link object, use dialog boxes to collect user information; others, such as the Horizontal Rule object, don't. The overall structure and procedure for both is the same.

Object File Structure

Figure 29.2 shows the HTML file for a simple object that doesn't call a dialog box. Note that the body section is empty. Also note that the objectTag() function is not called anywhere in the file. Dreamweaver calls the function automatically. Figure 29.3 shows the file for the same object, with a dialog box. The body contains a form, which will become the contents of the dialog box. Note that the form does not include a Submit button. Dreamweaver supplies this.

Figure 29.2. The HTML file for a simple object that does not call a dialog box.

Figure 29.3. The HTML file for an object that does call a dialog box.

Both files contain the following key elements:

• Filename This becomes the Insert menu entry for the object.

• Page title This becomes the ToolTip that pops up to identify the object in the Insert bar.

• objectTag() function This JavaScript function is the most important element of the object file. This function returns the exact code you want the object to insert into your document, enclosed in quotes. The objectTag() function is part of the Dreamweaver API, so it doesn't need to be defined. It also doesn't need to be called; Dreamweaver calls it automatically when the object is chosen .

• HTML form (optional) This becomes the dialog box for collecting user input and customizing the code. Dreamweaver supplies the OK and Cancel buttons automatically.

• displayHelp() function (optional) If there is a dialog box, and this function is defined, Dreamweaver adds a Help button to the dialog box. When the user clicks that button, the function is executed.

In the example shown in Figure 29.2, the code returned by the objectTag() function is a simple level 1 heading. Everything between the quotation marks, in the return statement, becomes part of the user's document. In the example shown in Figure 29.3, form input is collected and used to construct the return statement.

The Procedure for Objects

The API procedure for processing objects determines how and when Dreamweaver uses the file elements previously discussed. The procedure is as follows :

1. At startup, Dreamweaver reads the insertbar.xml file and populates the Insert bar using its entries. It also populates the Insert menu using the filename as the menu entry.
   
   
2. When the user mouses over the object in the panel, Dreamweaver uses the <title> from the object file to create the ToolTip that will appear.
   
   
3. When the user clicks an object, Dreamweaver reads the object file. If the file includes body content, Dreamweaver displays a dialog box containing the content, supplying OK and Cancel buttons automatically. If the file contains a displayHelp() function, a Help button also appears.
   
   
4. The final step in the API process is calling the objectTag() function. If there is a dialog box, the function is called when the user clicks OK. If there is no dialog box, the function is called as soon as the user clicks the object icon in the Insert bar. Whatever string of text is returned by the objectTag() function is inserted into the user's document, usually at the insertion point. (An exception to this is when the return string contains head content, such as a <meta> , <base> , or <link> tag. In this situation, even if the insertion point is in the body, Dreamweaver inserts the code into the head.)
   
   

Pretty simple, eh? To create an object extension, all you have to do is decide what code you want inserted and create a file that matches the structure shown in Figures 29.2 and 29.3. Then create an entry for the object in insertbar.xml to make it part of the Dreamweaver interface.

Not all objects are created equal! Some items lurking in the Insert barespecially those representing server-side code for live data pagesare very complex commands in object disguise. They're way beyond the scope of this chapter.

Exercise 29.1. Setting Up Shop

In this exercise, you'll get your workspace in order and learn about some of the basic extension-developing features available in Dreamweaver. You will create a custom folder within the Objects folder to store your exercise objects and add data to insertbar.xml so that your custom folder becomes a custom Insert bar category.

1. Make sure that Dreamweaver isn't running. You are doing this exercise to experiment with how and when Dreamweaver loads extensions.
   
   
2. Find your user-specific Configuration folder. (Check the section "Multiuser Support: The User Configuration Folder" in Chapter 28, "Customizing and Extending Dreamweaver," for more on user-specific Configuration items.) If there's an Objects folder here, open it. If there isn't, create a folder and call it Objects ; then open it. Create a new folder inside this folder, and name it Development . When you're developing new objects, it's a good strategy to put them in a special folder called Custom or Development , at least until you're sure they're running properly.
   
   

   

   Never store your object files loose in the Configuration/Objects folder, or Dreamweaver won't recognize them. Objects must be placed in an existing or new subdirectory within that folder.

   
   
3. If your user-specific Configuration/Objects folder contains an insertbar.xml file, open it in a text editor. If it doesn't, find the insertbar.xml file in the main Dreamweaver Configuration folder, and make a copy of it in your user-specific folder. Then open the copy in a text editor. Scroll to the end of the entries. Immediately above the closing </insertbar> tag, add the following code:
   
   

    <category id="DW_Insertbar_Development" folder="Development"> </category> 

   
   This creates a Development object category in the Insert bar, matching your Development folder.
   
   
4. Save and close insertbar.xml .
   
   
5. Launch Dreamweaver. At startup, the program checks the Configuration folder and loads all extensions that are inside it.
   
   
6. Check the Insert bar for a new category called Development. Because you added the code at the end of insertbar.xml , it should appear as the last item in the category drop-down menu, as shown in Figure 29.4. Of course, if you choose that category, it will be empty. You'll address that next .
   
   

   Figure 29.4. The new Development objects category in the Insert bar.

   

   
   

Exercise 29.2. Making a Simple Object

The simplest objects are those that don't call up a dialog box for user input, and therefore always return the same code. The simple object you will create in this exercise is a copyright statementjust the sort of thing you might want to put at the bottom of all your web pages.

To create this object, use the text editor of your choice. Save all the exercise files in the Development folder you created in the preceding exercise.

1. The first step when creating any object is to decide exactly what code you want the object to insert. In this case, you want a one-line piece of text, formatted however you like, utilizing the special HTML entity for . Figure 29.5 shows the copyright statement with formatting applied.
   
   

   Figure 29.5. Formatting the Tom Thumb copyright statement for inclusion in an object file.

   

   
   

   

   Use Design view to create and format the copyright statement, and then go to Code view. The code will be there, written for you.

   
   
2. Create the basic object file, with all structural elements in place. Open your text editor and enter the basic required code for an object without a dialog box. You can leave out the details specific to this object for now. Your code framework should look like this (elements that you will replace later with custom text appear in italic):
   
   

    <html> <head> <title>  Title Goes Here  </title> <script language="JavaScript"> function objectTag() { return '  inserted code goes here  '; } </script> </head> <body> </body> </html> 

   
   
3. Enter a page title into the code. This will become the ToolTip that shows in the Insert bar. A logical title for the current file might be "Tom Thumb Copyright Info ." The top portion of your code should now look like this (the new code is in bold):
   
   

    <html> <head> <title>  Tom Thumb Copyright Info  </title> 

   
   
4. Insert the desired line of code as the return statement of the objectTag() function. If you've already typed this line of code, you can just copy and paste it in; otherwise , type it in manually now.
   
   Note that the entire return statement has to be in quotation marks. They can be single or double quotes; just make sure that they're in balanced pairs.
   
   Your code should now look like this (the new code is in bold):
   
   

   

   Working with Word? As with any JavaScript return statement, no hard returns can occur within the statement. Make sure your code is written in one long line, or it won't work!

   
   

    <html> <head> <title>  Tom Thumb Copyright Info  </title> <script language="JavaScript"> function objectTag() { return '  <p>&copy; 2003, Tom Thumb</p>  '; } </script> </head> <body> </body> </html> 

   
   

   

   You can get more control over how the object name appears in the Insert menu by editing Configuration/Menus/ menus .xml .

   
   
5. Save your file in the Development folder. Call it Tom Thumb Copyright.htm . The filename will become the menu command that appears in the Insert menu, so it's good practice to name it something descriptive. Capitalization and spacing also carry through to the menu entry. (The extension can be .htm or .htmlDreamweaver accepts either.)
   
   
6. To make the new object appear in the interface, you need to add a <button/> tag to insertbar.xml . Quit Dreamweaver, if it's running, and open insertbar.xml in your text editor. Find the Development category tag you added earlier, and add the following code (the new code is in bold):
   
   

    <category id="DW_Insertbar_Development" folder="Development">  <button name="Tom Thumb Copyright Info" image=    "Development\Copyright Statement.gif" id="DW_TomThumb-    Copyright" file="Development\Tom Thumb copyright.htm" />  </category> 

   
   You might notice that you're referring to an image (Copyright Statement.gif) that doesn't exist yet. That's okay! You must specify an image for your object to display properly in the Insert bareven if you specify a non-existing image.
   
   
7. Test your object! Launch Dreamweaver and create a new document, if one isn't already open.
   
   
8. Check the Development category of the Insert bar; the new object should be there, represented by a generic icon. Position the cursor over the icon. The ToolTip should appear, as shown in Figure 29.6.
   
   

   Figure 29.6. The new custom object, with ToolTip.

   

   
   
9. While you're at it, check the Insert menu. Your new object appears at the bottom of the menu, identified by its filename.
   
   

   

   Don't waste your time making custom icon files for objects while they're still in the development phase. Wait until the object is all polished and perfectly functioning, and then dress it up with a custom icon. (Exercise 29.4 shows how to make an icon file.)

   
   
10. Position the insertion point where you want the object inserted, and click the object. The desired code should be inserted into the document at the current cursor position. Congratulations! You've made your very first object.
    
    

What If It Doesn't Work?

If your object doesn't show up in the Insert bar, you either saved it in the wrong place, you didn't append the .htm/.html extension to the filename, or there might be a syntax error in the insertbar.xml file.

If your object shows up, but something is wrong with the code, you'll probably get an error message when Dreamweaver tries to execute the objectTag() function. Dreamweaver error messages are fairly specific as far as what went wrong and what needs fixing. Examine the message, and fix your code accordingly .

Exercise 29.3. Creating an Object with a Dialog Box

Your simple object is fine as far as it goes, but it's not very flexible or useful because it always returns the same code, no matter what. What if you want to assign a copyright to someone besides good old Tom Thumb? A fully functional object would bring up a dialog box that would ask for user input and would enter that information into the code. That's the object you will build in this exercise.

1. Open Tom Thumb Copyright.htm (from the preceding exercise) and save it as Copyright Statement.htm in the Development folder. Why reinvent the wheel? You can just build on your previous success by adding a dialog box and tweaking the objectTag() function's return statement to collect user input.
   
   
2. Change the title of the new object file to Copyright Statement .
   
   
3. Decide what pieces of the code you want to replace with user input. Check Figure 29.5 as a reminder of what the end product should look like. For this object, you want to ask the user for a copyright name (rather than Tom Thumb) and a copyright year. (If your JavaScript skills are up to it, you could have Dreamweaver automatically calculate the year; for this exercise, just ask the user to insert it.)
   
   
4. You need to create an HTML form that will serve as a dialog box to collect this information. To be functional, your form needs two text fields: one to collect the name and another to collect the year. Open Copyright Statement.htm , and build the form in the body section of that file. If you like coding forms by hand, go to it. If you would rather use a visual editor, open the file in Dreamweaver, and use Design view to build it, as shown in Figure 29.7.
   
   

   Figure 29.7. The form for the Copyright Statement object dialog box as it appears in Dreamweaver Code and Design view.

   

   
   

   

   If you want to improve your skills in creating user-friendly forms, pay attention to all the user interface elements in Dreamweaver. The dialog boxes, inspectors, and panels are beautiful examples of clean, transparent interface design, and they're constructed almost entirely from standard form elements.

   
   Your form code should look like this:
   
   

    <form name="theForm"> <table> <tr valign="baseline"> <td align="right" nowrap>Name:</td> <td align="left"><input type="text" name="copyrightname">  </td> </tr> <tr valign="baseline"> <td align="right" nowrap>Year:</td> <td align="left"><input type="text" name="copyrightyear">  </td> </tr> </table> </form> 

   
   Note that neither the table nor the text has any formatting. Dreamweaver supplies the formatting when it processes the extension. If you enter your own formatting, your dialog box won't meet Macromedia user interface guidelines and might not look good on all computers. So don't do it!
   
   

   

   If you're building your form in the Dreamweaver visual editor, method and action properties are automatically added to the <form> tag. Your form doesn't need either of these because it won't be processed in the standard way. You can safely remove these properties from your code.

   
   
6. Your form is now pretty. To make it functional, you need to rewrite the return statement of the objectTag() to include the collected user input. If you're an old hand at coding, this will be a piece of cake. If you're a novice at JavaScript, the trickiest bit is balancing the opening and closing quotes so that you don't end up with any unterminated string literals. Your objectTag() function should now look like this (the new code is in bold):
   
   

    function objectTag() { return '<p>&copy; '+document.theForm.copyrightyear.value+',  '+document.theForm.copyrightname.value+'</p>'; } 

   
   

   

   If you think the return statement is too unwieldy to read easily, you can collect the form input into variables and use those to construct the final statement.

   
   
7. Quit Dreamweaver if it's running. To add the new object to your Insert bar, open insertbar.xml and add the following code to your Development category tag:
   
   

    <button name="Copyright Statement" id="DW_CopyrightStatement"  file="Development\Copyright Statement.htm" /> 

   
   
8. Launch Dreamweaver, and create a new document to try out your new object. You should get a lovely dialog box that looks like the one shown in Figure 29.8.
   
   

   Figure 29.8. The dialog box for the Copyright Statement object.

   

   
   
9. When you fill in your information and click OK, a customized copyright statement line should appear in your document.
   
   

What If It Doesn't Work?

As with the earlier exercise, if there's a problem with your code, Dreamweaver should give you a helpful error message. Read the error message, try to guess what it means, and then go back to your code and look for problems. Compare your code to the code listed in this exercise to see what might be wrong.

The most common things that go wrong in this kind of object file are incorrect references to form elements and mismatched single and double quotes in the return statement.

Exercise 29.4. Adding an Object Icon

Professional-looking objects have their own icons. When the development phase of your object is finished, the final touch is to make an icon file to represent it in the Objects panel.

The requirements for an icon file are as follows:

• The file must be a GIF, JPEG, or PNG image file, preferably no larger than 18x18 pixels. (Larger images work, but they're squashed into an 18x18-pixel space in the panel.)

• It's customary, though not required, to give the image the same name as the object file it goes with. For this exercise, therefore, name the image Copyright Statement.gif .

• It's customary, though not required, to store the image file in the same folder as the object file it goes with. For this exercise, the icon file must be stored in the Development folder.

• The icon must be called on in insertbar.xml by adding the image attribute to the <button> tag.

Icon files can have any colors you like, and the icon can look like anything you can imagine. You'll quickly discover, however, that designing icons that clearly communicate what they represent, when there are only 324 pixels to play with, is a real art.

1. Create, adapt, or borrow an 18x18-pixel GIF file containing an icon. If you have access to a good graphics program (such as Macromedia Fireworks), and you want to create your own icon, do it. Otherwise, use the Copyright Statement.gif file in the chapter_29 folder on the book's website at www.peachpit.com. (The image in this file is just a big symbol, which is not hard to create.)
   
   
2. Put the icon file in the Development folder. The instructions you wrote earlier in the insertbar.xml file specified that the image would be stored here.
   
   
3. Launch Dreamweaver, create a new document if needed to activate the Insert bar, and take a look at your icon! Figure 29.9 shows the Development folder, with a cool custom icon in place.
   
   

   Figure 29.9. The Copyright Statement object as it appears in the Insert bar, with its new custom icon in place.

   

   
   

Making the Most of Objects

Congratulations! You now have the foundation skills for making Dreamweaver objects. How can you make objects work for you? As you have seen, any piece of HTML code that you repeatedly use in web pages is a candidate for an object. The best object candidates, however, are pieces of code that you need to customize and then insertchanging the name and email address, specifying a certain URL to link to, and so forth.

Any time you find yourself going through the same steps repeatedly as you add content to web pages, ask yourself the following questions:

• Is the code I'm inserting similar enough each time that I could create an object from it?

• Are there differences in the code each time, or is it exactly the same? (If the code is exactly the same each time, requiring no customization, it might be more efficient to use a recorded command or snippet.)

• How many more times do I think I'm likely to need to insert this code? Will my need continue after today? After the current assignment? Indefinitely? Creating an object is a time-consuming solution (not smart for a need that is only very temporary).

• Do I have some extra time right now to devote to making this object? (Never try a new, challenging solution when your deadline is 45 minutes away.)

Depending on your answers, you'll know whether it's time to crack open Dreamweaver and fit a new custom object inside.

[ LiB ]