Creating Your Own Objects and Behaviors in Dreamweaver

This chapter is from the book

Inside Dreamweaver 4

Learn More Buy

This chapter is from the book

This chapter is from the book 

Inside Dreamweaver 4

Learn More Buy

Working with Objects

In the last chapter, you learned that objects are created from files stored in Dreamweaver's Configuration/Objects folder. In this section, you'll learn what a well-formed object file looks like, how Dreamweaver processes object files, and how to build your own objects from scratch.

What Are Objects?

An object, in terms of Dreamweaver's API, is an HTML file that contains, or uses JavaScript to construct a string of HTML code to insert into the user's document. That string of code can be anything from this:

copyright John Smith, 2000

to this:

<font face= "Georgia, Times, Times New Roman, serif" size="2">copyright 
John Smith, 2000</font>

to this:

<table width="200" height="200" border="1">
	<tr>
		<td align="center" ><font face= "Georgia, Times, Times 
		New Roman, serif" size="2">copyright John Smith, 2000</font></td>
	</tr>
	</table>

In other words, it's anything that can validly sit in an HTML document. The code gets inserted wherever the user's cursor is when the object is chosen.

What Files, Where

If you look inside the Configuration/Objects folder, you'll see several subfolders, the names of which you should recognize as the categories of objects accessible in the Objects panel. Open up one of those folders (Common, for instance), and you'll see dozens of files, corresponding to the individual objects in the Common Objects panel. Each object consists of from one to three files, all with the same name but different extensions. These files are listed here:

• An HTML file (Table.html, for instance). This is the object file itself, the 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 (Table.js, for instance). 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's HTML 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 file, but it isn't necessary.

• An image file (Table.gif, for instance). This file contains a 16x16 pixel image that Dreamweaver uses to represent the object in the Objects panel. This file is also optional: If there is no image file, Dreamweaver will supply a generic image icon to represent the object in the panel.

Figure 22.1 shows some typical sets of object files.

Figure 22.1 The Objects/Common folder, containing the files for the Insert Date object (two files only) and the Insert Table object (three files).

Object files must be stored in one of the folders inside the Configuration/Objects folder. The folder in which they're stored determines what portion of the Objects panel they'll appear in.

Structure of a Simple Object File: No Dialog Box

Some objects use dialog boxes to collect user information, and some don't. Those that don't are (not surprisingly) easier to create. Figure 22.2 shows a simple object file that doesn't call a dialog box.

Figure 22.2 The structure of a simple object file, and how it translates into a Dreamweaver object.

The key elements of the file are as follows:

• 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 Objects panel.

• objectTag() function. This JavaScript function is the most important element of the object file. The function returns the exact code that 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.

In the example shown in Figure 22.2, the code returned by the objectTag() function is a simple level 1 heading. Notice how everything between the quote marks, in the return statement, becomes part of the user's document.

Structure of a Fancier Object File with a Dialog Box

More sophisticated objects do more than insert pre-established code; they collect user information and use that information to customize the inserted code. Figure 22.3 shows the structure of an object file that creates a dialog box to collect user input and then constructs the code to insert based on that input.

Figure 22.3 The structure of a full-featured object file, and how it translates into a Dreamweaver object.

The added element in this kind of object file is HTML Form, which becomes the dialog box for collecting user input and customizing the code. Note that the form as written doesn't include a Submit button. Dreamweaver supplies the OK and Cancel buttons automatically. The form needs to have only the fields for collecting data.

In the example shown in Figure 22.3, the code returned by the objectTag() function is a level 1 heading, but with the content to be determined by the user. Notice how a variable is used in the objectTag() function to collect the form input and pass it along to the return statement.

Making Your Own Objects

Did the previous information seem awfully theoretical? In this section, you'll get some hands-on experience making your own objects. You'll move from simple objects to complex, and along the way you'll learn some tips and tricks for efficient object-handling.

Before Getting Started...

Writing your own objects involves hand coding, for which you'll need a text editor. If you're an experienced scripter, you probably already have a favorite text editor (NotePad, SimpleText, BBEdit, HomeSite, and so on); you can use any text editor to code your Dreamweaver objects. You are also free to use Dreamweaver itself to code your objects; both Layout view and Code view come in handy. Although it might seem like a dangerous way to proceed, Dreamweaver has no problem editing its own extensions. This is because Dreamweaver accesses only the extension files when it's loading extensions, which happens only when the program launches or when you force it to reload extensions.

When you're coding and testing extensions, it's easy for file management to get out of hand. A good strategy is to create a special working folder, stored outside the Dreamweaver application folder. Keep the following items in this folder:

