Tag Families

In the earlier example, you saw how introducing an end tag can improve the functionality of your Custom Tags. In this section, the power of Custom Tags is increased even further with the introduction of child tags to the scenario.

Almost every Web site has some sort of menu system that helps visitors navigate the site. We will use a nested menu system to discuss the use of nested Custom Tags.

TIP

Custom Tags can be nested more than one level deep. You can nest Custom Tags within Custom Tags as far as you desire. However, for performance reasons, it is recommended that you do not nest deeper than a few levels.

In the following code, we call two Custom Tags multiple times to create a menu structure:

 <cf_menu text="Products"          url="products.cfm">   <cf_menuitem text="ColdFusion"                url="productinfo.cfm?prod_ID=4">   <cf_menuitem text="JRun"                url="productinfo.cfm?prod_ID=5">   <cf_menuitem text="Flash"                url="productinfo.cfm?prod_ID=8"> </cf_menu> <cf_menu text="Support"          url="help.cfm">   <cf_menuitem text="Knowledge Base"                url="helptools.cfm?tool_ID=1">   <cf_menuitem text="Developer's Exchange"                url="helptools.cfm?tool_ID=2"> </cf_menu> <cf_menu text="About Macromedia"          url="about.cfm"> 

The <cf_menu> tag will display the main sections of the Web site, whereas the <cf_menuitem> tags will display specific pages within the section. Note, however, that <cf_menu> does not have to contain child tags, and can stand alone as a top-level menu item if necessary.

Custom Tag Functions

Two functions are used with Custom Tags to extend the intelligence of instance data and facilitate the transfer of data in a nested Custom Tag architecture.

GetBaseTagList()

When working with nested Custom Tags, we need a method of validation that helps us ensure that the tags are nested properly. The function GetBaseTagList() will be used for just this purpose. Review the following code:

 <cfset ParentTag=GetBaseTagList()> <cfif NOT ListFindNoCase(ParentTag, "cf_menu")>   This child tag must be embedded   within a parent tag called <cf_menu>   <cfabort> </cfif> 

We place this code within the child tag <cf_menuitem>. GetBaseTagList() returns a list comprising the names of all tags surrounding, and including, the child tag. With that list, you can use the string function ListFindNoCase() to check whether the parent tag is one of the tags surrounding the child tag. If the parent tag <CF_menu> does not surround the child tag, an error message will be displayed.

CAUTION

GetBaseTagList() can help you validate to ensure that your child tag is in fact embedded inside the correct parent tag. However, if you have multiple levels of nesting, you will have to do further parsing to ensure that the tags are nested in the correct order.

GetBaseTagData()

To create the most reusable and flexible Custom Tags, it's a good idea to make sure that a child tag can react differently to commands within the parent tag. In our example, the parent tag <cf_menu> has an attribute called containsitems. If the value of this attribute is set to yes, the child tags will be displayed below the parent tag. If the value of this attribute is set to no, child tags will not be displayed, even if child tags are listed.

For the child tags to react appropriately, they must know whether the parent tag has declared containsitems as yes or no. We will use the function GetBaseTagData() within the child tag to grab this data from the parent tag. Evaluate the following code:

 <cfset GetParentTagVars=GetBaseTagData("cf_menu")> <cfset ParentTagContainsItems=        stGetParentTagVars.ATTRIBUTES.ContainsItems> 

In the first <cfset> statement, all the variables in the parent tag <cf_menu> are pulled into the child tag as a structure and placed within a new structure called stGetParentTagVars.

Structures are discussed in Chapter 15, "Structures."

In the second <cfset> statement, we access the containsitems attribute from directly within the stGetParentVars structure. After we have this value, we can easily use it within conditional statements to force different behavior from the child tag.