Calling Custom Tags

Creating a Custom Tag is the easy part. Like any other ColdFusion template, a simple Custom Tag is merely a bunch of CFML code saved into a file with a .cfm extension.

Custom Tags are really defined by how they are accessed. Most ColdFusion pages are run when the Web server passes them to the ColdFusion application server. Custom Tags are run when they are called from within another ColdFusion template.

NOTE

In Chapter 5, "Redirects and Reuse," you were introduced to the <cfinclude> tag. This tag calls another page to be run. However, it should not be confused with a Custom Tag.

Simple Syntax (cf_)

After you've created a file that you will use as a Custom Tag, you need a way of calling that page to run. There are a number of ways to do this.

The easiest method is to use simple syntax. If you have a Custom Tag template that you have named customtag.cfm, you can simply call it by typing <cf_customtag>. Notice that the filename is prefixed with <cf_ and that the .cfm extension is dropped.

When using simple syntax, ColdFusion automatically looks for the Custom Tag in the same directory as the calling template. If it doesn't find the Custom Tag there, it searches a special directory that is created by ColdFusion upon installation (on Windows machines this is usually c:\cfusionmx7\customtags\).

TIP

ColdFusion always looks for Custom Tags in the current directory before it searches the CustomTags directories. By default the Custom Tags directory are under the ColdFusion root directory, but additional Custom Tag directories may be added using the ColdFusion Administrator.

<cfmodule>

You can also call a Custom Tag using the built-in ColdFusion tag <cfmodule>. <cfmodule> lets you use two separate methods to call the Custom Tag.

The first method works only if the Custom Tag is in the special directory c:\cfusionmx7\customtags\. The syntax is as follows:

 <cfmodule name="Developers.Emily.Header"> 

The value Developers.Emily.Header calls the header.cfm Custom Tag in a directory called Emily, which is in a directory called Developers. Developers is a subdirectory of the Custom Tags directory.

TIP

If you're in a hosted environment, your ISP might allow you access to your own directory inside c:\cfusionmx7\customtags\. The ColdFusion application server recursively searches through the CustomTags directory and all its subdirectories until it locates the Custom Tag in question. This can be a problem if two users being hosted on the same server have given identical names to their Custom Tags. For instance, header.cfm is a common Custom Tag name. If one person has her Custom Tag template in c:\cfusionmx7\customtags\Developers\Emily\header.cfm and another has his Custom Tag template in c:\cfusionmx7\customtags\Developers\Matt\header.cfm, there will be a problem when calling this Custom Tag using simple syntax like <cf_Header>. When Matt calls <cf_Header> from within his own application, he will always run the header.cfm Custom Tag in the Emily directory. This will be the first file by that name that ColdFusion encounters, because it recursively searches alphabetically through the subdirectories of c:\cfusionmx7\customtags\. Using <cfmodule> with the NAME attribute enables you to explicitly specify which Custom Tag in c:\cfusionmx7\customtags\will run.

<cfmodule> gives us an even more flexible means of calling a Custom Tag. So far, we have been restricted to putting our Custom Tags in the same directory as the calling page, or in the c:\cfusionmx7\customtags\directory. Using the template attribute of <cfmodule>, you can place a Custom Tag anywhere and call it using either a relative path or a ColdFusion mapping.

 <!--- using a relative path ---> <cfmodule template="../customtags/header.cfm"> <!--- using a ColdFusion mapping ---> <cfmodule template="/customtags/header.cfm"> 

ColdFusion mappings were introduced in Chapter 5, "Redirects and Reuse."