Programmatically Adding Repeating Regions


Programmatically Adding Repeating Regions

Repeating regions are another Dreamweaver MX template innovation. Typically, a repeating region surrounds a table row containing one or more editable regions. After creating an instance of the template, the designer can manipulate the number of rowsadding or removing them as needed and even changing their order. To add a row in a repeating region, you need to make sure the View > Visual Aids > Invisible Elements option is turned on. Then select the Add (+) button above the repeating region. This system works well for individual pages, but it might be a roadblock in a production situation. In this section, I'll show you how to programmatically add any number of additional rowsor whatever the repeating region encloses.

The structure of a repeating region is similar to other template region types, but it is different enough to require alternative handling. Here is a sample repeating region with three editable regions, one in each table cell , as inserted into a template:

 <!-- TemplateBeginRepeat name="RepeatRegion1" -->    <tr>      <td><!-- TemplateBeginEditable name="EditRegion6" -->&nbsp;      <!-- TemplateEndEditable --></td>      <td><!-- TemplateBeginEditable name="EditRegion7" -->&nbsp;      <!-- TemplateEndEditable --></td>      <td><!-- TemplateBeginEditable name="EditRegion8" -->&nbsp;      <!-- TemplateEndEditable --></td>    </tr>  <!-- TemplateEndRepeat --> 

The template syntax seems straightforward enough, but look what happens when a document is created from the template:

graphics/05icon05.gif

Notice the additional repeat entry identifying tags. From a DOM point of view, these nodes within the outer repeating region node make it a bit more difficult to select an inner editable region programmatically. Luckily, the Dreamweaver engineers have provided a significant aid for situations like these. Within the Shared folder, you'll find a collection of functions used by Macromedia commands to perform their magic; for Dreamweaver MX templates, the assisting file is called TemplateUtils.js. Found in the Shared/MM/Scripts/CMN folder, the TemplateUtils.js file has more than 90 template- related functions. Although it is beyond the scope of this book to discuss all of those functions, we will cover several that are used for our purpose. If you are working in-depth with templates, be sure to examine TemplateUtils.js closely.

To demonstrate the techniques in this section, I've created a sample extension, Add to Repeating Region, . This extension (see figure 5.3), given the name of a repeating region and a number, adds the specified number of rows to the region.

Figure 5.3. This custom extension adds repeating rows to the end of the region, although you can easily add them to the top, if desired.

graphics/05fig03.gif

NOTE

To view the completed code, see Listing 5-3 at the end of this section.


NOTE

This represents a little behind-the-scenes magic managed by the Dreamweaver engineers. This code works in all installations of Dreamweaverincluding multiuser configurations. In multiuser configurations, custom extensions like this one are installed in the user Dreamweaver folder, not the system folder, where the Shared scripts are stored. In effect, Dreamweaver understands what you are trying to accomplish, and rather than literally trying to locate the specified file one level up in the nonexistent user Shared folder, Dreamweaver knows to look in the system Shared folder.


One of the first lines of code in the example extension includes the TemplateUtils.js file:

 <script language="JavaScript" src="../Shared/MM/Scripts/CMN/  TemplateUtils.js" type="text/JavaScript"></script> 

Unfortunately, despite the range of the functions available in TemplateUtils.js, not one exactly fits the first goal: to find a repeating region by name on a template-derived document. However, we're not completely out of luck. One function, findNamedRepeatRegion() , is close:

graphics/05icon06.gif

graphics/05icon07.gif

As pointed out in the callout, this function finds repeating regions within templates. There is a different syntax for repeating regions within instances of templates. To get the functionality needed for our extension, follow these steps:

  1. From the TemplateUtils.js folder, copy the findNamedRepeatRegion() function.

  2. Locate the line of code that reads as follows :

     var params = scopeNode.getElementsByTagName("MMTemplate:Repeat"); 
  3. Change "MMTemplate:Repeat" to "MMTInstance:RepeatEntry" .

  4. Rename the function to findNamedRepeatingRegionInstance() .

    What you choose to name the function is really optional; it's only important that you do rename any modified functions to avoid conflicts.

Even though we have included a modified version of a TemplateUtils.js function, it is still necessary to include the entire file. Even the modified function uses other support functions, such as findTemplateScopeNode() .