• A backup copy of the Configuration folder. Whether you're adding new extensions or changing existing files, it's courting disaster to work on your only copy of this folder. If things get hopelessly messed up, you can replace your customized Configuration folder with this clean one; it's quicker and easier than reinstalling the whole program.

• A shortcut (PC) or alias (Mac) to Dreamweaver's Configuration folder and any of its subfolders you'll be accessing frequently.

• Test files (you'll be generating several of those in this chapter's exercises).

• Files for packaging extensions.

• Any extensions that you want to keep inactive during your development work.

While you're working on the exercises in this chapter, keep your working folder open, or leave a shortcut or alias to it on your desktop; otherwise, you'll be doing a lot of navigating through your hard drive.

Exercise 22.1 Setting Up Shop

In this exercise, you'll get your working space in order and learn some of the basic extension-developing features available in Dreamweaver. You'll create a custom objects folder where you can store your exercise objects, and you'll get some practice loading and reloading extensions.

1. Make sure Dreamweaver isn't running. If Dreamweaver is open and running on your computer, quit the program. You do this to experiment with how and when Dreamweaver loads extensions.

2. Find and open the Configuration/Objects folder on your hard drive. As you saw previously, every object file must be stored in a folder within the Configuration/Objects folder; every one of those folders correlates to a set of objects in the Objects panel. You can also add new object sets to the panel by adding your own new folders to the Configuration/Objects folder.

3. Create a new folder inside the Configuration/Objects folder. Name it Custom. 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.

4. Launch Dreamweaver. Every time you launch Dreamweaver, the program checks the Configuration folder and loads all extensions inside.

5. Check the Objects panel for a new category called Custom. In the Objects panel, click the triangle that accesses the pop-up Objects menu. There should now be a category called Custom (see Figure 22.4). Of course, if you choose that category, it'll be empty; that's because, so far, the Custom folder that you created is still empty.

Figure 22.4 New Custom folder in the Configuration/Objects folder, and the resulting Custom category in the Objects panel.

6. Without quitting Dreamweaver, rename the Custom folder as Development. If you're on a PC, minimize Dreamweaver; if you're on a Mac, hide Dreamweaver or send it to the background. On your hard drive, go back to the Configuration/Objects folder and find your Custom folder. Rename it Development.

7. In Dreamweaver, check the Objects panel categories again. Go back to Dreamweaver. Repeat step 5, checking the Objects panel to see what categories of objects you have to choose from. Your new category should still appear as Custom, not Development. This is because Dreamweaver hasn't yet noticed the name change.

8. Force Dreamweaver to reload extensions without quitting and relaunching. Hold down the Ctrl/Opt key and click the pop-up triangle in the Objects panel. The Reload Extensions command should now appear at the bottom of the pop-up menu (see Figure 22.5). Choose that command. Although some extension-related tasks require the program to be relaunched, most updating can be done more quickly this way.

Figure 22.5 Ctrl/Opt-clicking the pop-up triangle in the Objects panel reveals the Reload Extensions command.

9. Check the Objects panel categories again. Now release the Ctrl/Opt key and click the pop-up triangle to access the object categories. Your custom category should now show up as Development.

What does this mean? Dreamweaver doesn't constantly access the object files; rather, it accesses them once as it launches. Any time you change an object file, you must make Dreamweaver notice your changes by either quitting and relaunching the program or Ctrl/Opt-clicking the Objects panel pop-up and choosing Reload Extensions.

Exercise 22.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 that we'll create in this exercise is a contact information line that links to an email address—just 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 exercise files in the Development folder that you created in the last exercise.

1. Decide on the exact line of code that you want the object to insert. In this case, this will be a one-line piece of text, formatted however you like, with an email address embedded in it. The result should look like Figure 22.6.

Figure 22.6 The inserted code for the Insert John Smith Contact Info object (shown in Layout and Code view).

If you don't want to type in all this code by hand, remember that you can use Dreamweaver's visual editor to create the final result; then go to the Code Inspector or Code view, and the code will be there, written for you.

