Adding a Custom Object

Snippets are great for what could be termed static tags: custom code that requires no user intervention. For CMS code with variable parameters, custom objects are the extension of choice. Objects are user friendly, and you can choose them directly from the Insert bar or from a menu.

The easiest way to understand objects is to look at a simple Macromedia-supplied example. Following is the entire code for the Copyright object, which inserts the code for a copyright character entity:

As you can see, an object file is a standard HTML page with one key function: objectTag() . Whatever is returned from the objectTag() function is what is written into the user's document at the cursor location. In this example, it is a simple character entity. More complex objects might return a much longer string of information culled from user input and concatenated with other code, but there is still just one string returned.

The Copyright example shows how objects work on the most rudimentary level; for something like this, snippets could do the same job and are easier to set up. Objects really begin to shine when a parameter form is included in the HTML. Any standard HTML form element ”text fields, option buttons , check boxes, drop-down lists ”can be used in a parameter form. Each of the various form elements must be handled differently to extract the user input value. To see how it all works, let's look at an example that inserts a tag for the fictional JWL content management system (see Listing 1-1).

NOTE

To view the complete code, see Listing 1-1 at the end of this section.

When designing objects, I always start with the interface. Most of the programming job consists of pulling values from form elements, and you need to have all the elements in place before you can begin. An object is completely enclosed in a form, as shown in Figure 1.7. To maintain a clean appearance, I generally use a table to structure the form. It's not necessary to add Execute or Cancel buttons ”Dreamweaver does that for you for objects.

Figure 1.7. When you're creating a custom object, insert the form first, followed by the table and the form elements.

Make sure that all form elements have a unique, identifiable name . JavaScript requires the uniqueness; keeping the names understandable is good coding practice. Another good practice is to use the findObject() function whenever possible. Although it's not included in the JavaScript API ”you have to insert it from the Snippet panel, under JavaScript, Readable MM Functions, Find Object ”it's indispensable . The findObject() function, given an element's name, returns its object, which you can then manipulate and read. If, for example, I had a text field named authorText , I could get its value like this:

 var theAuthor = findObject("authorText").value 

After including the findObject() function ”it is also available in Configuration/Shared/Macromedia/Scripts/CMN/UI.js ”we're ready to launch right into the objectTag() function. The first lines of code put findObject() to work, setting up variables for all the form elements:

 var theID = findObject("idText");  var theAuthor = findObject("authorText");  var theImageFolder = findObject("imagesFolderText");  var theDeptList = findObject("deptList");  var thePublicOption = findObject("publicCB");  var theExpiresChoice = findObject("expiresRB"); 

Text fields are the easiest of the form elements to work with and require little manipulation. When it comes time to write the return string, you can retrieve the user-entered value like this:

 theAuthor.value 

List objects, however, are a different story. First, you have to find which of the list items was selected, and then you have to get that item's value. To find the selected item, use code like this:

 var theDeptListChoice = theDeptList.selectedIndex;  theDeptListChoice = theDeptList.options[theDeptListChoice].value 

The first line gets the index of the selection, a zero-based number. If the first item in a list is selected, the index would be 0; if the second item is selected, the index would be 1, and so on. The second line returns the value of the selection, based on the index.

Checkboxes are either selected or not. After you determine the status of the checked property, you can set a value accordingly :

 var thePublicValue = thePublicOption.checked ? "public" :  "private"; 

Using a conditional operator, the variable thePublicValue is set to public if the checkbox is selected and private if it is not.

Our final form element is the option button. You can select only one option button in a group . The task now is to figure out which one that is. Unfortunately, the only way to do this gracefully is to add a programming loop where every element is examined to see if it is checked. After you find the checked element, you can set the value to be returned accordingly. Here is one way to loop through a series of option buttons:

 for (i = 0; i < theExpiresChoice.length; ++i) {     if (theExpiresChoice[i].checked) {        var theExpiresValue = theExpiresChoice[i].value;        break;     }  } 

The final step in our object-programming example is to combine all the user values into one string and return it to the page. The surrounding tag elements are concatenated with the user values. Although you could format it in a single string, I broke it into sections to make it easier to read:

 var theTag = '<jwl:content '  theTag += 'author="' + theAuthor.value + '" ';  theTag += 'id="' + theID.value + '" ';  theTag += 'imageurl="' + theImageFolder.value + '" ';  theTag += 'dept="' + theDeptListChoice + '" ';  theTag += 'display="' + thePublicValue + '" ';  theTag += 'expires="' + theExpiresValue + '" ';  theTag += '></jwl:content>';  return theTag; 

