Chapter 53: Creating ColdFusion MX Custom Tags

---

 Download CD Content

Like all good programming languages, ColdFusion is extensible, meaning that if it doesn't have the tools you need to complete a job at hand, you can create your own. One of the easiest ways to do so is through the use of custom tags, or snippets of CFML code that can be custom-written once, then used many times throughout one or more applications. As with many ColdFusion features, building custom tags is easy; in fact it's just like creating a standard template. In this chapter you'll learn about the concepts behind custom tags, build a simple tag to compute sales tax, and learn more about Macromedia's Developers' Exchange, where you'll find hundreds of custom tags written by others and available for use in your own applications.

Understanding Custom Tags

To understand how custom tags work and why you'd want to use them, start by considering an online store. Users navigate through a catalog selecting products and arrive at a checkout area where they view their product total — sales tax included. After confirming their order and providing their user information, users choose a shipping method and see a new total including shipping charges and, again, tax. Finally, they provide their credit card data and their card is charged for the total, once again including tax.

This type of application is ideal for ColdFusion MX, and in fact there are several ready-made shopping cart applications available in the Macromedia Developers' Forum. However, for the purposes of this chapter let's focus on just one element of the application — computing sales tax. Note from the previous description that there are no less than three pages upon which tax must be computed and displayed to the user. One solution would be to simply include identical tax-computation code in each of the three pages, but as you might have guessed, that's inefficient programming.

A wiser solution is to use a ColdFusion custom tag. You could write the tax computation code once, save it in a separate file as a custom tag, and then call it from each of your three store pages.

Note 

"Calling" a custom tag simply means referring to its filename using a special naming convention, about which you'll learn more in the next section.

By breaking the tax computation code out into a separate file, you'd be ensuring two things:

• That your store pages' source would be easier to understand and troubleshoot, because the more complex tax computation code isn't included

• That you could reuse the tax computation code elsewhere on your site — or even in a another application — simply by calling the tag.

These are the two primary reasons for using custom tags, although you'll learn a few more later in this chapter.

Note 

Custom tags are similar to the concept of subroutines, which are found in many programming languages. Both allow developers to break out blocks of code either to simplify a program's source, or to re-use it with other programs.

Saving custom tags

Once you've broken some code out into a custom tag, you have to be careful where you save it: ColdFusion needs to know where it resides. There are three options:

• You can simply save the custom tag in the same folder as the pages that call it. This method is the easiest, but it isn't always practical in cases where the calling templates may reside in different folders on your site.

• You can save the tag in ColdFusion MX' default tag directory, usually c:\CFusionMX\CustomTags. Doing so makes the tag accessible by any template on your site(s).

• You can use ColdFusion Administrator to define a new path or paths where custom tags will be saved. You do so by accessing the Custom Tag Paths link in Administrator's Extensions section, as shown in Figure 53-1.

  
  Figure 53-1: Defining custom tag paths in ColdFusion Administrator

Calling custom tags

You'll learn more about creating custom tags in later sections, but first let's examine how they're called. After you've created a custom tag, you use it much the same way as any CFML tag, with the exception that most custom tags don't use a closing tag. Listing 53-1 shows how the tax computation tag described previously might be called in a template.

Listing 53-1: total_purchase.cfm

 <html> <head> <title>Your Total Purchase</title> <meta http-equiv="Content-Type" content="text/html; charset=iso- 8859-1"> </head>     <body> <!---set values for product total and state (in a complete application,  these would probably come from totaling the user's purchases and the  user's form input, respectively)---> <cfset product_total = 3.25> <cfset state = "CA">     <!---call a custom tag to compute tax---> <cf_tax_compute product_total="#product_total#" state="#state#">     <!---compute grand total based on "tax" variable returned by custom  tag---> <cfset grand_total = 3.25 + tax>     <!---display output to user---> <cfoutput>      Your total purchase, including tax, comes to  #DollarFormat(grand_total)#. </cfoutput>     </body> </html> 

The first line in Listing 53-1 calls the custom tag and supplies two attributes, product_total and state. As you'll learn when you later build this tag, it is written to accept these two attributes and then return a variable called tax, which will contain the total tax for the user's purchase, based on the user's state. This variable is used on the second line of the snippet to compute the user's grand total.

The tag reference begins with the prefix cf (the letters cf followed by an underscore). This tells ColdFusion that the tag you're referring to is a custom one, rather than a standard tag in the CFML library. The actual filename of the tag is  tax_compute.cfm, but by calling it with the cf_ prefix and no .cfm extension, you specify that it is a custom tag.

Tip 

Another extensibility feature offered by ColdFusion is the use of ColdFusion Extensions (CFXs). Like custom tags, CFX tags are designed to perform tasks not possible with standard CFML. Unlike custom tags, which are written in CFML, CFX tags are written in C++, Java, or Delphi. For more information, see your ColdFusion documentation.

---