2. Create the basic object file, with all structural elements in place. Open your text editor—or, if you prefer to work in Dreamweaver, open the Code Inspector—and enter the basic required code as described previously. You can leave out the details specific to this object, for now. Your code framework should look like this (elements that you'll be replacing later with custom text appear in bold):

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

TIP

If you write a lot of objects, you might get tired of writing this code framework over and over. You can save yourself all that typing by saving this empty framework as a text file and storing it in your working folder or in some other easily accessible spot.

3. Enter a page title into the code. This will become the ToolTip that shows in the Objects panel.

Most Dreamweaver ToolTips start with Insert (though this is convention only, not a requirement). A logical title for the current file, therefore, might be Insert John Smith Contact Info. The top portion of your code should now look like this:

<html>
<head>
<title>Insert John Smith Contact Info</title>

4. Insert the desired line of code as the return statement of the objectTag() function. If you have the line of code already typed into your computer, you can just copy and paste it in; otherwise, type it in manually now.

Note that the entire return statement must be in quotes. They can be single or double quotes; just make sure that they're in balanced pairs.

Your code should now look like this:

<html>
<head>
<title> Insert John Smith Contact Info </title>
<script language="JavaScript">
function objectTag() {
return '<p><font face="Verdana, Arial" size="2">
For more information, contact <a href="mailto:jsmith@mycompany.com">
John Smith</a></font></p>';
}
</script>
</head>
<body>
</body>
</html>

NOTE

As with any JavaScript return statement, there can be no hard returns within the statement. Make sure that your code is written out in one long line, or it won't work!

5. Save your file in the Development folder. Call it Contact John Smith.html.

Remember, object files must be in the proper folder, or they won't be recognized as objects. Make sure that you're saving the file into your Development folder. The extension can be .htm or .html—Dreamweaver accepts either.

The filename will become the menu command that appears in the Insert menu, so it's good practice to name it something descriptive. Unlike browsers and Web servers, Dreamweaver allows spaces in filenames and respects case changes. A filename such as Contact John Smith.html will work fine and will look good in the Insert menu. A filename such as jsmith_contact_info_1.html will also work, but it won't look as nice (or be as understandable) in the menu. Capitalization will also carry through to the menu entry.

6. Test your object!

If you already have Dreamweaver running, Ctrl/Opt-click the pop-up triangle in the Objects panel to access the Reload Extensions command.

If you don't have Dreamweaver running, launch it—the extension will be loaded automatically.

Create a new document, if there isn't one already open.

Check the Development category of the Objects panel. The new object should be there, represented by a generic object icon. Position the cursor over the icon, and the ToolTip should appear (see Figure 22.7).

Figure 22.7 The new custom object with a generic icon and ToolTip.

Click on the object. Your desired code should be inserted into the document.

Congratulations! You've made your very first object.

Exercise 22.3 Adding a Dialog Box

Your simple object is fine as far as it goes, but it's not a very flexible or useful object because it always returns the same code, no matter what. What if you want to link the contact information to someone other than good old John Smith? A fully functional object would bring up a dialog box that would ask for user input and then would enter that information into the code. That's the object you'll build next.

1. Open Contact John Smith.html and save it as Contact Info.html. Why reinvent the wheel? Let's build on our previous success by adding a dialog box and tweaking the objectTag() function's return statement to collect user input.

2. Change the page title of the new object file to Insert Contact Info.

   Remember, the page title creates the ToolTip that identifies the object in the Objects panel; right now, the page title of this file is identical to the title of the object that you worked on earlier. This makes it difficult to tell the objects apart in the panel, especially because both objects currently have generic icons.

3. Decide what pieces of the code you want to replace with user input. Check Figure 22.6 to remind yourself what the end product should look like.

For this object, you'll probably want to ask the user for a contact name (instead of John Smith) and an email address (instead of sending everything to poor John Smith's email).

4. Create an HTML form that will serve as a dialog box to collect this information. To be functional, your form will need two text fields: one to collect the name and another to collect the email address. So, the simplest form you could possibly come up with might look something like the one shown in Figure 22.8.

Figure 22.8 The form for the Contact Info object dialog box, as it appears in Dreamweaver's Layout view and as you want it to finally appear.

Open Contact Info.html and build the form in the body section of that file. If you like coding forms by hand, go to it. If you'd rather use a visual editor, open the file in Dreamweaver and use Dreamweaver's visual editor to build it. Figure 22.8 shows how the designed form might appear in Dreamweaver's Layout view.

NOTE

If you're building your form in Dreamweaver's visual editor, method and action properties will be automatically added to the <form> tag. Your form doesn't need either of those because the form isn't going to be processed in the standard way. You can safely remove these properties from your code. Dreamweaver will also add background and text color properties to the <body> tag; you should remove these and let Dreamweaver determine the appropriate color scheme for the dialog box.

Your form code should look like this:

<form name="theForm">
<table>
	<tr valign="baseline">
		<td align="right" nowrap>Contact Name:</td>
		<td align="left">
			<input type="text" name="contact" size="30">
		</td>
	</tr>
	<tr valign="baseline">
		<td align="right" nowrap>E-Mail Address:</td>
		<td align="left">
			<input type="text" name="email" size="30">
		</td>
	</tr>
