Simple CFML Custom Tags: Back to Basics

ColdFusion custom tags are simply self-contained, reusable ColdFusion components that extend the functionality of the language beyond the built-in tags that come with the product. For the purposes of this chapter, I will assume that you have worked with custom tags before. After a review of the fundamentals, we'll explore the need for advanced custom tags.

NOTE

For an in-depth discussion of simple custom tags and the features and issues of using them, see Chapter 22, "Building Reusable Components," in Macromedia ColdFusion MX 7 Web Application Construction Kit (Macromedia Press).

Let's begin by going over some of the basic rules about CFML custom tags. You may think you know where to save your custom tags and how to call them, but some of these things have changed since ColdFusion MX was first released. In fact, there are more ways than ever to call a custom tag.

But let's start with a question to which you should already know the answer: Where can you save your CFML custom tags? As you can see from the list below, you have several options. ColdFusion looks for custom tag files in these locations:

• In the same directory as the calling page

• In the ColdFusion custom tag directory, c:\CFusionMX7\CustomTags

• In a subdirectory of the ColdFusion custom tag directory

• In any directory or subdirectory of the custom tag directory, specified in ColdFusion Administrator (the Custom Tags Path section of the Extensions category)

You also have many choices regarding syntax when it comes to calling CFML custom tags. The standard from previous versions of ColdFusion has always been the classic <cf_ThisTagName> syntax. The syntax for this call is straightforward:

 <CF_ThisTagName Attr1="Value1" Attr2="Value2" Attr3="Value3"> 

In previous versions of ColdFusion, you also could call the .cfm file directly using the <cfmodule> tag. When you use <cfmodule>, you have two options for calling a custom tag. Using the NAME attribute, you can reference the custom tag anywhere in the ColdFusion installation directory. If the custom tag is in c:\CFusionMX7\CustomTags\MyDirectory, then you could call it with this syntax:

 <cfmodule Name="MyDirectory.ThisTagName"  Attr1="Value1"  Attr2="Value2"  Attr3="Value3"> 

Using the TEMPLATE attribute, you can reference the custom tag using a ColdFusion mapped path, or one that's relative to the calling page's directory:

 <cfmodule TEMPLATE="/CustomTags/MyDirectory/ThisTagName.cfm"  Attr1="Value1"  Attr2="Value2"  Attr3="Value3"> 

The introduction of ColdFusion MX brought the capability to import a directory of CFML custom tags, by using the <cfimport> tag. If you are familiar with JavaServer Pages (JSP), this method is similar to how you would import a JSP tag library (taglib). In fact, the <cfimport> tag does double duty: It also allows you to import JSP taglibs for use in your ColdFusion page (JSP taglib importing is available in the Enterprise version only). Table 18.1 describes the <cfimport> tag and its attributes.

Table 18.1. Attributes for <cfimport>

ATTRIBUTE	REQUIRED?	DEFAULT	DESCRIPTION
TAGLIB	Yes	None	Directory containing CFML custom tags; can also point to a JSP tag library descriptor or JAR file.
PREFIX	Yes	None	Prefix for addressing imported CFML or JSP tags. To import without a prefix, pass an empty string ("").

As you can see from Table 18.1, you simply point the taglib attribute to a directory containing CFML custom tags, and assign that directory to a tag prefix. Let's start with a directory named mylib under the Chapter18 directory. You set the <cfimport> tag's taglib attribute to mylib, and the prefix attribute to lib. You can call all the tags in the specified directory like this: <lib:ThisTagName>.

You'd only use this JSP (or XML) style of syntax when accessing tags whose directory has been imported through <cfimport>. You call custom tags in other directories with the standard <cf_ThisTagName> syntax. If the <cfimport> tag's prefix attribute is passed an empty string, it results in HTML-style syntax with no CF_ or JSP-style prefix (as in <ThisTagName>). The second code snippet coming up after the next paragraph shows this syntax.

NOTE

When using the <cfimport> tag, you must first ensure that the custom tag directory you wish to importin this case, mylibis located under one of the custom tag locations mentioned at the beginning of this section.

The Chapter18/mylib directory contains an example tag library that includes the IntelligentForm.cfm and IntelligentInput.cfm custom tags (covered in depth later in this chapter). You can call them using <cfimport> like this:

 <cfimport taglib="mylib" prefix="lib"> <lib:IntelligentForm formName="MyForm">   <lib:IntelligentInput fieldName="SSN" size="12" maxLength="11"/>   <lib:IntelligentInput fieldName="FirstName" size="22" maxLength="20"/>   <lib:IntelligentInput fieldName="LastName" size="22" maxLength="20"/> </lib:IntelligentForm> 

You can also call these custom tags without using a tag prefix, like this:

 <cfimport taglib="mylib" prefix=""> <IntelligentForm formName="MyForm">   <IntelligentInput fieldName="SSN" size="12" maxLength="11"/>   <IntelligentInput fieldName="FirstName" size="22" maxLength="20"/>   <IntelligentInput fieldName="LastName" size="22" maxLength="20"/> </IntelligentForm> 

<cfimport> gives you an advantage in large applications that use many custom tags from various sources. That's because you can isolate custom tags with identical names yet different logic into separate directories, import each directory using a different tag prefix, and call identically named tags without one tag occluding the other since you're effectively isolating each custom tag library into its own namespace.

But before you go changing all your custom tag calls to using <cfimport> syntax, be aware of these disadvantages:

• <cfimport> is a compile-time directive, which means you must place a call to <cfimport> on every page on which you intend to use <cfimport> syntax to call a custom tag.

• Because <cfimport> is processed at compile time, you cannot use any ColdFusion expressions as the values of attributes, which means that you must hard-code the value of taglib every time you call <cfimport>. This sometimes makes it difficult to migrate from development to staging and then to deploymentespecially in shared hosting environments where a mapping name has already been assigned to another application.

That wraps up our review of custom tag basics. If you need more, an excellent resource is Macromedia ColdFusion MX 7 Web Application Construction Kit (referenced earlier in the chapter), which gives thorough coverage of custom tag basics.

TIP

Looking for custom tags? The best place to start is the Developer Exchange on macromedia.com. This is an online exchange containing hundreds of freeware, shareware, and commercial custom tags for to download. The Developer Exchange is also a great place to publish any custom tags you write that you want to share with the rest of the ColdFusion development community.

Now that you've been through this review of custom tag fundamentals, you're probably thinking, "So what's the big deal about custom tags, anyway? They seem like glorified CFINCLUDEs to me." And up to this point, you're rightsimple custom tags are little more than separate templates of stand-alone code that can modify their behavior by changing the values of the attributes with which they are called.

Advanced custom tags, however, are to this day one of the most powerful development tools in all of ColdFusion. You can build complete application subsystems of highly reusable code that adapt to the environments in which they are deployed. Well-written advanced custom tags can be instantly reused from application to application with little or no modification at all.

In the remainder of this chapter you'll learn how to leverage the hidden workings of advanced custom tags, and you'll put that knowledge to use by building step by step a family of related custom tags that can easily adapt to handle multiple tasks in an application. The chapter also includes a number of diagrams and dumps of complex objects to help you visualize the process flow and data flow between related custom tags.

Let's go!