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 C:\CFusion\CustomTags\.

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>

The 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>

The cfimport is customarily placed at the very top of the file.

Deploying ESWsoftware custom tags

It is important to understand that many ESWsoftware "tags" are quite substantial applications involving many (perhaps hundreds of) files including images, style sheets, JavaScript, user-defined functions, and localization modules. The tag itself is best thought of as the application's program interface: it's the point where your code meets and communicates with the ESWsoftware application code. It is important that the entire application is installed correctly, so please follow installation instructions carefully.

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 cfmodule or cfimport calls to suit.

Some ESWsoftware tags require client-side resources, such as style sheets, images, and JavaScript files, to be made available. It is essential that the client resources be located in a web-accessible folder. "Web-accessible" means that you could open a browser and type in the URL of your style sheet, image, or JavaScript. This is important as your browser will retrieve these files directly.

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.

Further

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

TerraForm
TerraForm is a comprehensive web forms system for ColdFusion. TerraForm provides data validation, form reuse, internationalisation / localisation, and new form fields.
eXtensible Markup Language
Uniform Resource Locator
Macromedia ColdFusion MX
ColdFusion web application server version 6 or later.
HyperText Markup Language
The coding language used to create hypertext documents for use on the World Wide Web.