Using Custom Tags

Custom tags wrap functionality in a page that can be called from a ColdFusion application page. ColdFusion custom tags built in CFML allow for rapid application development and code reuse while offering off-the-shelf solutions to many programming chores.

You use a custom tag just as you would use a standard HTML or ColdFusion tag, for example, you might call a custom tag to generate a happy birthday message as follows:

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

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

<CF_HappyBirthdayMessge name="Ellen Janes" birthDate="June, 8, 1993">

<P> Happy Birthday Ellen!</P>

<P> May you have many more!</P>

</CF_HappyBirthdayMessage>

You call custom tags by adding the cf_ prefix to the filename (without the .cfm suffix). For example, use the tag name cf_getweather to call the file getweather.cfm. You must store custom tags that you call directly in either the same directory as the calling page, in the CFUSION\CustomTags directory, or in a subdirectory of the CFUSION\CustomTags directory. Each file defines a single custom tag.

You can also use the cfmodule tag to call custom tags. The cfmodule tag lets you specify the location of the custom tag file. 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. For more information on using the cfmodule tag, see theCFML Reference.

Using existing custom tags

Before creating a custom tag in CFML, you should review the Custom Tag section of the ColdFusion Developer Exchange. Tags are grouped in several broad categories and are downloadable as freeware, shareware, or commercial software. You can quickly 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 21, "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.

Creating custom CFML tags

Creating a custom tag in CFML is no different from writing any CFML 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

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

Variable scopes and special variables

ColdFusion provides several variable scope types and built-in variables that help you pass information between calling pages and custom tag pages.

Use the Attributes scope in the custom tag page to refer to the attributes passed by the calling page. For example, assume the calling page has the following line:
```
cf_mytag Firstname="Thadeus" Lastname="Jones">
```
In this case, the mytag.cfm custom tag page refers to the passed attributes as Attributes.Firstname and Attributes.Lastname.
Use the Caller scope in the custom tag page to refer to local variables in the calling tag page. You use the Caller scope to return values to the calling page, but you can also use this scope to access any local variables on the calling page.
Use the Request scope for variables in nested tags. The Request scope is available to the base page, all pages it includes, all custom tag pages it calls, and all custom tag pages called by the included pages and custom tag pages. Collaborating custom tags that are not nested in a single tag can exchange data via the request structure. The Request scope is represented as a structure named Request.

Custom tag pages also have access to system data structure called thisTag. The thisTag structure contains information about the tag and its execution environment. The thisTag variable is described in "Executing Custom Tags".

Using tag attributes

Custom tag attribute values are passed from the calling page to the custom tag page as name-value pairs.

CFML custom tags support required and optional attributes. Attributes are defined as name-value pairs. Custom tag attributes conform to CFML coding standards:

ColdFusion passes any attributes in the Attributes scope.
Use the cfparam tag with a default attribute at the top of a custom tag to test for and assign defaults for optional attributes that are passed from a calling page.
Use the cfparam tag without a default attribute or a cfif tag with an IsDefined function at the top of a custom tag to test for required attributes that must be passed from a calling page.
Use the Attributes.attribute_name syntax when referring to passed attributes to distinguish them from custom tag page local variables.
Attributes are case-insensitive.
Attributes can be listed in any order within a tag.
Attribute = value pairs for a tag must be separated by a space.
Passed values that contain spaces must be enclosed in double-quotes.

Passing values to and from custom tags

Because custom tags are individual ColdFusion pages, variables and other data are not automatically shared between a custom tag and the calling page.

To pass data from the calling page to the custom tag, specify attribute name-value pairs in the custom tag, just as you do for normal HTML and CFML tags. In the custom tag you use the Attributes scope to access these variables.For example, to pass the value of the NameYouEntered variable to the cf_getMD tag, you can call the custom tag as follows:

<cf_getMD Name="#NameYouEntered#">

In the getmd.cfm file, you refer to the passed attribute as Attributes.Name.

To pass values back to the calling page, use the Caller scope. The custom tag page can also access variables already set on the calling by simply prefixing the calling page's local variable name with Caller. For example, use the following code to set the variable Doctor on the calling page:

<cfset Caller.Doctor="Doctor " & Attributes.Name>

The following figure shows the relation between the variables on the calling page and the custom tag:

Passing custom tag attributes via CFML structures

You can use the reserved attribute attributecollection to pass attributes to custom tags. Attributecollection must reference a structure that contains the attribute names as the keys and the attribute values as the values. You can freely mix attributecollection with other attributes when you call a custom tag.

The key-value pairs in the structure specified by attributecollection get copied into the called page Attributes scope. This has the same effect as specifying the attributecollection entries as individual attributes when you call the custom tag. The custom tag page refers to the attributes passed using attributecollection the same way as it does other attributes; for example as Attributes.CustomerName or Attributes.Department_number.

If the called custom tag uses a cfassociate tag to save its attributes in the base tag, the attributes passed via structure are saved as independent attribute values, with no indication that they were aggregated into a structure by the custom tag's caller.

