Installing and using custom tags
If you have never installed a custom tag before, it is very important that you read and understand this article. The information here applies to all custom tags from ESWsoftware as well as other vendors.
Custom tags are a common way to encapsulate sophisticated functionality. How you install and subsequently call your custom tags depends on your server environment. There are three different ways to call custom tags. This article will help you choose the appropriate way for your environment.
Method 1: cf_
The most well-known technique for calling a custom tag is to prefix the tag name with
cf_ like this:
<cf_mytag myAttribute="1"> ... </cf_mytag>
This is a very tidy technique, generating easy-to-read code. Your custom tags look just like built-in ColdFusion tags, except for the extra underscore. However, for this technique to work, your tag must be located in either the same folder as your calling template or in your server's custom tags folder.
Locating the tag in the same folder is generally not very useful as you will usually want to share the tag, calling it from many different places.
If you have full server access, you may place the tag in the server's custom tags folder. On CFMX servers, this is usually
C:\CFusionMX\CustomTags\. On CF5 servers, this is usually
However, if you are using a shared server that hosts many websites, you may not have access to your server's custom tags folder. So for shared servers, this technique is not very suitable.
Method 2: cfmodule
With this technique, you use the
cfmodule tag to call your custom tag, like this:
<cfmodule template="somepath/mytag.cfm" myAttribute="1"> ... </cfmodule>
template attribute supplies a relative or mapped path to your tag, which could be located anywhere. This technique will work on any server, but it is not very elegant. It also becomes confusing if you are using nested custom tags. Look at this example:
<cfmodule template="somepath/mytag.cfm" myAttribute="1"> <cfmodule template="somepath/myothertag.cfm"> ... </cfmodule> <cfmodule template="somepath/yetanothertag.cfm"> </cfmodule>
Do you know which tag the final
</cfmodule> is closing? It's actually closing
yetanothertag even though that was probably not the programmer's intention. Here,
mytag isn't getting closed at all. Since closing
cfmodule tags always looks the same, ColdFusion Server does not know which custom tag you want to close, but it guesses you want to close the one you opened most recently.
So if you work with nested custom tags using
cfmodule, you should be sure to close all tags. You can close your tag with
</cfmodule> (just like HTML) or you can use a special empty element notation, adding a slash just before the final angle bracket. Like this:
<cfmodule template="somepath/yetanothertag.cfm"/> (this is just like XML).
If you are calling the same custom tag many times on a page, you might like to place the path to the tag in a variable. This makes your code more readable:
<cfset mytag = "somepath/mytag.cfm"> <cfmodule template="#mytag#" myAttribute="1"> ... </cfmodule> <cfmodule template="#mytag#" myAttribute="2"> ... </cfmodule>
Method 3: cfimport
With this technique, you import a library of custom tags from any location. The library is simply a folder containing several (possibly related) custom tags. You give your library a name and use that as a prefix for your tags. This technique has several advantages: it allows you to use a tidy tag format, even on a shared server (as you don't need to use the server's custom tags folder); and it allows you to organise your tags into groups. It also has disadvantages: this technique only works on ColdFusion MX; and you must place the cfimport in every file that calls the custom tags (it does not cascade down to included files). Here is how it's done:
<cfimport taglib="somepath/" prefix="tag"> <tag:mytag myAttribute="1"> ... </tag:mytag>
cfimport is customarily placed at the very top of the file.
Deploying ESWsoftware custom tags
I recommend that you place all your ESWsoftware tags together in a folder of their own. If you are using method 1 above, you can create a folder:
C:\CFusionMX\CustomTags\ESWsoftware\ and place them all in there. If you are using method 2 or method 3, you probably have a
customtags folder already. I recommend you create a sub-folder for ESWsoftware tags and adjust your
cfimport calls to suit.
You will find client-side resources for ESWsoftware tags bundled together into a folder called
resources (or in the case of TerraForm:
terraformresources). You may place this folder anywhere on your web site. Each tag has an attribute called
resourcePath that will describe the location of this folder. Detailed instructions about setting this attribute are included with each tag.
For more information about creating and using ColdFusion custom tags, please refer to the "Creating and Using Custom CFML Tags" in the Adobe ColdFusion LiveDocs.
4 April 2004