Creating Customs Tags in Coldfusion; An example

20 Oct
2008

ColdFusion Image
In this example I will show you how to create a Custom tag in ColdFusion. The idea of a Custom tag is to allow you to package chunks of code into reusable modules that you can then reuse through out your project. They are similar to UDF (User Defined Functions) with the exception that Custom tags are self-contained, have a specific purpose and goal-oriented. In addition, one does not have to understand how exactly the Custom Tag works, all you do is plug in the variables and watch the tag do it’s work.

Now to put Custom tags to good use, you will want them to accept variables and return variables. You do that by using the ATTRIBUTES scope, and the CALLER Scope. The ATTRIBUTES scope accepts variables and the CALLER scope is what returns the variables. These only pertain to Custom tags and should not be used anywhere else ex: UDF, or inside a CFC. The only place these scopes should be used is in a Custom Tag.

In addition, your Custom tags should be placed in the specified folder that can be found in the ColdFusion admin panel. If you cannot access the ColdFusion admin panel due to being on a shared host service then you place the Custom Tags in the current folder of where your tag is used. For Example if I have a folder called admin, and in the admin i have login.cfm and I am using a Custom Tag then the custom tag would be in the same folder as the login.cfm file.

After you place them in the right folder then you can use the tag like this . To have the template accept attributes and return attributes you do

 
<cf_nameOfTemplate myName="#myInputName#" returnedVariable="myNameReturned">
//you can then use it like this
<cfoutput>
#myNameReturned#
</cfoutput>

Inside the Custom Tag, you would have something like this

 
<cfparam name="ATTRIBUTES.myName" type="string">
 
//notice the variableName type
 
<cfparam name="returnedVariable" type="variableName">

To return the variable you can do something like this

 
<cfset CALLER[ATTRIBUTES.returnedVariable]=Attributes.myName>

This is just scratching the surface of Custom Tags, I will explain more as this week progresses but this should give you enough rope to try some stuff on your own.

Here is the source and a working example. Click Here for the Example
Custom Tag

<cfparam name="ATTRIBUTES.returnVariable" type="variablename">
<cfparam name="ATTRIBUTES.searchName" type="string">
<cfparam name="ATTRIBUTES.datasourceName" type="string" default="cfartgallery">
 
 
<cfquery name="myQuery" datasource="#ATTRIBUTES.datasourceName#">
	SELECT Description ,ArtName
    FROM ART
    WHERE Description LIKE '%#ATTRIBUTES.searchName#%' OR ARTNAME LIKE '%#ATTRIBUTES.searchName#%'
</cfquery>
 
<cfset Caller[ATTRIBUTES.returnVariable] = myQuery>

Main Index.cfm

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Untitled Document</title>
</head>
<body>
 
<cfform>
	<cfinput type="text" name="mySearchName"/>
    <input type="submit" value="Search"/>
</cfform>
<hr/>
<cfif isDefined("FORM.mySearchName")>
<cf_myCFXTAG  searchName="#mySearchName#" returnVariable="myReturnedQuery">
 
<table border="2" align="center">
    	<tr>
        	<th>
            	ArtName
            </th>
            <th>
            	Description
            </th>
        </tr>
<cfoutput query="myReturnedQuery">
	    <tr>
        	<td>
            	#artName#	
            </td>
            <td>
            #Description#
            </td>
        </tr>
 
</cfoutput>
 </table>
</cfif>
</body>
</html>