Using Tag Libraries

ColdFusion programmers have CFML custom tags. JavaServer Pages (JSP) programmers have something similar: JSP custom tag libraries, often called taglibs for short. As of ColdFusion MX 7, you should be able to use any taglib in your ColdFusion pages, as well. So, if you know that a solution for a particular task has already been created by some JSP developer as a tag library, you can just reuse it in your CFML pages rather than having to reinvent the proverbial wheel.

To work with a tag library, you follow these basic steps:

1.	Find a taglib that looks interesting, then download or install it. The taglib will most likely come in the form of a .jar file, often with an accompanying .tld file.
2.	Use the new <cfimport> tag to make the tag library available to your ColdFusion page. This is the CFML equivalent to the <%@ taglib %> directive that would normally be used to make the tag library available to a JSP page.
3.	Use the tags provided by the tag library, using the same basic syntax as in a JSP page.

Finding Tag Libraries

Before you can start using tag libraries with ColdFusion, you first need to find and obtain the taglib that you want to use. You may already have one in mind, but if not, here are a few Web sites where you can look for interesting libraries:

• The Jakarta Tag Library project, at jakarta.apache.org/taglibs

• The JSPTags.com site, at www.jsptags.com

• The SourceForge site, at http://sourceforge.net

• The OpenSymphony site, at www.opensymphony.com

Installing the Tag Library

