Executing Custom Tags

Tag instance data

During the execution of a custom tag template, ColdFusion keeps some data related to the tag instance. The ThisTag scope is used to preserve this data with a unique identifier. The behavior is similar to the File scope.

The following variables are generated by the ThisTag scope:

Pattern of execution

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

Modes of execution

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

If an end tag is not explicitly provided and shorthand empty element syntax (<TagName .../>) is not used, the custom tag template will be 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.

Specifying execution modes

A variable with the reserved name ThisTag.ExecutionMode will specify the mode of invocation of a custom tag template. The variable will have one of the following values:

During the execution of the body of the custom tag, the value of the ExecutionMode variable is going to be inactive. In this framework, the template of a custom tag that wants to perform some processing in both modes may look something like the following:

<CFIF ThisTag.ExecutionMode is 'start'>
    <!--- Start tag processing --->
<CFELSE>
    <!--- End tag processing --->
</CFIF>

CFSWITCH can also be used:

<CFSWITCH expression=#ThisTag.ExecutionMode#>
    <CFCASE value= 'start'>
        <!--- Start tag processing --->
    </CFCASE>
    <CFCASE value='end'>
        <!--- End tag processing --->
    </CFCASE>
</CFSWITCH>

Terminating tag execution

CFEXIT terminates execution of a custom tag. CFEXIT'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.

The METHOD attribute can also be used to specify that the tag body should be executed again. This enables custom tags to act as high-level iterators, emulating CFLOOP behavior.

The following table summarizes CFEXIT behavior:

CFEXIT Behavior in a Custom Tag 
METHOD Attribute Value Location of CFExit Call Behavior
ExitTag (default) Base template Acts like CFABORT
  ExecutionMode=start Continue after end tag
  ExecutionMode=end Continue after end tag
ExitTemplate Base template Acts like CFABORT
  ExecutionMode=start Continue from first child in body
  ExecutionMode=end Continue after end tag
Loop Base template 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 portion of the results that is generated by the body of a given tag. This includes all results generated by descendant tags, too. Any changes to the value of this variable will result 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>