Dreamweaver MX Extensions

Workshop #2: Creating a Simple Object with User Input

In this next workshop, we'll take our object-building skills one level higher, creating an object that uses a form to collect user input. Along the way we'll see how to create a nice layout for the dialog box and how to collect user input and build it into the return statement for the objectTag() function.

Sample Object: Inserting a Netscape Spacer Tag

The <spacer> tag creates a little block of empty white space on a pagea handy item, but one that works only in Netscape Navigator (all versions including 6). Internet Explorer completely ignores this tag. In its admirable effort to encourage users to use only cross-browser, cross-platform HTML code, Dreamweaver has no <spacer> tag in its standard set of objects.

I like to use <spacer> tags for two purposes: First, they are perfect when I design web pages for corporate intranets in which Netscape is the only browser in use; and second, they help Netscape to stabilize layout tables on complex pages. It's a well-known problem that some browsers ( especially Netscape) will sometimes shrink empty table cells, even if those cells have specified width or height attributes, resulting in a distorted page layout. The commonly accepted solution to this problem is to tuck little transparent GIF images throughout layout tables to "prop" cells open . But the same stability can often be achieved, without having to fiddle with spacer images, by inserting <spacer> tags instead.

Creating the Spacer Object

Like any project that involves creating an object, the Netscape <spacer> tag project can be broken down into three main components : determining what code the object will insert, building the object file, and testing and refining. This object is a bit more complex to create than the Centering Table because it requires user input to determine the various attributes of the <spacer> tag. It also includes the additional task of designing the form.

Task 1: Determine the HTML code you want the object to insert

The <spacer> tag takes three properties: type (horizontal, vertical, or block), width , and height . Horizontal spacers have only a width parameter; vertical spacers have only a height parameter; block spacers have both. To make things easy as you start out, assume that your object will create only block spacers; thus, there will always be two parameters to collect from the user ( width and height ). The code you have to insert will look like this:

<spacer type="block" width="?" height="?">

The question marks ( ? ) represent numbers that the user will supply. The form/dialog box will collect those numbers .

Task 2: Design a form to collect user input

As forms go, yours will be simple. It needs two input elements, both of which can be text fields, and a descriptive label for each. Following the Macromedia UI guidelines, this becomes a two-column dialog box with right-aligned labels and left-aligned text fields, as shown in Figure 2.11. For this task, don't worry about coding the formyou just want to know what it's going to look like and what input elements it will include.

Task 3: Create a basic object file