Whether you're using a tag library that you downloaded from a third party or a tag library that was developed in house, the library will most likely come to you as a Java Archive (.jar) file. There may or may not be an accompanying Tag Library Descriptor (.tld) file. Place the file or files in the WEB-INF/lib folder, which should be located within your Web server's (or virtual Web server's) document root folder.

NOTE

If there is no WEB-INF/lib folder, create it by first creating a folder called WEB-INF, then a subfolder called lib. Also, as far as ColdFusion is concerned, you can place the folder in other locations as well, but it's customary to place tag library files in WEB-INF/lib. The tag library may be expecting it internally.

In most cases, that's all you need to do to install the library. It's also possible that additional .jar files, .property files, or other files may need to exist in order for the tag library to work properly; the tag library's documentation should make all this clear to you.

NOTE

The installation instructions for many tag libraries discuss making a new entry for the library in the server's WEB-INF/web.xml file. Just ignore any discussion of altering the web.xml file.

NOTE

If you are using a commercial tag library, it may come with a formal installation program. In such a case, just run the installation, providing the installer with the location of the WEB-INF/lib folder if prompted. The installer probably expects you to be using the library with JSP pages rather than ColdFusion, so it's possible that you'll need to move the .jar and/or .tld files after installation.

Importing the Library with <cfimport>

Now that the tag library files have been placed into their correct location, you should be able to import the library with the <cfimport> tag, using the syntax described in Table 29.4.

Table 29.4. <cfimport> Tag Syntax for Importing Tag Libraries

ATTRIBUTE	DESCRIPTION
TAGLIB	The location of the tag library file(s). If the tag library came with a separate .tld file, provide that location. Otherwise, use the path to the .jar file. Assuming that you placed the files in the WEB-INF/lib folder, you would use TAGLIB= "WEB-INF/lib/taglib.tld" or TAGLIB="WEB-INF/lib/ taglib.jar", replacing the taglib part with the actual filenames in question.
PREFIX	A prefix to use for referring to the tags in the tag library. For the remainder of the current ColdFusion page, you will be able to refer to the tags in the form <prefix:tagname>, where the prefix is the value you supply here.

TIP

You can provide any identifier you want as the PREFIX, as long as it is not a reserved word, but there will usually be a customary prefix for the tag library you're using (often the same prefix used in the documentation or examples that come with the library). I recommend that you use the customary prefix whenever possible.

NOTE

It's worth noting that the <cfimport> tag can be used in a few other ways as well, most importantly to import a set of CFML custom tags into their own namespace. This chapter is concerned only with using <cfimport> to import JSP tag libraries; please consult the ColdFusion documentation for information about using this tag with CFML custom tags.

Using the Tag Library's Tags

Once you've imported a tag library with <cfimport>, you can use the tags in the library using syntax that is very similar to the way the tags are used in JSP pages. Say you're using a fictional tag library that you have imported using the prefix cars, like so:

 <cfimport  taglib="/WEB-INF/lib/cars.tld"  prefix="cars"> 

If this fictional library includes a tag called displaycar, you'd include it in your ColdFusion page like this:

 <cars:displaycar /> 

Like custom tags, most JSP custom tags accept or require certain attributes. If the displaycar tag has attributes called make and model, you could call the tag with syntax similar to the following:

 <cars:displaycar make="Ford" model="Mustang" /> 

Note the trailing slash before the end of the tag in these snippets. This is standard XML-style shorthand for an opening and closing tag. If you wish, you can write the opening and closing tags explicitly, like so:

 <cars:displaycar make="Ford" model="Mustang"></cars:displaycar> 

Some JSP tags will expect you to place some type of content between the opening and closing tags. Of course, the result will depend on the actual tag you're using, but the syntax is pretty much what you would expect:

 <cars:displaycar make="Ford" model="Mustang">  ...any content or nested JSP tags can appear here... </cars:displaycar> 

Using the Jakarta Image 1.1 Tag Library

Keeping with our earlier theme of creating a photo album, let's assume that in one of your design meetings you are asked to create functionality that can overlay images or text on top of another imagefor example, to identify a thumbnail that is new to a tag gallery, or to put a time/date stamp or watermark on the image. Adding this sort of functionality might require some serious Java programming, but being the sharp and savvy developer you are, you find a tag library at the Apache Jakarta site that does exactly what you need.

The binaries for the tag library are at:

http://cvs.apache.org/builds/jakarta-taglibs-sandbox/nightly/projects/image/

and you'll need to download the files and unpack them. You should see four files:

 image-doc.war image-examples.war taglibs-image.jar taglibs-image.tld 

You'll also need to unpack the image-examples.war (you can use WinZip) and get the pmiw.jar. Take the pmiw.jar, the taglibs-image.jar, and the taglibs-image.tld and place them all in your web_root\WEB-INF\lib.

For this example, you could use any two images, but we have taken the liberty of downloading an image of the ColdFusion MX 7 product box, coldfusion.jpg, and an image showing the word new, filename new.jpg. When you run the code in Listing 29.7, you should see in your browser an image of the ColdFusion box overlaid with an image of the word new in the right corner as seen in Figure 29.4.

Listing 29.7. overLay.cfmImporting and Using a JSP Tag Library

 <cfimport taglib="/WEB-INF/lib/taglibs-image.jar" prefix="taglibs-image">  <taglibs-image:image src="/books/2/449/1/html/2/coldfusion.jpg"         dir="generated"         name="new-coldfusion.jpg"         refresh="true"         attributes="border='0' alt='a sample dynamic image'">     <taglibs-image:grayscale/>     <taglibs-image:overlay x="55%" y="60%">         <taglibs-image:image src="/books/2/449/1/html/2/new.jpg" >             <taglibs-image:resize scale="100%" />             <taglibs-image:transparency level="5" />         </taglibs-image:image>     </taglibs-image:overlay>     <taglibs-image:border width="5" height="3"             color="0x005d00"/>     <taglibs-image:resize bestfit="true" width="200" height="400"/> </taglibs-image:image> 

Figure 29.4. Using the Jakarta Image 1.1 Tag library to overlay one image on top of another.

As you can see, this listing uses several different tags from an image tag library: <taglibs-image:image>, <taglibs-image:grayscale>, <taglibs-image:overlay>, <taglibs-image:resize>, and <taglibs-image:border>. Here's what's going on: Image file "coldfusion.jpg" is loaded (each time, since the refresh is set to "true"). Otherwise, it checks for "new-coldfusion.jpg" in the "generated" directory and loads it. Next, we use <taglibs-image:grayscale> to convert the image to grayscale. Then the "new.jpg" is overlaid on the coldfusion.jpg image at location 55% right and 60% below the top-left corner (these percentages are of the base image's current "width" and "height", respectively); this is done using the <taglibs-image:overlay> tag. The image, which is now a combination of the coldfusion.jpg and the new.jpg, is then resized and outputted to the generated directory as new-coldfusion.jpg. All of that was done with just a few simple tags!

If you look closely at the tags we are using, you can see how similar the syntax and structure are to CFML. Many developers find that working with JSP tag libraries from CFML is very intuitive.

Explore the various open-source Java tag libraries; you'll find an amazing number of excellent libraries to solve almost any problem. With the combination of ColdFusion MX 7 and the Java tag libraries, there is very little you cannot accomplish.

Using CFML Expressions in JSP Tag Attributes

Some JSP tags will let you provide dynamic expressions (variables and such) to their attributes; others will not. Some tag libraries allow you to use expressions in tag attributes (or at least some of them, depending on their purpose). In general, the documentation for the taglib will let you know which attributes accept dynamic expressions and which do not.

Inspecting the Tag Library Descriptor

Another way to find out which attributes accept dynamic expressions is to look in the Tag Library Descriptor (TLD) file for the library. As mentioned earlier, you may receive the TLD as a separate .tld file, in which case you can open it up in a text editor such as Macromedia Dreamweaver or Windows Notepad. If the taglib doesn't have a separate .tld file, then the TLD should be located inside the .jar file. Use a ZIP utility such as WinZip or PKZIP to open the .jar file; then locate the TLD (it should be packed into the .jar with the pathname /meta-inf/taglib.tld) and view it with your text editor.

The TLD will contain a <tag> for each tag in the library; within each <tag> there will be an <attribute> element for each of the tag's attributes. If the <attribute> contains a <rtexprvalue> of true, then that attribute of that tag will accept dynamic expressions (such as variables). If <rtexprvalue> is false or not present, then only static values can be provided to the attribute.

Listing 29.8 shows how you can supply dynamic attributes to JSP tags that support them. This example uses the Image tag library, which was written by Marcello P. Lima of parallaxis.net as an aid for JSP developers in determining the width and height of images on-the-fly. Think of it as the JSP version of the ImageInfo class that was used in Listings 29.5 and 29.6. In fact, this taglib uses ImageInfo internally; it's a taglib wrapper around ImageInfo in much the same way as the Listing 29.6 code was a UDF wrapper around the same class.

NOTE

Before Listing 29.8 will work, you must place the image_taglib.jar file into your server's WEB-INF/lib folder, as explained in the earlier section "Installing the Tag Library." You can get the latest version of the .jar from Marcello's site at http://parallaxis.net/code/taglib/image_taglib.php. For your convenience, the image_taglib.jar file has also been included with this chapter's listings.

Listing 29.8. TagLibImage.cfmProviding Dynamic Attributes to Tags from a Tag Library

 <!---  Filename: TagLibImage.cfm  Author: Nate Weiss (NMW)  Purpose: Demonstrates the use of CFML expressions in JSP Tag atttributes ---> <!--- Import the tag library ---> <cfimport   taglib="/WEB-INF/lib/image_taglib.jar"   prefix="image"> <!--- For this example, just list the files in the images subfolder ---> <cfset ImageDir = ExpandPath("images")> <!--- Get a listing of image files, as a query object ---> <cfdirectory   action="List"   directory="#ImageDir#"   name="Images"> <html> <head><title>Using the Image Tag Library</title></head> <body> <!--- For each file... ---> <cfloop query="Images">   <hr>   <!--- Display the image itself --->   <image:FullTag path="/ows-adv/25/images/#Images.Name#"/><br>   <!--- Display information about the image --->   image:  <cfoutput>#Images.Name#</cfoutput><br>   format: <image:FileType path="/ows-adv/25/images/#Images.Name#"/><br>   width:  <image:Width path="/ows-adv/25/images/#Images.Name#"/><br>   height: <image:Height path="/ows-adv/25/images/#Images.Name#"/><br> </cfloop> </body> </html> 

This particular tag library includes a tag called FullTag, which takes care of generating the correct HTML <img> for the image you supply to the path attribute; the generated <img> tag includes width and height attributes that reflect the actual size of the image file. The library also includes FileType, Width, and Height tags (plus some others not used in this example), all of which take path as their sole attribute.

As you can see, you are free to use static text, CFML variables, or combinations thereof when passing attributes to a JSP tag. You can use CFML functions, as well. Basically, you can use nearly any expression that would normally appear after the = sign in a <cfset> tag.

NOTE

The documentation and examples for a tag library will generally show JSP-style variables and expressions being used in tag attributes, in a form similar to path="images/{$name}". Just keep in mind that the curly braces can be replaced with # signs, and that CFML-style expressions in general can be used.

NOTE

Thanks to Marcelo P. Lima for permission to use and distribute this tag library with the listings for this book.

Creating Your Own JSP Tag Libraries

As you have learned in this section, JSP-style tag libraries can be used interchangeably in JSP pages and ColdFusion pages, using more or less the same syntax. If your shop uses both technologies, then you may want to consider creating some of your own tag libraries. That topic is beyond the scope of this book, but you can learn all about it in nearly any book or online reference about Java Server Pages.

You might also consider installing a free developer version of Macromedia JRun, which includes complete documentation on creating tag libraries. At the time of this writing, that portion of the JRun documentation was also available as a separate PDF document at www.macromedia.com/support/jrun/documentation/en/jrun/.