ADVANCED macromedia COLDFUSION MX 7 Application Development [Electronic resources] نسخه متنی

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.

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). 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.