Calling Custom Tags

Contact Us or call 1-877-932-8228
Calling Custom Tags

Calling Custom Tags

To call a custom tag, use the following syntax:

<cf_tagname>

The cf_ is simply a prefix that tells the ColdFusion Application Server that this is a custom tag. The string that follows the cf_ is the name of the custom tag file minus the file extension. So, in the example above, the file would be called tagname.cfm. Any ColdFusion file can be called as a custom tag.

To illustrate, let's assume that we have a page called Foo.cfm, which has nothing more than the word "foo" written on it. Foo.cfm will be our custom tag template. You call it with the <cf_foo> tag, which will simply output the word "foo". The code for the two files is shown below.

Code Sample:

CustomTags/Demos/Foo.cfm
foo

Code Sample:

CustomTags/Demos/FooCaller.cfm
<html>
<head>
<title><cf_foo></title>
</head>
<body>
	<cf_foo>
</body>
</html>

thisTag Structure

The thisTag structure holds data related to the custom tag instance. The table below shows the variables available in the thisTag structure.

Variable Description
ExecutionMode The mode of execution: "start", "end", or "inactive"
HasEndTag true if the tag is called with an end tag; otherwise, false
GeneratedContent The content in the body of the tag (i.e, between the open and close custom tag)
AssocAttribs Contains the attributes of nested custom tags that have been made available through the <cfassociate> tag.

ExecutionMode

Custom tags can be called with end tags, like so: <cf_foo></cf_foo> or <cf_foo/>. This instructs ColdFusion to call the custom tag twice. Open CustomTags/Demos/FooCallerClosed.cfm in your browser and you will see that the word "foo" is output twice.

However, you may not want the code in the tag to be executed twice or you may want the start tag to behave differently from the end tag. This can be handled by checking the ExecutionMode of the ThisTag structure. Take a look at our modified custom tag template.

Code Sample:

CustomTags/Demos/Foo2.cfm
<cfif ThisTag.executionMode EQ "start">
	foo
<cfelse>
	bar
</cfif>

Code Sample:

CustomTags/Demos/Foo2Caller.cfm
<html>
<head>
<title><cf_foo2></title>
</head>
<body>
	<cf_foo2/>
</body>
</html>

As you can see, the word "foo" is output when the tag is opened and the word "bar" is output when it is closed. Now that's useful! But let's take a look at an even more interesting example. The following page creates a custom tag which displays an image from a specified directory. Each time the custom tag is called, it returns a different image from the directory.

Code Sample:

CustomTags/Demos/ImageFlipper.cfm
               <cfif thisTag.executionMode EQ "start">
	<cfdirectory action="list" name="getImages" directory="#ExpandPath(ATTRIBUTES.directory)#">
	
	<cfparam name="SESSION.picture" default="0">
	<cfset SESSION.picture = SESSION.picture + 1>
	
	<cfif SESSION.picture GT getImages.RecordCount>
		<cfset SESSION.picture = 1>
	</cfif>
	
	<cfoutput>	
	<img src="#ATTRIBUTES.directory#/#getImages.name[SESSION.picture]#"
		<cfif isDefined("ATTRIBUTES.height")>
			height="#ATTRIBUTES.height#"
		</cfif>
		<cfif isDefined("ATTRIBUTES.width")>
			width="#ATTRIBUTES.width#"
		</cfif>
		<cfif isDefined("ATTRIBUTES.alt")>
			alt="#ATTRIBUTES.alt#"
		<cfelse>
			alt="#getImages.name[SESSION.picture]#"
		</cfif>>
	</cfoutput>
</cfif>

Code Sample:

CustomTags/Demos/Runners.cfm
<html>
<head>
<title>Flipping Image</title>
</head>

<body>
<cf_ImageFlipper directory="Images/Runners" height="205" width="150">Runners</cf_ImageFlipper>
</body>
</html>

In the code above, you'll notice the ATTRIBUTES scope, which contains any variables passed in as attributes as shown below...

<cf_ImageFlipper directory="Images/Runners" height="205" width="150">

We check for the existence of these attributes using the isDefined() function.

GeneratedContent

The GeneratedContent variable, which is only accessible in the "end" mode, holds all content between the open tag and close tag (e.g., between <cf_foo> and </cf_foo>). Its value can be modified in the custom tag. The following files show how a custom tag can be used to comment out the body based on the value of an attribute.

Code Sample:

CustomTags/Demos/ImageFlipper2.cfm
<cfif thisTag.executionMode EQ "start">
	<cfdirectory action="list" name="getImages" directory="#ExpandPath(ATTRIBUTES.directory)#">
	
	<cfparam name="SESSION.picture" default="0">
	<cfset SESSION.picture = SESSION.picture + 1>
	
	<cfif SESSION.picture GT getImages.RecordCount>
		<cfset SESSION.picture = 1>
	</cfif>
	
	<cfoutput>	
	<img src="#ATTRIBUTES.directory#/#getImages.name[SESSION.picture]#"
		<cfif isDefined("ATTRIBUTES.height")>
			height="#ATTRIBUTES.height#"
		</cfif>
		<cfif isDefined("ATTRIBUTES.width")>
			width="#ATTRIBUTES.width#"
		</cfif>
		<cfif isDefined("ATTRIBUTES.alt")>
			alt="#ATTRIBUTES.alt#"
		<cfelse>
			alt="#getImages.name[SESSION.picture]#"
		</cfif>>
	</cfoutput>
<cfelseif thisTag.executionMode EQ "end">
	<cfif isDefined("ATTRIBUTES.CommentBody") AND ATTRIBUTES.CommentBody EQ "true">
		<cfset thisTag.GeneratedContent = "<!--#thisTag.GeneratedContent#-->">
	</cfif>
</cfif>

Code Sample:

CustomTags/Demos/Runners2.cfm
<html>
<head>
<title>Flipping Image</title>
</head>

<body>
<cf_ImageFlipper2 directory="Images/Runners" height="205" width="150" CommentBody="true">
	<br/>Runners
</cf_ImageFlipper2>
</body>
</html>
Next