Developing ColdFusion MX Applications with CFML Previous Up One Level Next Home Search
Creating and Using Custom CFML Tags


Creating custom tags

Custom tags let you extend CFML by adding your own tags to the ones supplied with ColdFusion. After you define a custom tag, you can use it on a ColdFusion page just as you would any of the standard CFML tags, such as cfquery and cfoutput.

You use custom tags to encapsulate your application logic so that it can be referenced from any ColdFusion page. Custom tags allow for rapid application development and code reuse while offering off-the-shelf solutions for many programming chores.

For example, you might create a custom tag, named cf_happybirthday, to generate a birthday message. You could then use that tag in a ColdFusion page, as follows: 

<cf_happybirthday name="Ted Cantor" birthDate="December 5, 1987">

When ColdFusion processes the page containing this tag, it could output the message: 

December 5, 1987 is Ted Cantor's Birthday.

Please wish him well.

A custom tag can also have a body and end tag, for example: 

<cf_happybirthdayMessge name="Ellen Smith" birthDate="June 8, 1993">

  <P> Happy Birthday Ellen!</P>
  <P> May you have many more!</P>
</cf_happybirthdayMessge>

This tag could output the message: 

June 8, 1993 is Ellen Smith's Birthday.

Happy Birthday Ellen!
May you have many more!

For more information about using end tags, see "Handling end tags".

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 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.

Securing custom tags

ColdFusion's security framework enables you to selectively restrict access to individual tag files and tag directories. This can be an important safeguard in team development. For details, see Administering ColdFusion Server.

Accessing existing custom tags

Before creating a custom tag in CFML, you should review the Custom Tag section of the ColdFusion Developer Exchange at http://devex.macromedia.com/developer/gallery/index.cfm. You might find a tag here that does what you want.

Tags are grouped in several broad categories and are downloadable as freeware, shareware, or commercial software. You can view each tag's syntax and usage information. The gallery contains a wealth of background information on custom tags and an online discussion forum for tag topics.

Tag names with the cf_ preface are CFML custom tags; those with the cfx_ preface are ColdFusion extensions written in C++. For more information about the CFX tags, see Chapter 12, "Building Custom CFXAPI Tags".

If you do not find a tag that meets your specific needs, you can create your own custom tags in CFML.

Copyright © 2002, Macromedia Inc. All rights reserved. Previous Up Next Home Search

Comments