User Guide

Nesting custom tags 255
What data is accessible?
To enable developers to obtain maximum productivity in an environment with few restrictions,
CFML custom tags can expose all their data to collaborating tags.
When you develop custom tags, you should document all variables that collaborating tags can
access and/or modify. When your custom tags collaborate with other custom tags, you should
make sure that they do not modify any undocumented data.
To preserve encapsulation, put all tag data access and modification operations into custom tags.
For example, rather than documenting that the variable MyQueryResults in a tag's
implementation holds a query result and expecting users to manipulate MyQueryResults directly,
create a nested custom tag that manipulates MyQueryResult. This protects the users of the
custom tag from changes in the tag's implementation.
Variable scopes and special variables
Use the Request scope for variables in nested tags. The Request scope is available to the base page,
all pages it includes, all custom tag pages it calls, and all custom tag pages called by the included
pages and custom tag pages. Collaborating custom tags that are not nested in a single tag can
exchange data using the request structure. The Request scope is represented as a structure named
Request.
Where is data accessible?
Two custom tags can be related in a variety of ways in a page. Ancestor and descendant
relationships are important because they relate to the order of tag nesting.
A tag’s descendants are inactive while the page is executed; that is, the descendent tags have no
instance data. A tag, therefore, can only access data from its ancestors, not its descendants.
Ancestor data is available from the current page and from the whole runtime tag context stack.
The tag context stack is the path from the current tag element up the hierarchy of nested tags,
including those in included pages and custom tag references, to the start of the base page for the
request. Both
cfinclude tags and custom tags appear on the tag context stack.
High-level data exchange
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.
In addition, there are many cases in which descendant tags are used only as a means for data
validation and exchange with an ancestor tag, such as
cfhttp/cfhttpparam and cftree/
cftreeitem
. You can use the cfassociate tag to encapsulate this processing.
The
cfassociate tag has the following format:
<cfassociate baseTag="tagName" dataCollection="collectionName">