Custom tag processing reserves attributecollection to refer to the structure holding a collection of custom tag attributes. If attributecollection does not refer to such a collection, the ColdFusion generates a Template exception.

The following example uses an attributecollection to pass two of four attributes:

<cfset zort=StructNew()>

<cfset zort.x = "-X-">

<cfset zort.y = "-Y-">

<cf_testtwo a="blab" attributecollection=#zort# foo="16">

If testtwo.cfm contains this CFML:

---custom tag ---<br>

<cfoutput>#attributes.a# #attributes.x# #attributes.y#

  #attributes.foo#</cfoutput><br>

--- end custom tag ---

its output is the following statement:

---custom tag ---

blab -X- 12 16

--- end custom tag ---

Custom tag example

In this example, we create a custom tag that uses an attribute that is passed to it to set the value of a variable called Doctor on the calling page.

To create a custom tag:

Create a new application page (the calling page) in ColdFusion Studio.

Modify the file so that it appears as follows:

<html>

<head>

  <title>Enter Name</title>

</head>

<body>

<!--- Enter a name, which could also be done in a form --->

<!--- This example simply uses a cfset --->

<cfset NameYouEntered="Smith">



<!--- Display the current name --->

<cfoutput>

Before you leave this page, you're #NameYouEntered#.<br>

</cfoutput>



<!--- go to the custom tag --->

<CF_GetMD Name="#NameYouEntered#">

<!--- Come back from the Custom tag --->



<!--- display the results of the custom tag --->

<cfoutput>

You are now #Variables.Doctor#.<br>

</cfoutput>

</body>

</html>

Save the page as callingpage.cfm.
Create another new page (the custom tag) in ColdFusion Studio.

Enter the following code:

<!--- The value of the variable Attributes.Name comes from the calling page.

     If the calling page does not set it, make it "Who". --->

<cfparam name="Attributes.Name" default="Who">



<!--- Create a variable called Doctor, make its value "Doctor " 

     followed by the value of the variable Attributes.Name.

     Make its scope Caller so it is passed back to the calling page

--->

<cfset Caller.Doctor="Doctor " & Attributes.Name>

Save the page as getmd.cfm.
Open the file callingpage.cfm in your browser.

The calling page uses the getmd custom tag and displays the results.

Reviewing the code

The following table describes the code and its function:

Code

Description

<cfset NameYouEntered="Smith">
In the calling page, create a variable NameYouEntered and assign it the value "Smith."

<cfoutput> Before you leave this page, you're #NameYouEntered#.<br> </cfoutput>
In the calling page, display the value of the NameYouEntered variable before calling the custom tag.

<CF_GetMD Name="#NameYouEntered#">
In the calling page, call the GetMD custom tag and pass it the Name attribute whose value is the value of the local variable NameYouEntered.

<cfparam name="Attributes.Name" default="Who">
The custom tag page normally gets the Name variable in the Attributes scope from the calling page. Assign it the value "Who" if the calling page did not pass an attribute.

<cfset Caller.Doctor="Doctor " & Attributes.Name>
In the custom tag page, create a variable called Doctor in the Caller scope so it will exist in the calling page as a local variable.
Set its value to the concatenation of the string "Doctor " and the value of the Atributes.Name variable.

<cfoutput> You are now #Variables.Doctor#.<br> </cfoutput>
In the calling page, display the value of the Doctor variable returned by the custom tag page. (We use the Variables scope prefix to emphasize the fact that the variable is returned as a local variable.)

Code	Description
<cfset NameYouEntered="Smith">	In the calling page, create a variable NameYouEntered and assign it the value "Smith."
<cfoutput> Before you leave this page, you're #NameYouEntered#.<br> </cfoutput>	In the calling page, display the value of the NameYouEntered variable before calling the custom tag.
<CF_GetMD Name="#NameYouEntered#">	In the calling page, call the GetMD custom tag and pass it the Name attribute whose value is the value of the local variable NameYouEntered.
<cfparam name="Attributes.Name" default="Who">	The custom tag page normally gets the Name variable in the Attributes scope from the calling page. Assign it the value "Who" if the calling page did not pass an attribute.
<cfset Caller.Doctor="Doctor " & Attributes.Name>	In the custom tag page, create a variable called Doctor in the Caller scope so it will exist in the calling page as a local variable. Set its value to the concatenation of the string "Doctor " and the value of the Atributes.Name variable.
<cfoutput> You are now #Variables.Doctor#.<br> </cfoutput>	In the calling page, display the value of the Doctor variable returned by the custom tag page. (We use the Variables scope prefix to emphasize the fact that the variable is returned as a local variable.)

Tip

Be careful not to overwrite variables that might already exist on the calling page. You should adopt a naming convention to minimize the chance of overwriting variables. For example, prefix the returned variable with customtagname_, with customtagname being the name of the custom tag.

Note

Data pertaining to the HTTP request or to the current application is visible in the custom tag page. This includes the variables in the Form, Url, Cgi, Request, Cookies, Server, Application, Session, and Client scopes.

Developing ColdFusion Applications
Reusing Code