How to Use Custom Tags

It's sometimes said that lazy people make the best programmers because they tend to solve problems by taking advantage of proven, working solutions that are already in place. Lazy or not, it's often a great idea to reuse work others have done. Before you get started on a project or tackle a piece of code, see whether someone has already written a custom tag that does what you need. If so, you can just use it. It's almost like getting the entire ColdFusion developer community to help you write the code for your application.

Finding Tags on the Developer Exchange

You can look for custom tags online in a number of places. By far the largest and most popular is the Developer Exchange portion of Macromedia's own Web site, which offers thousands of custom tags for the taking. In many situations, a simple search will reveal that someone else has already solved your problem for you.

The Developer Exchange is located at http://www.macromedia.com/cfusion/exchange/index.cfm. You can run keyword searches to find tags or browse through tags by category, popularity, or date of posting (Figure 23.1).

Figure 23.1. The Developer Exchange on the Macromedia Web site is a great place to look for publicly available custom tags.

NOTE

Other items are available besides custom tags at the Developer Exchange, so when you run a search, be sure to specify that you want custom tags only.

NOTE

Another good place to look for custom tags is the CFXtras site, at http://www.cfxtras.com.

How to "Install" a Custom Tag

A single ColdFusion template (.cfm) file represents each custom tag. Generally, the .cfm file and some type of documentation are placed together in a .zip file for easy downloading.

There isn't really any special installation step. All you have to do is place the custom tag template into the special CustomTags folder on your ColdFusion server's drive.

To install a custom tag, follow these steps:

1.	Find the custom tag you want and download the .zip file that contains the tag. If you have been given the .cfm file directly rather than compressed in a .zip file, go to step 3.
2.	Open the .zip file, using a utility such as WinZip from http://www.winzip.com, and find the custom tag template (.cfm) file itself. The template's filename will be the name of the custom tag, without the cf_ prefix. So if you have downloaded a custom tag called <cf_PlaceOrder>, you should look for a file called PlaceOrder.cfm.
3.	Place the custom tag template file into the CustomTags folder, located within the CFusionMX folder on your ColdFusion server's drive. In a default Windows installation, this is the c:\CFusionMX\CustomTags folder.

That's it. The custom tag is now installed, and you can start using it in your code.

TIP

If you want to organize the custom tag templates you download (or write) into subfolders within the CustomTags folder, go ahead. As long as they are somewhere within the CustomTags folder, ColdFusion will find and use them in your applications.

NOTE

If you don't have access to the special CustomTags folder, or if you plan to use the custom tag in just one or two of your own templates, place the custom tag template into the folder where you plan to use it. See "Placing Custom Tags in the Current Directory," later in this chapter.

NOTE

You can move the location of the special CustomTags folder, or create additional special custom tag folders. See "Changing the Custom Tag Search Path," later in this chapter.

NOTE

Some custom tags might require other tags or files to be present as well. The documentation that comes with the tag should point out what you need to know.

NOTE

If, after you download a tag, you find that no ColdFusion template exists with the appropriate filename, you may have downloaded a CFX tag, which is different from a CFML custom tag. CFX tags are compiled with a language such as Java or C++ and must be registered in the ColdFusion Administrator before you can use them. Instead of a template (.cfm) file, they are represented by one or more Dynamic Link Library (.dll) or Java Class (.class) files. See Chapter 29, "ColdFusion Server Configuration," for details.

Using Custom Tags

After you install a custom tag by placing its template in the special CustomTags folder, it's ready for use in your code. To help you get your feet wet, this book's CD-ROM includes two custom tags in the folder for this chapter. The custom tags are .zip files, just as if you had downloaded them from the Developer Exchange (see Figure 23.1) or some other source. Table 23.1 provides information about the tags.

Table 23.1. Third-Party Custom Tags Included on the CD-ROM for This Chapter

CUSTOM TAG	WHAT IT DOES
<cf_CoolImage>	Creates a rollover image on the current page. When the user hovers the pointer over the image, it changes, usually to a glowing or highlighted version of the original image.
<cf_TwoSelectsRelated>	Places two correlated <select> lists or drop-down lists on the current page. When the user selects an item in the first list, the choices in the second list change.

Before you try the following code listings, install these tags according to the directions in the last section. That is, extract the CoolImage.cfm and TwoSelectsRelated.cfm templates from the .zip files included on the CD-ROM, and place them in the special CustomTags folder on your ColdFusion server.

Using <cf_CoolImage>

Users and graphic designers love rollover images, in which an image changes when you move your pointer over it, usually to suggest that the image is live and canshould! must!be clicked. Normally, you must write or borrow some JavaScript to get this done.