How you proceed in turning the previous elements into an object file depends largely on how comfortable you are with JavaScript coding and what your scripting habits are. My preference is to start simple and add complexity one step at a time. (I always like to start from what I know I can do, and work toward what I'm not sure I can do.) So that's how you will work here. You'll start by creating an object that inserts a spacer with no user input and make sure that works properly; then you'll add the form and revise the objectTag() function so it makes use of the information collected.

1. To start, open My Object.htm and save it in your Development folder as Block Spacer.htm .

2. Change the <title> to Block Spacer .

3. Revise the objectTag() function so that it inserts a spacer tag with set values (don't worry yet about collecting user input). Because you want your inserted spacer code to include double quotes, make sure to change the quotes around the return statement to single quotes. The code for your <head> section should now look like this (new code in bold):

   <head> <title> Block Spacer </title> <script language="JavaScript"> function objectTag() { return '<spacer type="block" width="50" height="50">' ; } </script> </head>

4. For the object's dialog box, create a form that looks like the one shown earlier in Figure 2.11. Name the two text fields width and height . The code for the object file's <body> section should now look like this (new code in bold):

   <body> <form name="myForm"> <table border="0" > <tr valign="baseline"> <td align="right" nowrap>Width:</td> <td align="left"> <input type="text" name="width" size="8"> </td> </tr> <tr valign="baseline"> <td align="right" nowrap>Height:</td> <td align="left"> <input type="text" name="height" size="8"> </td> </tr> </table> </form> </body>

When you've created the form, save and close the object file.

Task 4: Add an entry for the object to insertbar.xml

To make sure the new object displays properly in the Insert bar, open insertbar.xml in your text editor and add the following <button/> tag to your Development category:

<button id="DW_Development_BlockSpacer" image="" enabled="" showIf="" file="Development\Block Spacer.htm" />

When you've entered the code (and double-checked for typos!), save and close the file.

Try it out! In Dreamweaver, reload extensions and make sure the Block Spacer object appears in the Insert bar. Create a new document and choose the object. It should create a dialog box like that shown in Figure 2.11 and (regardless of user input into the form) should insert the following line of code into your document:

<spacer type="block" width="50" height="50">

(Note that Dreamweaver doesn't display spacers in Design view. You'll need to check Code view to make sure the proper code has been inserted.) If the object doesn't work, check your code against that shown previously, and troubleshoot until it does.

Task 5: Add form interactivity

Now that you have the object and you have the form, it's time to revise the objectTag() function so that it collects the information the user has entered into the form and uses that information to construct the string of code that it returns.

1. To collect the information from the form, define two variables whose names match the names you gave your two form text fields. Add these variable declarations at the beginning of your objectTag() function, like this (new code is in bold):

   <script language="JavaScript"> function objectTag() { var width=document.myForm.width.value; var height=document.myForm.height.value; return '<spacer type="block" width="50" height="50">'; }

2. Next, you have to rewrite the return statement so that it uses those variable names instead of the hard-coded width and height values it previously held. This is tricky. Start by removing the numbers from the code:

   return '<spacer type="block" width=" " height=" ">';

   Then break quoted text string into smaller chunks by entering single quotes on either side of each hole where you removed a number. Like this (new code in bold):

   return '<spacer type="block" width=" ' ' " height=" ' ' ">';

   Then put plus signs ( + ) on either side of each hole, to indicate that you'll be adding a variable there (new code in bold):

   return '<spacer type="block" width="' + + '" height="' + + '">';

   Finally, fill in the holes with the names of the variables (new code in bold):

   return '<spacer type="block" width="'+ width +'" height="'+ height +'">';

   Your revised objectTag() function should look like this:

   function objectTag() { var width=document.myForm.width.value; var height=document.myForm.height.value; return '<spacer type="block" width="'+width+'" height="'+height+'">'; }

   Putting strings of text and variable values together like this is called concatenating , and it can be one of the most difficult tasks in creating your Dreamweaver objects because of the single and double quotes that must be balanced. If you follow a procedure like the one above whenever you have to do this, you'll save yourself a lot of grief . Figure 2.12 shows a graphic representation of what happens when you replace values with variables.

   Figure 2.12. Inserting a variable in place of a property. See how a new set of quotes always gets inserted with the variable?

3. Finally, in Dreamweaver, reload extensions and try the object again. When the dialog box appears, enter numbers into the text fields and click OK. The code that gets inserted should include your numbers. If you get an error message, or if the right code doesn't get inserted correctly, go back to your object file. Carefully compare your code to the code shown here. Be on the lookout for typos! Make sure the names of your form and your text fields exactly match the names you call on in the objectTag() function. Make sure your double and single quotes balance (no opening quotes without closing quotes to match).

   note

   For a quick tutorial on using HTML forms and JavaScript together, see the section "Working with Form Elements" in Appendix A.

note

The most common mistakes in creating objects with dialog boxes are misaligning the quotation marks and not referring to the form field names correctly.

Task 6: Add some spit-and-polish

To tidy up, let's add a few last items. Wherever there's a dialog box that includes text fields, you want it to appear with the first text field active and its contents (if any) selected. To do that, use a local function (one that's not part of the API) that most standard Dreamweaver objects use.

1. In your text editor, open the Block Spacer.htm object file and add the following function to your <script> tag (new code in bold):

   <script language="JavaScript"> function objectTag() { var width=document.myForm.width.value; var height=document.myForm.height.value; return '<spacer type="block" width="'+width+'" height="'+height+'">'; } function initializeUI() { document.myForm.width.focus(); document.myForm.width.select(); } </script>

   The first statement of this function puts the insertion point in the specified field (notice that this function specifies the text field called width ); the second selects any contents.

2. Because the function you've just defined is a local function, not part of the API procedure, it must be explicitly called. You want it to execute as soon as the dialog box appears, so you'll call it onLoad . Add the following code to your object file's <body> tag (shown in bold):

   <body onLoad="initializeUI()" >

   Make sure you spelled the function name exactly the same in this line as you did when you defined the function (step 1). There you go!

note

If you test your extensions using Dreamweaver for Windows, you may notice that you don't need the initializeUI() function your object's dialog box opens with the width text field active even without the function. Dreamweaver for Macintosh requires the function to place the focus in the proper text field. Even if you're not developing for any Mac users, though, it's a good idea to get used to the concept of initializing dialog boxes as you open themand initializing the text field focus is also part of the UI requirements for extensions that are submitted to the Dreamweaver Exchange.

Listing 2.5 shows the complete code for the Block Spacer object.

Listing 2.5 Code for the Finished Block Spacer Object, Commented for Reference

<html> <head> <!the title will become the ToolTip> <title>Block Spacer</title> <script language="JavaScript"> function objectTag() { //collect information from form/dialog box var width=document.myForm.width.value; var height=document.myForm.height.value; //insert this code into document return '<spacer type="block" width="'+width+'" height="'+height+'">'; } //put focus in first text field of form function initializeUI() { document.myForm.width.focus(); document.myForm.width.select(); } </script> </head> <body onLoad="initializeUI()"> <form name="myForm"> <table border="0" > <tr valign="baseline"> <td align="right" nowrap>Width:</td> <td align="left"> <input type="text" name="width" size="8"> </td> </tr> <tr valign="baseline"> <td align="right" nowrap>Height:</td> <td align="left"> <input type="text" name="height" size="8"> </td> </tr> </table> </form> </body> </html>