</table>
</form>

5. Add variables to the objectTag() function to collect form data.

Open the Contact Info.html file in your text editor. The first step in processing user input is to declare two variables to collect the information from the two text fields in the form. These variables will be local to the objectTag() function and thus must be declared inside it.

Add two local variable declarations to your function, each initialized to the value of one of the form fields. The code of your objectTag() function should now look like this:

function objectTag() {
var contact = document.theForm.contact.value;
var email = document.theForm.email.value;
return '<p><font face="Verdana, Arial" size="2">For more information, 
contact <a href="mailto:jsmith@mycompany.com">John 
Smith</a></font></p>';
}

6. Rewrite the return statement, substituting the two variables for the name and email address. If you're an old coding hand, 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:

function objectTag() {
var contact=document.theForm.contact.value;
var email=document.theForm.email.value;
return '<p><font face="Verdana, Arial, sans-serif" size="2"> 
For more information contact <a href="mailto:' + 
email + '">' + contact + '</a></font></p>';
}

TIP

Why declare variables instead of putting the references to the form directly into the return statement? No reason, except that it keeps the return statement from getting too long and unwieldy. The following code would work just as well:

return '<p><font face="Verdana, Arial, sans-serif" size="2"> For more 
information contact <a href="mailto:' + document.theForm.email.value
 + '">' + document.theForm.contact.value + '</a></font></p>'

Figure 22.9 shows your complete object file code.

Figure 22.9 Complete code for the Contact Info.html object file.

7. Test your object. In Dreamweaver, reload extensions and try to insert the new object. You should get a lovely dialog box that looks like the one shown in Figure 22.10.

Figure 22.10 Dialog box for the Contact Info object.

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

Exercise 22.4 Refining Your Object

In this exercise, you'll see that, while the only required JavaScript function for an object is the objectTag() function, you can add other optional functions. In fact, you can define any function that you like in the head section of the object file. As long as you call the function in the <body> tag, using the onLoad event handler, Dreamweaver will execute the function as soon as the user chooses the object.

The local function that you'll add in this exercise addresses a minor annoyance that you may have noticed in the dialog box that your object calls up. When the dialog box comes up, the insertion point is not in the correct position for you to immediately start entering data. That's not a life-threatening problem, but it's less than slick.

1. Open the Contact Info.html file in your text editor. Because this is not major surgery, you'll work on the same object that you created in the last exercise instead of creating a new object.

2. Add an initializing function to the document head. Somewhere inside the <script> tags in the document's head section, add the following code:

   function initializeUI()
   {
   document.theForm.contact.focus();
   document.theForm.contact.select();
   }

What does this function do? The first line officially gives focus to whatever form element is named within it—in this case, the Contact field (your first text field). The second line selects the text (if any) in whatever form element is named within it—again, in this case, the Contact field.

TIP

This function is used in many of the objects that ship with Dreamweaver. (Macromedia does not prohibit borrowing pieces of code.) Because the function is not part of the API, there's nothing magic about its name. If you'd rather name it something different, feel free to do so.

3. Call the function from the <body> tag. Add the following code to the <body> tag of the object file:

   	<body onLoad="initializeUI()">

Because this function is not part of Dreamweaver's official object-handling procedure, it must be specifically called.

4. Reload extensions and test the object. Now try it out. Save and close the object file. In Dreamweaver, reload extensions and choose the object from the Objects panel. The insertion point should be primed and ready to enter data into the Contact field of the dialog box.

Exercise 22.5 Creating a Separate JS File

Although it won't affect the functionality of the object, you might decide that separating the JavaScript from the HTML portion of the object makes upkeep easier.

In this exercise, you'll separate the JavaScript and place it in a JS file, using a link inside the main object file (the HTML file) to access it.

1. Make a copy of the object file. Because this is a major change to your object, it's a good idea to make a copy of the original file to work on. You can use the File/Save As command in your text editor, or you can duplicate the file from Windows Explorer or the Macintosh Finder, whichever you prefer. If you keep both your duplicate and your original in the Development folder, you'll need to give each file a different name; if you want it to retain the same filenames, you'll have to move the original file to another folder. (Also, if you keep both files in the Development folder, Dreamweaver will show two generic icons in the Objects panel. If this is the case, you'll need to give each different object file its own unique page title so that the ToolTips that identify them in the Objects panel will be unique.)