Listing 23.1 shows how you can use the <cf_CoolImage> custom tag to easily place a rollover image on one of your pages. If you visit this listing in your Web browser, you will see that the image does indeed roll over when you move the pointer over it. (Be sure you have copied over the images from the CD-ROM.)

Listing 23.1. UseCoolImage.cfmUsing <cf_CoolImage> to Create a Rollover Effect

 <!---   Filename: UsingCoolImage.cfm  Author: Nate Weiss (NMW)  Purpose: Demonstrates how to use a custom tag ---> <html> <head><title>Using a Custom Tag</title></head> <body> <h2>Using a Custom Tag</h2> <p>Hover your mouse over the logo, baby, yeah!</p>  <!--- Display a "Mouse Rollover" Image via groovy --->  <!--- <CF_CoolImage> Custom Tag by Jeremy Allaire --->  <!--- The tag will include all needed code for us --->  <cf_CoolImage  imgName="MyImage"  src="/books/2/448/1/html/2/Logo.gif"  oversrc="/books/2/448/1/html/2/LogoOver.gif"  width="300"  height="139"  border="0"  href="http://www.macromedia.com/"  alt="Click for Macromedia Home Page"> </body> </html> 

The attributes for <cf_CoolImage> are fairly self-explanatory and are not detailed here (you can look them up on the Developer Exchange if you want). The purpose of this listing is to show you how to use a custom tag in your code and give you a sense of what you can do with custom tags.

Thinking About Custom Tags as Abstractions

If you visit UseCoolImage.cfm and then view its HTML code using your browser's View Source option, you will see that all the appropriate JavaScript and HTML code has been generated for you, based on the attributes you provided to the tag in Listing 23.1. I don't have the space here to go into a line-by-line explanation of the generated code, but the custom tag takes care of writing it correctly for you, so you don't really need to understand it.

In fact, that's the great thing about the tag. It lets you focus on the task at handinserting a rollover imagewithout worrying about the actual code you would normally need to write. You can think about the rollover at a higher, or more abstract, level. Developers often refer to this type of phenomenon as abstraction.

The more concepts or coding steps a tag wraps into one task-based or goal-oriented chunk, the more fully that tag becomes a helpful abstraction of the underlying concepts. You are free to make your custom tags do whatever you want them to and have them represent whatever level of abstraction you feel is appropriate.

NOTE

If you want to know more about the JavaScript code generated by <cf_CoolImage>, you can easily decipher it with the help of a JavaScript reference text or online tutorial. You can also refer to the JavaScript reference built into Dreamweaver MX.

Using <cf_TwoSelectsRelated>

To give you a sense of the variety of effects and behaviors custom tags offer, here is another example, this time using the <cf_TwoSelectsRelated> custom tag, also included on this book's CD-ROM. This custom tag enables you to add two <select> lists quickly to your page; these lists become actively correlated via JavaScript. Again, the goal of the tag is to present developers with an abstraction of the basic idea of related inputs, without making each developer concentrate on getting the tedious JavaScript code exactly right.

Listing 23.2 shows how to use the tag in your own applications. Here it displays a list of ratings. When the user clicks a rating in the first list, the corresponding list of films is displayed in the second list (Figure 23.2).

Listing 23.2. UsingTwoSelectsRelated.cfmDisplaying Correlated Information

 <!---   Filename: UsingTwoSelectsRelated.cfm  Created by: Nate Weiss (NMW) Purpose: Demonstrates the use of the TwoSelectsRelated custom tag.  ---> <!--- Get ratings and associated films from database ---> <cfquery datasource="ows" name="getRatedFilms">  SELECT  r.RatingID, r.Rating,  f.FilmID, f.MovieTitle  FROM FilmsRatings r INNER JOIN Films f  ON r.RatingID = f.RatingID  ORDER BY r.RatingID, f.MovieTitle </cfquery> <html> <head><title>Using a Custom Tag</title></head> <body> <h2>Using a Custom Tag</h2>  <!--- This custom tag will only work in a form --->  <form>  <!--- Show ratings and films in correlated SELECT lists --->  <!--- via custom tag, which generates all needed script --->  <cf_TwoSelectsRelated  query="getRatedFilms"  name1="RatingID"  name2="FilmID"  display1="Rating"  display2="MovieTitle"  size1="5"  size2="5"  forcewidth1="30"  forcewidth2="50">  </form> </body> </html> 

Figure 23.2. Some custom tags create user-interface widgets, such as these related select lists.

