Saving development costs by reusing code has been a goal of the computing industry for a long time. With a little forethought you can save time and money developing Web systems using ColdFusion by encapsulating functionality in custom tags.

This article describes how to nest custom tags (a working knowledge of these tags is assumed. If you need more information on paired custom tags, see Charles Arehart's article in CFDJ, Vol. 3, issue 1). Because of the frequent references to listings later on, I suggest you download them now from www.sys-con.com/coldfusion/sourcec.cfm.

Any custom tag can be turned into a container for other custom tags. The container is called the parent tag; the other custom tags are called descendants or child tags. As with any family tree, there can be several levels of nesting, as shown in Figure 1.

Example Use of Nested Tags
You may find that you've written a custom tag that needs a lot of data. You can make some custom tags a lot easier to use by turning them into nested tags. For example, consider a custom tag that will build a formatted, numbered list of items for you. You could make a custom tag such as cf_buildlist that would take perhaps two attributes: one a list of styles (e.g., liststyles= "italic,bold,plain,plain,italic"), the other a list of list items (e.g., list-items="forests, jungles, oceans, lakes, rivers").

The cf_buildlist tag would generate something like this:

1. forests
2. jungles
3. oceans
4. lakes
5. rivers

In this custom tag design, your users have responsibility for creating two related lists and passing them to the cf_buildlist custom tag. It would be much easier for them if they could specify the formatting for each item at the time each list item is specified.

Nested custom tags can make things easier for your users. In this example you could create a cf_buildlist tag that had a closing tag and another child tag cf_listitem that accepted list items:

Now users can more easily specify each item and the style for each item. You could extend cf_buildlist to accept other attributes about the list as a whole. For example, you might add an attribute that specifies whether the list is bulleted or numbered.

A good guideline for deciding whether to turn a custom tag into a nested tag is this: if you can identify repeating groups of information in your existing attributes, then you have a candidate for creating parent/child tags.

Parents Getting at Child Data
Listing 1 is an example of a ColdFusion template that calls a custom tag cf_myparenttag (see Listing 2). cf_myparenttag has a child tag, cf_mysubtag (see Listing 3), and cf_mysubtag has its own child tag, cf_mysubsubtag (see Listing 4). In Listing 1 lines 16-26 make the call to cf_myparenttag. Lines 19-23 are the call to the cf_mysubtag.

CF_ASSOCIATE is used to allow parent tags to get at the attributes defined for child tags. Let's say you have a custom tag called cf_myparenttag that calls a child tag cf_mysubtag. You want cf_myparenttag to be able to access the attributes defined for cf_mysubtag. Do this is by using CF_ASSOCIATE in cf_mysubtag (see Listing 3), then accessing the attributes in cf_my-parenttag (see Listing 2).

In Listing 3, lines 10-12, we say that if the execution mode is "start", then associate the attributes de-fined for cf_mysubtag with the parent tag, cf_myparenttag.

Now look at Listing 2, lines 19-25. Here, if the execution mode is "end", we access the array of structures made available by the cfassociate function and print out the structure key and its corresponding value.

The output of Listing 1 is given in Listing 5. You can see the nesting effect in the printed statements: "Before calling myparenttag", "Before calling mysubtag", "Before calling mysubsubtag", "After calling my-subsubtag", "After calling mysubtag", "After calling myparenttag". All the custom tags have been called in sequence.

Thistag Scope
CFML provides functions that give information about the execution and type of custom tags and about the content generated by the tags. The structure "thistag" provides access to these variables:

• AssocAttribs: Associated attri-butes from child tags.
• ExecutionMode: Valid values are start, end, and inactive.
• HasEndTag: Used for code validation, it distinguishes between custom tags that have and don't have end tags for ExecutionMode=start. The name of the Boolean value is ThisTag.HasEndTag.
• GeneratedContent: Content from this tag that can be processed as a variable.

We've already seen how to use CF_ASSOCIATE to populate the AssocAttribs variable. All the other variables are populated for you by ColdFusion. In Listing 5, which shows the output of running Listing 1, you can see the values for the executionmode and hasendtag variables for each custom tag call. Note that cf_mysubsubtag isn't a paired custom tag; there's no corresponding end tag for the opening call. The parent tag for cf_mysubsubtag is cf_mysubtag, and in Listing 3, line 16, the variable #thistag.hasendtag# has the value NO because there is no end tag.

The variable #thistag.generatedcontent# provides access to the content generated by the custom tag. If you code your custom tag so it produces no output (e.g., by using cfsetting or cfsilent), you can process the generated content before it's displayed. You could use Cold-Fusion's string functions, for example, to replace a string in the generated content before it's displayed.

Children Getting at Parent Data
We've seen how a parent tag can access the attributes of its children. Now we'll look at how a child tag can access information about and data from its parent.

Two ColdFusion functions provide information about the execution of custom tags:

• GetBaseTagList()
• GetBaseTagData(parent tag name)

GetBaseTagList returns a comma-delimited list of execution scopes. In Listing 2, line 14, for example, the call to #getBaseTagList()# (when executed by running Listing 1) produces:

[CFOUTPUT, CF_MYPARENTTAG]

This gives the programmer the information that the current execution scopes are, first, CFOUTPUT, and then the custom tag cf_myparenttag.

Now look at Listing 3, line 17. Here the call to #getBaseTagList()# (when executed by running Listing 1) produces the list:

[CFOUTPUT,CF_MYSUBTAG,CF_MYPARENTTAG]

A programmer could now use this information to determine in what context the custom tag is executing. This might be important when the custom tag is included in an IF clause, for example. The programmer could check the list generated by #getBaseTagList# and determine whether the call to the current custom tag was made from within an IF clause.

GetBaseTagData returns a structure that contains information about the specified parent tag. Look at cf_mysubsubtag (Listing 4, lines 21-22). Here there is a call to #GetBaseTagData()# for the tag cf_mysubtag - the parent of cf_my-subsubtag. Since the parent we specified was a custom tag, we have access to the #thistag# set of variables. Line 22 accesses the #thistag.-executionmode# variable for cf_my-subtag. GetBaseTagData will work for any parent tag. For example, we could add a line at line 23 to say:

This would give access to all the thistag variables for cf_myparenttag.

Since you know the list of parent tags from #getBaseTagList#, you could write code that obtains data for each parent tag in the list. Note that some parents, such as CFIF, don't have any associated data.

Summary
Nested custom tags provide a very flexible way to abstract complexity, and make it easy for others to use your code. You can create nested tags easily, but as the complexity of your solution grows, you may need to call on the functions ColdFusion provides to allow parent tags to access attributes defined in child tags, or to allow child tags to access information about their parents. You can control with absolute precision what ColdFusion will display to the user by working with the generated content.

• Figure 1