Nesting Custom Tags

A custom tag can call other custom tags, thereby nesting tags. ColdFusion uses nested tags such as cfgraph and cfgraphdata, cfhttp and cfhttppam, and cftree and cftreeitem. The ability to nest tags allows you to provide similar functionality.

The calling tag is known as an ancestor, parent, or base tag, while the tags that ancestor tags call are known as descendant, child, or sub tags. Together, the ancestor and all descendent tags are called collaborating tags.

The following table lists the terms that describe the relationships between nested tags:

Calling tag

Tag nested within the calling tag

Description

ancestor
descendant
An ancestor is any tag that contains other tags between its start and end tags. A descendant is any tag called by a tag.

parent
child
Parent and child are synonyms for ancestor and descendant.

base tag
sub tag
A base tag is an ancestor that you explicitly associate with a descendant, called a sub tag, with cfassociate.

Calling tag	Tag nested within the calling tag	Description
ancestor	descendant	An ancestor is any tag that contains other tags between its start and end tags. A descendant is any tag called by a tag.
parent	child	Parent and child are synonyms for ancestor and descendant.
base tag	sub tag	A base tag is an ancestor that you explicitly associate with a descendant, called a sub tag, with `cfassociate`.

In order to nest tags, the parent tag must have a closing tag.

You can create multiple levels of nested tags. In this case, the sub tag becomes the base tag for its own sub tags. Any tag with an end tag present can be an ancestor to another tag.

Nested custom tags operate through three modes of processing, which are exposed to the base tags through the variable thisTag.ExecutionMode:

The start mode, in which the base tag is processed for the first time.
The inactive mode, in which sub tags and other code contained within the base tag are processed. No processing occurs in the base tag during this phase.
The end mode, in which the base tag is processed a second time. The end mode occurs when ColdFusion reaches the custom tag's end tag.

Associating sub tags with the base tag

While the ability to create nested custom tags is a tremendous productivity gain, keeping track of complex nested tag hierarchies can become a chore. The cfassociate tag lets the parent know what the children are up to. By adding this tag to a sub tag, you enable communication of its attributes to the base tag.

Developing ColdFusion Applications
Reusing Code