Appendix A: Creating ColdFusion MX Custom Tags | ColdFusion MX Professional Projects

CFML custom tags allow you to create your own tags for a ColdFusion page. You can define these tags to perform specific actions. This incorporates the functionality provided by the custom tag to the ColdFusion page.

Creating and Calling Custom Tags

You can define custom tags in the same way as ColdFusion tags, such as <cfset> or <cfoutput>. For example, you can use the following syntax to create a custom tag called <cf_mytag> to show a welcome message:

 <cf_mytag name="Frank Malone" message="Wishing you a nice day">

<cf_mytag> returns the following message when processed by ColdFusion:

 Hello Frank Malone! Your first custom tag Wishing you a nice day

A custom tag declaration can also have a body and an end tag. For example, the following code creates a custom tag with a body and an end tag:

 <cf_mytag name="name1">     This is a sample content defined in a custom tag </cf_mytag>

Creating a Custom Tag

You can use a single ColdFusion page to implement a custom tag. This ColdFusion page can be called from any other ColdFusion page, which is thereafter known as the calling page. The called page provides an application logic that can be incorporated by the calling page. To call a custom tag, prefix the filename of the ColdFusion page with cf_. For example, if the filename of the ColdFusion page that implements a custom tag is mycust.cfm, another ColdFusion page can reference it as custom tag <cf_mycust>.

A ColdFusion custom tag can be saved in any of these locations:

The Cfusion\CustomTags directory or CfusionMX\CustomTags directory under the ColdFusion root directory, depending upon the ColdFusion version installed on the computer
The same directory as the calling page
A directory specified using ColdFusion MX Administrator

Note

A custom tag defined in the CfusionMX\CustomTags directory can be shared between multiple ColdFusion application pages.

To create a custom tag and call it from another ColdFusion page, follow these steps:

Use this code to create a ColdFusion page that displays a welcome message in the browser:

 <cfoutput> Welcome to custom tags. Today is #DateFormat(Now(),'dd/mm/yyyy')#</cfoutput>

Save this code in a file named welcome.cfm.

Create a calling ColdFusion page that contains the following code:

 <html> <head> <title> A Welcome message </title> <head> <body>     <!--The following call executes the code in the custom tag         page welcome.cfm --     The message below has been generated using a custom tag:<br>    <cf_welcome> </body> </html>

Save the code in a file named callwelcometag.cfm.
View callwelcometag.cfm in the Web browser to see the welcome message defined in the custom tag <cf_welcome>.

When the custom tag <cf_welcome> is called from the calling page, it returns a welcome message with the current date, as shown in Figure A.1.

click to expand
Figure A.1: Calling a custom tag.

Calling a Custom Tag Using the <cfmodule> Tag

You can call a custom tag by adding the prefix cf_ to the filename of the ColdFusion page. Use the <cfmodule> tag to call a custom tag page stored in a different directory location. This tag allows you to specify the location of the custom tag page to be called. It also allows you to resolve custom tag name conflicts by allowing you to store custom tags with the same name in different directory locations. You can then call these custom tags using <cfmodule> in a ColdFusion page.

The <cfmodule> tag contains two important attributes that allow you to execute a custom tag in a ColdFusion page:

template. Specifies a path to the custom tag relative to the directory of the calling page. If you prefix the path value with a / character, ColdFusion looks for the mappings defined in ColdFusion Administrator. For example, <cfmodule template="/customtag.cfm"> looks for the custom-tag.cfm custom tag page in the wwwroot directory under the ColdFusion root directory.
name. Specifies period-delimited names to distinctly identify a subdirectory under the custom tag's directory. For example, <cfmodule name="mytags.calculate"> looks for the calculate.cfm custom tag page in the CustomTags\mytags directory under the ColdFusion root directory.

CREATING A MAPPING

To create a mapping in ColdFusion Administrator, perform the following steps:

Launch ColdFusion Administrator.
Choose the Mappings link in the left frame of the ColdFusion Administrator window to launch the ColdFusion Mappings page.
In the Logical Path text box, type the name of the map alias you want to assign to the directory.
In the Directory Path box, type the physical path of the directory for which you want to create the mapping.
Click Add Mapping to create the new mapping.

To create a custom tag and call it from <cfmodule> using the template attribute, perform the following steps:

Create a ColdFusion custom tag page that contains the following code:

 <cfset strvar="This shows the usage of the cfmodule tag"> <Cfoutput> #strvar# </Cfoutput>

Save this code in a file named strmessage.cfm in the ColdFusion root directory.

Create a ColdFusion page that calls strmessage.cfm, which contains the following code:

 <HTML> <HEAD> <TITLE> This is a sample ColdFusion page using custom tags</TITLE> </HEAD> <BODY>     <!-- Use the cfmodule to call the custom tag           defined in the ColdFusion root directory -->     <cfmodule template="../strmessage.cfm"> </BODY> </HTML>

Save this code in a file named callmessagetag.cfm, and store it in the wwwroot directory under the ColdFusion root directory.
Execute callmessagetag.cfm to call the custom tag defined in strmessage.cfm. This custom tag is stored in the parent of the directory containing callmessagetag.cfm.

You can also use the name attribute to create a custom tag as follows:

Create a subdirectory in the CustomTags directory under the ColdFusion root directory named testapp.

Create a custom tag page with the following code:

 <cfset strvar="This uses the name attribute of the cfmodule tag"> <Cfoutput> #strvar# </Cfoutput>

Save this code in a file named Nameattr.cfm. Store this file in CustomTags\testapp under the ColdFusion root directory.

 <HTML> <HEAD> <TITLE> This is a sample ColdFusion page using custom tags</TITLE> </HEAD> <BODY>     <!-- Use the cfmodule to call the custom tag defined in a         subdirectory under the ColdFusion CustomTags directory -->     <cfmodule name="testapp.Nameattr"> </BODY> </HTML>

This code calls Nameattr.cfm in the CustomTags\testapp directory.