Developing ColdFusion MX Applications with CFML
Reusing Code in ColdFusion Pages

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.
• Can do specific processing when ColdFusion encounters the beginning tag.
• Can do processing that is different from the begging 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 calling page's Variables scope, 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 figure shows how this works. The arrows indicate the flow of ColdFusion processing the pages.

Calling custom CFML tags

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

• Call a tag directly.
• Call a tag using the cfmodule tag.
• Use the cfimport tag to import a custom tag library directory.

To call a CFML custom tag directly, precede the file name with cf_, omit the .cfm extension, and put 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 Chapter 10, "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 Macromedia ColdFusion Developer's Exchange includes a library of custom tags that perform a wide variety of often-complex jobs; see http://devex.macromedia.com/developer/gallery/index.cfm.

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 similar to 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 invoking it requires less system overhead than using a custom tag.

For more information

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

Copyright © 2002, Macromedia Inc. All rights reserved.

Comments