Understanding the Difference Between Custom Tags and cfinclude

---

Understanding the Difference Between Custom Tags and <cfinclude>

In a sidebar accompanying the previous chapter, you learned about <cfinclude> and how it can be used to include the contents of one template in another. At this point you may be wondering how this process differs from using a custom tag.

The answer is that <cfinclude> causes the included page's code in to be executed in-line with the calling page just as if it had been hard-coded into the calling template. In this way, any variables present on the calling page are automatically shared with the included page. In contrast, custom tags are used more like separate programs, whereby you must specifically pass attributes to the custom tag, and in turn the custom tag must specifically define variables to be returned to the calling page.

The advantage to custom tags is that because their variables are isolated from the calling page, they are much more portable and can be used in a variety of settings without modification.

Using <cfmodule> to Call a Custom Tag

Usually, the best way to use a custom tag is to save it in an "approved" directory (see "Saving custom tags" earlier in this chapter) and then call it using the standard syntax:

<cf_some_tag_name some_attribute>

However, in some rare cases this method doesn't suffice. For example, if you have a custom tag named get_user_info.cfm designed for one application, and you or another developer on your system has a tag also named get_user_info.cfm, a conflict will result. By calling the tag with <cfmodule>, you can specify a specific path to a specific tag's file to avoid confusion. Instead of

<cf_get_user_info>

you could use

<cfmodule template="../../get_user_info.cfm">

ColdFusion then processes the file as if it had been called as a custom tag.

You can also pass along attributes accepted by the tag by supplying them in the <cfmodule> call:

<cfmodule template="../../get_user_info.cfm" user_id = 12  user_state="CA">

When you do so, <cfmodule> passes the attributes along, as-is, to the custom tag you called.

The <cfmodule> method is also handy when you need to supply the name of a tag dynamically, because you can't do so with standard tag syntax. For example, if a form gave the user a choice of shipping methods, you could use a special custom tag for each shipping service and then call the correct one dynamically. The following snippet assumes that the variable shipping_method contains a name like "fedex," "ups," and so on, and that you have tags named compute_fedex.cfm, compute_ups.cfm, and so on.

<cfmodule template="compute_#shipping_method#.cfm" zipcode="#zipcode#">

Finally, <cfmodule> is also useful for calling tags that for one reason or another may not be saved in one of the "approved" locations. Because you can supply a complete file path with <cfmodule>, you can use it to call any file anywhere on your Web server as a custom tag, providing the file itself is suitable for use as a custom tag.

---