MACROMEDIA ColdFusion MX, Develop Manual

Page: 185 / 860

Executing custom tags 185
Processing body text
Body text is any text that you include between the start and end tags when you call a custom tag;
for example:
<cf_happybirthdayMessge name="Ellen Smith" birthDate="June, 8, 1993">
<P> Happy Birthday Ellen!</P>
<P> May you have many more!</P>
</cf_happybirthdayMessge>
In this example, the two lines of code after the start tag are the body text.
You can access the body text within the custom tag using the
thisTag.GeneratedContent
variable. The variable contains all body text passed to the tag. You can modify this text during
processing of the tag. The contents of the
thisTag.GeneratedContent
variable are returned to
the browser as part of the tag’s output.
The
thisTag.GeneratedContent
variable is always empty during the processing of a start tag.
Any output generated during start tag processing is not considered part of the tag’s generated
content.
A custom tag can access and modify the generated content of any of its instances using the
thisTag.GeneratedContent
variable. In this context, the term generated content means the
results of processing the body of a custom tag. This includes all text and HTML code in the body,
the results of evaluating ColdFusion variables, expressions, and functions, and the results
generated by descendant tags. Any changes to the value of this variable result in changes to the
generated content.
As an example, consider a tag that comments out the HTML generated by its descendants. Its
implementation could look like this:
<cfif thisTag.ExecutionMode is 'end'>
<cfset thisTag.GeneratedContent ='<!--#thisTag.GeneratedContent#-->'>
</cfif>
Terminating tag execution
Within a custom tag, you typically perform error checking and parameter validation. As part of
those checks, you can choose to abort the tag, using
cfabort
, if a required attribute is not
specified or other severe error is detected.
The
cfexit
tag also terminates execution of a custom tag. However, the
cfexit
tag is designed to
give you more flexibility when coding custom tags than
cfabort
. The
cfexit
tag’s
method
attribute specifies where execution continues. The
cfexit
tag can specify that processing
continues from the first child of the tag or continues immediately after the end tag marker.
You can also use the
method
attribute to specify that the tag body executes again. This enables
custom tags to act as high-level iterators, emulating
cfloop
behavior.