2. Open the object file in your text editor or in Dreamweaver, and select the JavaScript in the head section.

   As you know if you're an experienced scripter, the JavaScript code that can be copied to an external file is the code that would normally appear in the HTML document's head section—the functions, in other words. So you start by selecting all the code that appears between the opening and closing <script> tags. You should select the bold code shown here:

   <html>
   <head>
   <title>Contact Info</title>
   <script language="JavaScript">
   function objectTag() {
   var contact=document.theForm.contact.value;
   var email=document.theForm.email.value;
   return '<p><font face="Verdana, Arial" size="2">
   For more information, contact <a href="
   mailto:'+email+'">'+contact+'</a></font></p>';
   }
   </script>
   </head>

3. Cut the selected code, and paste it into a new text document. Cut that code to the Clipboard (Edit/Cut). If you're working in a text editor, create a new document and paste in the code (Edit/Paste). If you're working in Dreamweaver, create a new document; then open the Code Inspector for that new document, and select all the code in the source editor and delete it. Then paste in the new code.

NOTE

Dreamweaver automatically supplies the HTML framework for all new documents; if you don't need that framework, it is safe to select the code and delete it.

4. Save the new document as Contact Info.js. The new document, which contains only the JavaScript code from the head of the original object file, must be saved as a text file with the .js extension. It should be stored in the Development folder, and named to match the object file.

NOTE

Actually, the filename doesn't need to match the object file, and the script file doesn't need to be stored in exactly the same folder as the object file, as long as the correct name and relative URL are given when the two files are linked. However, it is recommended to keep to a naming convention like this because it makes file management much easier.

5. In the object file, change the <script> tags to link to the JS file. The head section of the original HTML object file should now look like this:

   <head>
   <title>Contact Info</title>
   <script language="JavaScript">
   </script>
   </head>

   Change the opening script tag so that it looks like this:

   <head>
   <title>Contact Info</title>
   <script language="JavaScript" src = "Contact Info.js">
   </script>
   </head>

6. Save and close both files. Figures 22.11 and 22.12 show what the complete code should look like in the two files.

Figure 22.11 The complete code for Contact Info.html, substituting the external file reference for the JavaScript.

7. In Dreamweaver, reload extensions and try out the object. If you correctly moved the JavaScript code and correctly entered the link information in the object file, the object should work in exactly the same way it worked before.

Figure 22.12 The complete code for Contact Info.js.

Figure 22.13 Dreamweaver error message showing the result of incorrect linking between the object file and its external JS file.

If you didn't paste the correct code into the JS file, you'll probably generate a JavaScript syntax error, and Dreamweaver will generate an error message.

Exercise 22.6 Creating an Object Icon Using Fireworks

Professional-looking objects have their own icons. When the development phase of your object is done, the finishing 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 image file, preferably no larger than 16x16 pixels. (Larger images will work, but they'll be squashed into an 16x16 pixel space in the panel.)

• The file must have exactly the same name as the object file it goes with, but with the GIF extension. For this exercise, therefore, the name must be Contact Info.gif.

• The file must be stored in the same folder as the object file it goes with. For this exercise, the icon file must be stored in the Development folder.

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

This exercise won't show you how to create a graphic to use as an object icon; that's beyond the scope of this chapter. But you will see how to use an existing graphic as an icon file.

1. Create, adapt, or borrow a 16x16 pixel GIF file containing an icon. If you have access to a good graphics program (such as Macromedia Fireworks) and want to create your own icon, do it. Otherwise, use the Contact Info.gif file on the CD. (If you make your own file, make sure to name it Contact Info.gif.)

TIP

You don't have to create your icons from scratch. You can start with an existing icon and adapt it to your needs. The Contact Info.gif file on the CD was adapted from Macromedia's E-Mail.gif file.

2. Put the icon file in the Development folder. Remember, the icon must be stored in the same folder as the object file.

3. Reload extensions, and take a look at your icon. In Dreamweaver, reload extensions.

4. In the Objects panel, access your Development objects. If all went as planned, you should have a beautiful custom icon in place (see Figure 22.14).

Working Smart with Objects

Congratulations! You now know the foundation skills for making Dreamweaver objects. How can you make objects work for you?

Analyze Your Needs

As you've seen, any piece of HTML code that you repeatedly use in Web pages is a candidate for an object. The best object candidates, though, are pieces of code that you need to customize and then insert—changing 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 over and over as you add content to Web pages, ask yourself these 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 code? (If the code is exactly the same each time, requiring no customization, it might be more efficient to use a recorded command or even a library item.)

• 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 if the need 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 if it's time to crack open Dreamweaver and fit a new custom object inside.

Expand Your Horizons

When you feel comfortable with the basic object-making framework as presented here, expand yourself. Read through the Extending Dreamweaver manual to get ideas of what's possible in the Dreamweaver API. Take a look at some of the objects that come with Dreamweaver, to see how they're structured and what refinements they include.