The next modification necessary for this function comes down to style. Rather than including yet another, rather lengthy file, I'd prefer to use some built-in functionality. The original function called out an external script and function to check for a matching name:

 if (dwscripts.minEntityNameDecode(params.item(i).name) ==  regionName) 

However, I found that I could get the same results with a DOM function:

 if (params[i].parentNode.getAttribute("name") == regionName) 

The parentNode property is needed to take the additional InstanceRepeatEntry nodes into account. The point here is that after you have begun to customize a function, you can code it in your own style.

If we find a matching region, we can then look for an editable region within the repeating region. To add a new row using this technique, we need to have a portion within the repeating region selected. Because the one commonality that repeating regions used in this way share is an editable region, that's what we look for:

 var theER = findChildEditableRegion(params[i]) 

The findChildEditableRegion() function is another useful tool from the TemplateUtil.js file. After we identify the editable region, we select it:

 var theOffs = curDOM.nodeToOffsets(theER);  curDOM.setSelection(theOffs[0], theOffs[1]); 

Now we're ready to perform the actual operation of the extension. After getting the user-supplied value, we'll take advantage of another bit of built-in Macromedia functionality to add the rows:

 var theNum = parseInt(findObject("number_text").value);  for (x = 0; x < theNum; ++x) {    dw.runCommand("InsertRepeatEntry.htm",null,null,"listEnd");  } 

As you can see, the custom extension executes a standard Dreamweaver command: InsertRepeatEntry.htm. This command is used whenever Modify > Templates > Repeating Entry > New Entry at End is selected, or whenever the cursor is in the last row of a repeating region and the Add (+) button is selected.

TIP

The final argument, listEnd , determines where the row is added in the repeating region. Other valid values for this argument are listBegin , beforeEntry , and afterEntry . The latter two values refer to the current cursor position within the region.


Listing 5-3 Add to Repeating Region.htm (05_addrepeating.mxp)
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">  <html>  <head>  <title>Add To Repeating Region</title>  <meta http-equiv="Content-Type" content="text/html; charset=iso- 8859-1">  <script language="JavaScript" src="../Shared/MM/Scripts/CMN/UI.js"  type="text/JavaScript"></script>  <script language="JavaScript"  src="../Shared/MM/Scripts/CMN/TemplateUtils.js"  type="text/JavaScript"></script>  <script language="JavaScript">  <!-- //*************** Global Variables  function commandButtons(){      return new Array( 'OK', 'runCommand()', 'Cancel',      'window.close()');  }  function findNamedRepeatingRegionInstance(regionName, targetDom)     {     var curDOM = (targetDom == null) ? dw.getDocumentDOM     ('document') : targetDom;     var scopeNode = findTemplateScopeNode(curDOM);     if (scopeNode == null)        return null;     //For some reason, this seems to be case sensitive when     //looking for XML style tags.     var params = scopeNode.getElementsByTagName     ("MMTInstance:RepeatEntry");     for (i=0;i<params.length;i++)        {        if (params[i].parentNode.getAttribute("name") ==        regionName)           var theER = findChildEditableRegion(params[i])           var theOffs = curDOM.nodeToOffsets(theER);           curDOM.setSelection(theOffs[0], theOffs[1]);           var theNum = parseInt(findObject("number_text").value);           for (x = 0; x < theNum; ++x) {              dw.runCommand("InsertRepeatEntry.htm",null,null,              "listEnd");           }        }     return null;     }  function runCommand() {     var theDOM = dw.getDocumentDOM();     var theRR = findObject("name_text").value;     var theData = findNamedRepeatingRegionInstance(theRR, theDOM);     window.close();  }  //-->  </script>  </head>   <body>  <form name="form1" method="post" action="">    <table border="0">      <tr>        <td nowrap>  <div align="right">Repeating Region:</div></td>        <td><input name="name_text" type="text"        value="RepeatRegion1"></td>      </tr>      <tr>        <td><div align="right">Number to Add: </div></td>        <td><input name="number_text" type="text" id="number_text2"        value="2" size="5"></td>      </tr>    </table>    </form>  <p>&nbsp;</p></body>  </html> 


Joseph Lowery's Beyond Dreamweaver
Joseph Lowerys Beyond Dreamweaver
ISBN: B000H2MWYS
EAN: N/A
Year: 2001
Pages: 87
Authors: Joseph Lowery

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net