Executing Custom Tags

The following sections provide information on executing custom tags.

Tag instance data

When a custom tag page executes, ColdFusion keeps data related to the tag instance. The thisTag built in structured variable preserves this data with a unique identifier. The behavior is similar to the File tag-specific variable (sometimes called the File scope).

The following variables are generated by the thisTag structure:

Variable

Description

ExecutionMode
Valid values are "start" and "end."

HasEndTag
Used for code validation. It distinguishes between custom tags that are called with and without end tags.

GeneratedContent
The content that has been generated by the tag. This includes anything in the body of the tag, including the results of any active content, such as ColdFusion variables and functions. You can process this content as a variable.

AssocAttribs
Holds the attributes of all nested tags if you use cfassociate to make them available to the parent tags.

Variable	Description
`ExecutionMode`	Valid values are "start" and "end."
`HasEndTag`	Used for code validation. It distinguishes between custom tags that are called with and without end tags.
`GeneratedContent`	The content that has been generated by the tag. This includes anything in the body of the tag, including the results of any active content, such as ColdFusion variables and functions. You can process this content as a variable.
`AssocAttribs`	Holds the attributes of all nested tags if you use `cfassociate` to make them available to the parent tags.

Modes of execution

ColdFusion invokes a custom tag page in either of two modes:

Start tag execution
End tag execution

If an end tag is not explicitly provided and shorthand empty element syntax (<TagName .../>) is not used, the custom tag page gets invoked only once, in start tag mode. If a tag must have an end tag provided, use thisTag.HasEndTag during start tag execution to validate this.

The same CFML page is executed for both the start and end tag of a custom tag.

Specifying execution modes

A variable with the reserved name thisTag.ExecutionMode will specify the mode of invocation of a custom tag page. The variable has one of the following values:

Start start tag execution
End end tag execution

When the body of the custom tag (not the custom tag page or template) executes, the value of the ExecutionMode variable is inactive.

A custom tag page that performs processing in both modes can have the following format:

<cfif thisTag.ExecutionMode is 'start'>

  <!--- Start tag processing --->

<cfelse>

  <!--- End tag processing --->

</CFIF>

You can also use cfswitch:

<cfswitch expression=#thisTag.ExecutionMode#>

  <cfcase value= 'start'>

    <!--- Start tag processing --->

  </cfcase>

  <cfcase value='end'>

    <!--- End tag processing --->

  </cfcase>

</cfswitch>

Terminating tag execution

The cfexit tag terminates execution of a custom tag. The cfexit tag's method attribute specifies where execution continues. cfexit 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.

The following table summarizes cfexit behavior:

method attribute value

Location of cfexit call

Behavior

ExitTag (default)
Base page
Acts like cfabort

ExecutionMode=start
Continue after end tag

ExecutionMode=end
Continue after end tag

ExitTemplate
Base page
Acts like cfabort

ExecutionMode=start
Continue from first child in body

ExecutionMode=end
Continue after end tag

Loop
Base page
Error

ExecutionMode=start
Error

ExecutionMode=end
Continue from first child in body

method attribute value	Location of cfexit call	Behavior
ExitTag (default)	Base page	Acts like cfabort
	ExecutionMode=start	Continue after end tag
	ExecutionMode=end	Continue after end tag
ExitTemplate	Base page	Acts like cfabort
	ExecutionMode=start	Continue from first child in body
	ExecutionMode=end	Continue after end tag
Loop	Base page	Error
	ExecutionMode=start	Error
	ExecutionMode=end	Continue from first child in body

Access to generated content

Custom tags 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 given 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 results in changes to the generated content.

thisTag.GeneratedContent 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.

As an example, consider a tag that comments out the HTML generated by its descendants. Its implementation could look something like this:

<cfif thisTag.ExecutionMode is 'end'>

<cfset thisTag.GeneratedContent =

    '<!--#thisTag.GeneratedContent#-->'>

</cfif>

Developing ColdFusion Applications
Reusing Code