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:
The same CFML template is executed for both the start and end tag of a custom tag.
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.
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>
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 |
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>