This code queries the Orange Whip Studios database to get a list of ratings and related films. The query variable is then provided to the query attribute of the <cf_TwoSelectsRelated> custom tag. When the tag executes, it outputs two ordinary <select> tagsthe first with a name attribute as provided to the name1 attribute of the custom tag, and the second with a name attribute as provided to name2. The appropriate number of <option> tags is also generated for each <select> list, with each <option>'s display text and value attribute coming from the results of the getratedFilms query, as specified by the value1, value2, display1, and display2 attributes provided to the custom tag. In addition, the appropriate JavaScript code is generated to give the lists an actively related effect. If you visit Listing 23.2 in your browser, you can test the behavior. And if you view the page's source code using your browser's View Source option, you will see that about 75 lines of HTML and JavaScript code were generated for you, depending on the actual records in the database.

Again, the purpose of this listing isn't to teach you the syntax for this custom tag in particular (you can learn more about that in the tag's documentation, included in the .zip file on the CD-ROM). It's to give you an idea about how to use custom tags and the types of tasks they can do for you.

Changing the Custom Tag Search Path

As you have already learned, when you use a custom tag in one of your ColdFusion templates, the ColdFusion Application Server looks in the special CustomTags folder for the corresponding custom tag template. So when you use the <cf_TwoSelectsRelated> custom tag in your own code, ColdFusion looks for the TwoSelectsRelated.cfm file in the c:\ CFusionMX7\CustomTags folder (assuming you are running ColdFusion on a Windows machine and that you accepted the default installation options).

If you want, you can change the location of the special CustomTags folder, or specify additional folders for ColdFusion to look in. Say you want to place the custom tags for the Orange Whip Studios project in a folder called C:\OrangeWhipCustomTags, instead of C:\CFusionMX7\CustomTags. All you need to do is add the new folder to the custom tag search path. The custom tag search path is a list of folders ColdFusion looks through whenever you call a custom tag in one of your application templates. When you first install ColdFusion, only one folder is in the search path (the CustomTags folder within CFusionMX7).

After you add a new folder to the search path, you are free to place some custom tags in the new folder and others in the original CustomTags folder. Now, when you first refer to a custom tag in your own templates, the ColdFusion server first looks in the special CustomTags folder (and its subfolders) and then in your newly specified folder (and any of its subfolders).

NOTE

If all this path searching sounds like a lot of overhead for ColdFusion to incur, don't worry. Once ColdFusion successfully finds a custom tag template in the search paths you have configured, it remembers the template's location for all subsequent requests (until the server is restarted or until the server's template cache is exhausted). In other words, the custom tag search path is searched only once per custom tag per server restart, so there isn't much of a penalty for adding folders to the search path. Remember that if you test a custom tag and then move it, you will need to restart ColdFusion to have it "find" the custom tag again.

To add a folder to the custom tag search path, follow these steps:

1.	Navigate to the Custom Tag Paths page of the ColdFusion Administrator.
2.	Specify the path and name of the folder you want to add to the custom tag search path (Figure 23.3). You can use the Browse Server button to avoid having to type the folder's path manually. Figure 23.3. You can add folders to the custom tag search path with the ColdFusion Administrator.
3.	Click the Add Path button. The new folder appears in the list of custom tag paths.
4.	Now you can place your custom tag templates in the folder you just added or in the original.

You can also remove folders from the custom tag search path using the Delete button shown in Figure 23.3. After you remove a folder from the search path, ColdFusion will no longer find custom tag templates in that folder.

NOTE

Throughout this chapter, you will find instructions to save files in the special CustomTags folder. Whenever I mention the CustomTags folder, you can also use any folders you have added to the custom tag search path.

Placing Custom Tags in the Current Directory

Sometimes placing custom tag templates in the special CustomTags folder isn't possible or convenient (see the section "How to 'Install' a Custom Tag," earlier in this chapter). For instance, if an Internet Service Provider is hosting your ColdFusion application, you might not have access to the ColdFusion Administrator or the CustomTags folder.

In such a situation, you can place the custom tag template (CoolImage.cfm, for example) in the same folder as the template you want to use it in. When ColdFusion encounters the custom tag in your code, it first looks for the appropriate file in the current folder. (It doesn't automatically look in the parent folder or subfolders of the current folder.) If ColdFusion can't find the .cfm file for the custom tag in the current folder, it then looks in the special CustomTags folder (and its subfolders).

Placing the custom tag template in the current folder is a good idea when:

• You don't have access to the special CustomTags folder.

• You are still developing and testing the custom tag. Just don't forget to restart ColdFusion so it can "find" it again.

• You know you won't use the custom tag extensively, so you don't mind its being available only to code templates in the current folder.

• You want to simplify the distribution of your application and would rather not require that the custom tag template be dealt with separately.

These situations aside, it's smart to use the special CustomTags folder described earlier in this chapter. You will find all your custom tags in one place, and you won't have to maintain multiple copies of the same custom tag template (one for each folder in which you want to use the tag).