Handling end tags

The examples of custom tags shown so far in this chapter all reference a custom tag using just a start tag, as in:

<cf_date>

In this case, ColdFusion calls the custom tag page date.cfm to process the tag.

However, you can create custom tags that have both a start and an end tag. For example, the following tag has both a start and an end tag:

<cf_date> 
   ...
</cf_date>

ColdFusion calls the custom tag page date.cfm twice for a tag that includes an end tag: once for the start tag and once for the end tag. As part of the date.cfm page, you can determine if the call is for the start or end tag, and perform the appropriate processing.

ColdFusion will also call the custom tag page twice if you use the shorthand form of an end tag:

<cf_date/> 

You can also call a custom tag using the cfmodule tag, as shown in the following example:

<cfmodule ...>
   ...
</cfmodule>

If you specify an end tag to cfmodule, then ColdFusion calls your custom tag as if it had both a start and an end tag.

Determining if an end tag is specified

You can write a custom tag that requires users to include an end tag. If a tag must have an end tag provided, you can use thisTag.HasEndTag in the custom tag page to verify that the user included the end tag.

For example, in date.cfm, you could include the following code to determine whether the end tag is specified:

<cfif thisTag.HasEndTag is 'False'>
   <!--- Abort the tag--->
   <cfabort showError="An end tag is required.">
</cfif>

Determining the tag execution mode

The variable thisTag.ExecutionMode contains the mode of invocation of a custom tag page. The variable has one of the following values:

• Start Mode for processing the start tag.
• End Mode for processing the end tag.
• Inactive  Mode when the custom tag uses nested tags. For more information, see Nesting custom tags.

If an end tag is not explicitly provided, ColdFusion invokes the custom tag page only once, in Start mode.

A custom tag page named bold.cfm that makes text bold could be written as follows:

<cfif thisTag.ExecutionMode is 'start'>
   <!--- Start tag processing --->
   <B>
<cfelse>
   <!--- End tag processing --->
   </B>
</cfif>

You then use this tag to convert the text to bold:

<cf_bold>This is bold text</cf_bold>

You can also use cfswitch to determine the execution mode of a custom tag:

<cfswitch expression=#thisTag.ExecutionMode#>
   <cfcase value= 'start'>
      <!--- Start tag processing --->
   </cfcase>
   <cfcase value='end'>
      <!--- End tag processing --->
   </cfcase>
</cfswitch>

Considerations when using end tags

How you code your custom tag to divide processing between the start tag and end tag is greatly dependent on the function of the tag. However, you can use the following rules to help you make your decisions:

• Use the start tag to validate input attributes, set default values, and validate the presence of the end tag if it is required by the custom tag.
• Use the end tag to perform the actual processing of the tag, including any body text passed to the tag between the start and end tags. For more information on body text, see Processing body text.
• Perform output in either the start or end tag; do not divide it between the two tags.

View comments in LiveDocs