When the HTML page is completed, the object is saved in one of the Object subfolders , such as Common or Script. You can also create your own subfolder to hold a collection of objects, if desired. Dreamweaver automatically uses a generic icon to represent your object on the Insert bar; if you'd like to use a custom icon, create a 16x16 pixel GIF image and store it in the same folder as your HTML file with the same base name. For example, an icon for the JWL_Content.htm object file would be called JWL_Content.gif. As noted earlier, Dreamweaver automatically renders the OK and Cancel buttons for the object, as shown in Figure 1.8.

Figure 1.8. When the object is selected from the Insert bar, the Custom Object dialog box is displayed, ready for user input.

When the object is inserted into the page, the complete tag will look something like this:

 <jwl:content author="Joseph Lowery" id="QORT77-432-23"  "imageurl="../images" dept="pr" display="public" expires="365" >  </jwl:content> 

The tag is now ready to go to work. All the user needs to do is enter the content between the opening and closing tag. And with content management systems, adding content is the easiest part.

Listing 1-1 Add Content.htm (01_addcontent.htm)

 <html>  <head>  <title>Add Content</title>  <meta http-equiv="Content-Type" content="text/html;  charset=iso-8859-1">  <script language='javascript'>  <!  //**************** Primary Functions **********************  function commandButtons(){      return new Array('OK', 'doCommand()', 'Cancel',      'window.close()')  }  // Example: obj = findObj("image1");  function findObj(theObj, theDoc)  {    var p, i, foundObj;    if(!theDoc) theDoc = document;    if((p = theObj.indexOf("?")) > 0 && parent.frames.length)    {      theDoc = parent.frames[theObj.substring(p+1)].document;      theObj = theObj.substring(0,p);    }    if(!(foundObj = theDoc[theObj]) && theDoc.all) foundObj =    theDoc.all[theObj];    for (i=0; !foundObj && i < theDoc.forms.length; i++)       foundObj = theDoc.forms[i][theObj];    for(i=0; !foundObj && theDoc.layers && i < theDoc.layers.length;    i++)       foundObj = findObj(theObj,theDoc.layers[i].document);    if(!foundObj && document.getElementById) foundObj =    document.getElementById(theObj);    return foundObj;  }  function objectTag() {     var theID = findObject("idText");     var theAuthor = findObject("authorText");     var theDeptList = findObject("deptList");     var theImageFolder = findObject("imagesFolderText");     var thePublicOption = findObject("publicCB");     var theExpiresChoice = findObject("expiresRB");      var theDeptList = findObject("deptList");     var theDeptListChoice = theDeptList.selectedIndex;     theDeptListChoice = theDeptList.options     [theDeptListChoice].value     var thePublicValue = thePublicOption.checked ? "public" :     "private";     for (i = 0; i < theExpiresChoice.length; ++i) {           if (theExpiresChoice[i].checked) {           var theExpiresValue = theExpiresChoice[i].value;           break;        }     }     // Return the html tag that should be inserted     return "&copy;";  }  >  </script>  <style type="text/css">  <!  .inputBox {     width: 200px;  }  .inputBoxIcon {     width: 180px;  }  >  </style>  </head>  <body>  <form name="form1" method="post" action="">    <table width="100%" border="0">      <tr>        <td><div align="right">ID</div></td>        <td><input name="idText" type="text" class="inputBox"        id="idText"></td>      </tr>      <tr>        <td><div align="right">Author</div></td>        <td><input name="authorText" type="text" class="inputBox"        id="authorText"></td>      </tr>      <tr>        <td><div align="right">Department</div></td>        <td><select name="deptList" class="inputBox" id="deptList">            <option value="null" selected>Select a            department...</option>            <option value="hr">Human Resources</option>            <option value="marketing">Marketing</option>            <option value="pr">Public Relations</option>            <option value="sales">Sales</option>          </select></td>      </tr>      <tr>        <td nowrap>  <div align="right">Images Folder</div></td>        <td nowrap>  <input name="imagesfolderText" type="text" class="inputBoxIcon"  id="imagesfolderText">           <img src="../Shared/MM/Images/folder.gif" width="16"           height="16"></td>      </tr>      <tr>        <td><div align="right">Public</div></td>        <td><input name="publicCB" type="checkbox" id="publicCB"        value="checkbox" onClick="showList()"></td>      </tr>      <tr>        <td valign="top"> <div align="right">Expires</div></td>        <td><p>            <input name="expiresRB" type="radio" value="30" checked            onClick="showList()">            30 days<br>            <input name="expiresRB" type="radio" value="365"            onClick="showList()">            One year<br>            <input type="radio" name="expiresRB" value="0"            onClick="showList()">            Never<br>          </p></td>      </tr>    </table>  </form>  </body>  </html>