Creating and calling custom tags

You implement a custom tag with a single ColdFusion page. You then call the custom tag from a ColdFusion page by inserting the prefix cf_ before the page's file name. The page referencing the custom tag is referred to as the calling page.

To create and call a custom tag:

  1. Create a ColdFusion page, the custom tag page, that shows the current date: 
    <cfoutput>#DateFormat(Now())#</cfoutput>
  2. Save the file as date.cfm.
  3. Create a ColdFusion page, the calling page, with the following content: 
    <html>
<head>
	<title>Date Custom Tag</title>
</head>
<body>

	<!--- Call the custom tag defined in date.cfm --->
	<cf_date>

</body>
</html>
  4. Save the file as callingdate.cfm.
  5. View callingdate.cfm in your browser.

    This custom tag returns the current date in the format DD-MMM-YY.

As you can see from this example, creating a custom tag in CFML is no different from writing any ColdFusion page. You can use all CFML constructs, as well as HTML. You are free to use any naming convention that fits your development practice. Unique descriptive names make it easy for you and others to find the right tag.

Note: Although tag names in ColdFusion pages are case-insensitive, custom tag filenames must be lowercase on UNIX.

Storing custom tag pages

You must store custom tag pages in any one of the following:

To share a custom tag among applications in multiple directories, place it in the cfusion\CustomTags directory. You can create subdirectories to organize custom tags. ColdFusion searches recursively for the Custom Tags directory, stepping down through any existing subdirectories until the custom tag is found.

You might have a situation where you have multiple custom tags with the same name. To guarantee which tag ColdFusion calls, copy it to the same directory as the calling page. Or, use the cfmodule tag with the template attribute to specify the absolute path to the custom tag. For more information on cfmodule, see the next section.

Calling custom tags using the cfmodule tag

You can also use the cfmodule tag to call custom tags if you want to specify the location of the custom tag page. The cfmodule tag is useful if you are concerned about possible name conflicts when invoking a custom tag, or if the application must use a variable to dynamically call a custom tag at runtime.

You must use either a template or name attribute in the tag, but you cannot use both. The following table describes the basic cfmodule attributes:

Attribute Description  

template

Required if the name attribute is not used. Same as the template attribute in cfinclude. This attribute:

  • Specifies a path relative to the directory of the calling page.
  • If the path value is prefixed with "/", ColdFusion searches directories explicitly mapped in the ColdFusion MX Administrator for the included file.

Example: <cfmodule template="../MyTag.cfm"> identifies a custom tag file in the parent directory.

name

Required if the template attribute is not used. Use period-separated names to uniquely identify a subdirectory under the CustomTags root directory.

Example: <cfmodule name="MyApp.GetUserOptions"> identifies the file GetUserOptions.cfm in the CustomTags\MyApp directory under the ColdFusion root directory.

attributes

The custom tag's attributes.

For example, the following code specifies to execute the custom tag defined by the mytag.cfm page in the parent directory of the calling page:

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

For more information on using the cfmodule tag, see CFML Reference.

Calling custom tags using the cfimport tag

You can use the cfimport tag to import custom tags from a directory as a tag library. The following example imports the tags from the directory myCustomTags:

<cfimport prefix="mytags" taglib="myCustomTags">

Once imported, you call the custom tags using the prefix that you set when importing, as the following example shows: 

<mytags:customTagName>

where customTagName corresponds to a ColdFusion application page named customTagName.cfm. If the tag takes attributes, you include them in the call:

<mytags:custom_tag_name attribute1=val_1 attribute2=val_2>

You can also include end tags when calling your custom tags, as the following example shows:

<mytags:custom_tag_name attribute1=val_1 attribute2=val_2>
...
</mytags:custom_tag_name>

ColdFusion calls the custom tag page twice for a tag that includes an end tag: once for the start tag and once for the end tag. For more information on how ColdFusion handles end tags, and how to write your custom tags to handle them, see Handling end tags.

One of the advantages to using the cfimport tag is that you can define a directory structure for your custom tags to organize them by category. For example, you can put all security tags in one directory, and all interface tags in another. You then import the tags from each directory and give them a different prefix:

<cfimport prefix="security" taglib="securityTags">
<cfimport prefix="ui" taglib="uiTags">
...
<security:validateUser name="Bob">
...
<ui:greeting name="Bob">
...

Reading your code becomes easier because you can identify the location of your custom tags from the prefix.

View comments in LiveDocs