Optional Regions and Template Parameters

Dreamweaver MX introduced several powerful template features to complement the standard editable regions. Optional regions permit a designated area of a template-derived document to either be shown or hidden at design time. A catalog page might, for example, include an embedded "now on sale" banner in an optional region allowing the graphic to be displayed only for appropriate products. In this section, we look at ways of driving optional regions dynamically; it is assumed that you're familiar with inserting them in the standard fashion.

Optional regions use two different sets of tags for both the template and the template-derived document. Within the template, one set of tags surrounds the content in the <body> :

 <!-- TemplateBeginIf cond="dbOnSale" -->  <img src="../images/onsale.gif" width="152" height="71">  <!-- TemplateEndIf -->

Another related tag is inserted into the template's <head> area:

 <!-- TemplateParam name="dbOnSale" type="boolean" value="true" -->

If the value attribute of the TemplateParam tag is set to true , the optional region is displayed; if it is false , all content within the region is hidden.

When an instance of the template is created, the syntax of the tags changes significantly. The tags that mark the optional regions are not visible in the code, regardless of whether the region is designated to be shown. However, the counterpart to the TemplateParam tag is still present in the <head> , although now it is has become an InstanceParam tag, like this:

 <!-- InstanceParam name="dbOnSale" type="boolean" value="true" -->

The InstanceParam tag is our target for dynamically driving the optional region. Building on the procedure outlined in the previous sections, you would require four elements:

A boolean (true/false) field in the data source with the same name as the optional region
An application page that extracts the boolean field and outputs it into XML-like syntax
A template that includes an optional region
A routine in a Dreamweaver extension to write the boolean value supplied by the data into the InstanceParam tag

The fourth point represents the only difficult task ”and it's only difficult because it can be a little problematic locating InstanceParam tags to replace them. Because Dreamweaver template tags are HTML-comment based instead of Dreamweaver-specific tags ” <! InstanceParam... --> as opposed to <MM:InstanceParam...> ”they cannot be as easy isolated as a standard tag. Typically, when looking for a specific tag, the getElementsByTagName() function is used to retrieve an array of all of one type of tag on the same page. Any further search for a particular tag is then handled by looping through the array, looking for a specific attribute or value. That method won't work with comment-based tags.

To find a particular InstanceParam tag, we rely on two bits of information. First, all InstanceParam tags are placed in the <head> area, which limits our search quite explicitly. Second, InstanceParam tags are never placed within another tag; they are first children of the <head> tag. Armed with that little bit of knowledge, we're ready to begin the hunt for the elusive InstanceParam .

First, we employ the getElementsByTagName() function to get the contents of the <head> tag:

 var theDOM = dw.getDocumentDOM().getElementsByTagName("head")

Next, we gather all of the first children of the <head> tag object into an array:

 var theNodes = theDOM[0].childNodes;

Now we're ready to loop through the array, looking for a particular name associated with the optional region and the InstanceParam tag. In this example, we're looking for dbOnSale . When we find it, we want to change the attribute from true to false :

 for (i=0; i < theNodes.length; ++i) {    if(theNodes[i].getAttribute("name")) {      if ( theNodes[i].getAttribute("name") == "dbOnSale") {        theNodes[i].setAttribute("value","false");        break;      }    }  }

One final step is necessary to update an instance of a template. Again, an API call is ready to lend a hand:

 dw.getDocumentDOM().dom.updateCurrentPage() ;

The updateCurrentPage() function is the same one called when we select Modify, Template, Update Page.