Controlling Template Locations with cfmodule

Controlling Template Locations with <cfmodule>

ColdFusion provides an alternative way to use custom tags in your templates that is helpful in a number of situations. Instead of calling your custom tags using the usual <cf_ prefix, you use the <cfmodule> tag. You don't need to change anything in the custom tag template itself. You can use any custom tag with either method.

Introducing the <cfmodule> Tag

The <cfmodule> tag executes a ColdFusion template as a module, which is just another name for a CFML custom tag. Basically, you specify which custom tag you want to use with the name or template attribute. Then you add whatever additional attributes you need to pass to the tag, just as you would if you were calling the module using the normal <cf_-style custom tag syntax.

Table 23.2 explains the attributes you can supply to the <cfmodule> tag.

Table 23.2. <cfmodule> Tag Syntax

ATTRIBUTE	PURPOSE
name	The name of the custom tag you want to use, not including the <cf_ prefix. ColdFusion will look for the tag in the current folder and then the special CustomTags folder, just as it would if you were calling the custom tag normally. So instead of using <cf_PlaceOrder> in your code, you would use <cfmodule> with name="placeOrder".
template	The relative filename of the custom tag template, including the .cfm extension. You can provide a relative path to the template, just like the template attribute of the <cfinclude> tag. ColdFusion won't automatically look for the tag in the special CustomTags folder, because you are specifying the location explicitly. So instead of using <cf_PlaceOrder> in your code, you might use <cfmodule> with template="PlaceOrder.cfm". You can also use a pathname expanded from a ColdFusion mapping.
attributeCollection	Optional. A structure that contains name-value pairs to consider as attributes. See the section "Passing Attributes with attributeCollection," later in this chapter.

TIP

You provide either the name attribute or the template attribute when using <cfmodule>, but not both.

Calling Modules by Name

As mentioned previously, you can use <cfmodule> to call modules either by name with the name attribute or by template location with the template attribute. In this section, you learn about calling modules by name.

Understanding the name Attribute

At its simplest, you can use <cfmodule> to call custom tags by simply providing the name of the tag, without the customary <cf_ prefix. ColdFusion will use the same logic it does normally to find the corresponding template file (first looking in the current directory and then looking in the special CustomTags folder). Provide <cfmodule> with whatever additional attributes you would normally supply to the custom tag.

For instance, you might have a custom tag called <cf_PlaceOrder> that's normally called with two attributes called orderID and sendConfirmation, like this:

 <!--- Place order ---> <cf_PlaceOrder  order  sendConfirmation="Yes"> 

To call the tag with <cfmodule>, you would use the following:

 <!--- Place Order ---> <cfmodule  name="PlaceOrder"  order  sendConfirmation="Yes"> 

No huge advantage exists to using <cfmodule> in this way versus the traditional <cf_ method. It's simply an alternative syntax you can use if you prefer.

NOTE

One advantage that can be helpful in certain situations is that this syntax can determine the NAME attribute dynamically. For example, you could create a string variable called CallThisModule, which would hold the name of the module you wanted to call, based on whatever logic you needed. You could then call <cfmodule> with template="#CallThisModule#" to execute the module. There would be no way to accomplish this using the traditional <cf_ syntax.

Using Dot Notation to Avoid Conflicts

As you saw earlier, you can place custom tag templates anywhere within the special CustomTags folder. You can place them in the CustomTags folder itself, or you can create any number of folders and subfolders within it (see the section "Using Custom Tags," earlier in this chapter).

This is a great feature, but it can cause problems if more than one custom tag with the same filename exists. For instance, what if two of your Web applications are running on the same ColdFusion server, and both use <cf_PlaceOrder> custom tags that do different things internally? You could place one in a subfolder of CustomTags called OrangeWhip and the other in a subfolder called PetStore, but you would have no way to tell ColdFusion which one of these to use at any given time. ColdFusion would simply use the first one it found for all requests, regardless of which folder the calling template was in.

To address this type of situation, ColdFusion allows you to use dot notation in <cfmodule>'s name attribute, where the dots indicate subfolders within the special CustomTags folder.

For instance, to specify that you want to use the version of the PlaceOrder module located within the OrangeWhip subfolder of the CustomTags folder, you would use the following:

 <!--- Place order via custom tag ---> <cfmodule  name="OrangeWhip.PlaceOrder"> 

To specify that you want to use the custom tag template PlaceOrder.cfm located in a folder called Commerce within a folder called OrangeWhip in the special CustomTags folder, you would use the following:

 <!--- Place Order ---> <cfmodule  name="OrangeWhip.Commerce.PlaceOrder"  action="Delete"  film> 

As you can see, this special dot notation lets you set up hierarchies of custom tag modules, simply by establishing subfolders nested within the CustomTags folder. This can be important if you'll be installing your application on a server along with other ColdFusion applications.

NOTE

If you prefer the <cf_ syntax to <cfmodule> but are still worried about naming conflicts, you can add a consistent prefix t o each of your custom tag filenames. Instead of naming a custom tag file PlaceOrder.cfm, for instance, you might call it owsPlaceOrder.cfm. The chance of there being two tags with the same filename on the same server is very unlikely. Then you could use the tag with <cf_owsPlaceOrder> syntax. It's a less formal solution, but it will generally work.

Calling Modules by Template Location

You can also use <cfmodule> with its template attribute instead of the name attribute to explicitly specify the location of your custom tag template. Use this method in situations where you don't want ColdFusion to attempt to find your tag's template automatically (in the current folder, the CustomTags folder, or anywhere else).

NOTE

The template attribute effectively takes away the magic effect created by your custom tags, as they appear to become part of ColdFusion. So using the word module instead of custom tag starts to make more sense.

The template attribute works just like the template attribute of the <cfinclude> tag. You can provide a relative path to the template, using slashes to indicate subdirectories. You can also use the usual URL-style ../ notation to indicate the parent folder.

For instance, just as all images for the Orange Whip Studios project are stored in the images subfolder within the ows folder, you could keep all your modules in a subfolder called modules. Then, assuming you want to call a template from a different subfolder of ows (such as a subfolder called 23 for this chapter of this book), you could refer to the custom tag template using a relative path that starts with ../modules/, as shown in the following code.

So, instead of this:

 <!--- Place order ---> <cf_PlaceOrder  order  sendConfirmation="Yes"> 

or this:

 <!--- Place order ---> <cfmodule  name="PlaceOrder"  order  sendConfirmation="Yes"> 

you might use something such as this:

 <!--- Place order ---> <cfmodule  template="../modules/PlaceOrder.cfm"  order  sendConfirmation="Yes"> 

You can also use ColdFusion mappings with the template attribute of the cfmodule tag. So if you created a mapping called ows, you can create a folder under it called customtags and call PlaceOrder like this:

 <!--- Place order ---> <cfmodule template="/ows/customtags/PlaceOrder.cfm"   ordered="#myOrderID#"   sendConfirmation="yes"> 

NOTE

You can't provide an absolute file system-style path to the TEMPLATE attribute, so drive letters or UNC paths are not allowed.