Using custom CFML tags



Custom tags written in CFML behave like ColdFusion tags. They can do all of the following:

  • Take arguments.

  • Have tag bodies with beginning and ending tags.

  • Do specific processing when ColdFusion encounters the beginning tag.

  • Do processing that is different from the beginning tag processing when ColdFusion encounters the ending tag.

  • Have any valid ColdFusion page content in their bodies, including both ColdFusion built-in tags and custom tags (referred to as nested tags), or even JSP tags or JavaScript.

  • Be called recursively; that is, a custom tag can, if designed properly, call itself in the tag body.

  • Return values to the calling page in a common scope or the Variables scope of the calling page, but custom tags do not return values directly, the way functions do.

Although a custom tag and a ColdFusion page that you include using the cfinclude tag are both ColdFusion pages, they differ in how they are processed. When a page calls a custom tag, it hands processing off to the custom tag page and waits until the custom tag page completes. When the custom tag finishes, it returns processing (and possibly data) to the calling page; the calling page can then complete its processing. The following image shows this process. The arrows indicate the flow of ColdFusion processing the pages.

View full size graphic

Calling custom CFML tags

Unlike built-in tags, you can run custom CFML tags in the following three ways:

  • Call a tag directly.

  • Call a tag using the cfmessagebox tag.

  • Use the cfimport tag to import a custom tag library directory.

To call a CFML custom tag directly, precede the filename with cf_, omit the .cfm extension, and place the name in angle brackets (<>). For example, use the following line to call the custom tag defined by the file mytag.cfm:

<cf_myTag>

If your tag takes a body, end it with the same tag name preceded with a forward slash (/), as follows:

</cf_myTag>

For information on using the cfmodule and cfimport tags to call custom CFML tags, see Creating and Using Custom CFML Tags.

Recommended uses

ColdFusion custom tags let you abstract complex code and programming logic into simple units. These tags let you maintain a CFML-like design scheme for your code. You can easily distribute your custom tags and share tags with others. For example, the ColdFusion Developer Exchange includes a library of custom tags that perform a wide variety of often-complex jobs; see www.adobe.com/go/learn_cfu_exchange_en.

Consider using CFML custom tags in the following circumstances:

  • You need a tag-like structure, which has a body and an end tag, with the body contents changing from invocation to invocation.

  • You want to associate specific processing with the beginning tag, the ending tag, or both tags.

  • To use a logical structure in which the tag body uses “child” tags or subtags. This structure is like the cfform tag, which uses subtags for the individual form fields.

  • You do not need a function format in which the calling code uses a direct return value.

  • Your code must be recursive.

  • Your functionality is complex.

  • To distribute your code in a convenient form to others.

If you can create either a UDF or a custom CFML tag for a purpose, first consider creating a UDF because running it requires less system overhead than using a custom tag.

For more information

For more information on custom CFML tags, see Creating and Using Custom CFML Tags.