ColdFusion developers have had Custom Tags in their arsenal of tricks since the early days of ColdFusion. With CFMX, the <cfimport> tag has made it even easier to use custom tags on your pages. With the introduction of ColdFusion Components (CFC) in CFMX, the custom tag has taken a back seat to the versitility of CFCs, but some things are ideally suited to the ColdFusion Custom Tag API. This article will address one use of a ColdFusion custom tag: building a flexible template for your site that will feed every page on the site.
Creating a custom tag is as easy as creating a ColdFusion page. Your pagename.cfm becomes <cf_pagename> as a custom tag. To demonstrate the most rudimentary tag you can create that will form the basis of our template, I created a site in Dreamweaver MX and then added a folder to the site named myCustomTags. This folder will hold custom tags for the site. In that folder I create a blank file named mytemplate.cfm. At this point the page is simply blank -- a default Dreamweaver blank document (in this case, a default Dreamweaver MX XHTML 1.0 transitional document):
<?xml version="1.0" encoding="iso-8859-1"?>
<!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>
<title>Untitled Document</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
</head>
<body>
</body>
</html>
Note: The <?xml> declaration puts IE into quirks mode, but was used here because
it is the default XHTML document style in Dreamweaver MX. Any blank page will
work for the tutorial.
No special code is needed in the custom tag. The custom tag is the blank page: the contents are simply output when the tag is invoked.
To invoke the tag, follow these steps:
1. Create a new blank document named tagtest.cfm at the root of the site folder. Open it in Dreamweaver.
2. Go into source view of this file and REMOVE all code from the file. It should be completely blank.
3. Now, add these two lines:
<cfimport prefix="mytag" taglib="mycustomtags">
<mytag:mytemplate>
4. Save the tagtest.cfm page and browse it. You should now see the contents of the custom tag, a simple blank page.
Let me explain what's going on here. The <cfimport> tag creates a reference to the tag library (your simple folder in the site named mycustomtags). We give the tag library a prefix (mytag), which is a simple name that can be used on the page to reference any tag within that library (.cfm files in the folder). Next, we call the custom tag by using the prefix and the tagname (the ColdFusion page without the .cfm.)
<mytag:mytemplate>
That's it. It doesn't get any easier.
The next step is to utilize this new tag for actual pages. To do this, we need to separate what comes before the opening <body> tag with the closing </body> tag. This can be done easily by examining the thistag built-in construct of ColdFusion custom tags, and examine its executionmode property. We have two values we are interested in: start and end. I'll do this with a simple <cfif> statement:
<cfif thistag.executionmode EQ "start">
<!--- Start tag contents here --->
<cfelse>
<!--- End tag contents here --->
</cfif>
You can probably tell what comes next: all of the content on our custom tag page up to and including the opening <body> tag (mytemplate.cfm) will go into the first conditional (after the <cfif>) and the closing </body></html> will go into the <cfelse> block:
<cfif thistag.executionmode EQ "start">
<!--- Start tag contents here --->
<?xml version="1.0" encoding="iso-8859-1"?>
<!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>
<title>Untitled Document</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
</head>
<body>
<cfelse>
<!--- End tag contents here --->
</body>
</html>
</cfif>
We'll have to make one change to our tagtest.cfm page now to get it to work with an open and a close tag: simply add the closing tag to the file:
<cfimport prefix="mytag" taglib="mycustomtags">
<mytag:mytemplate>
</mytag:mytemplate>
After adding that closing tag, you should have the same results when you browse the page: the blank page that is your mytemplate.cfm file is invoked by the tagtest.cfm page. Let's add some content to tagtest.cfm:
<cfimport prefix="mytag" taglib="mycustomtags">
<mytag:mytemplate>
<h1>This is a test of our template</h1>
<p>Any sort of content can go in the page now. The custom tag opening and closing
tags are now acting as our HTML <body> tags</p>
</mytag:mytemplate>
If you browse the tagtest.cfm page now, you should see the content.
One thing you'll notice is that the title of the document is set in stone: Untitled Document. We can rectify that by passing a title to the custom tag. We can even offer a default title in case no title is passed in. We do that with the attributes variable scope:
attributes.variablename
To specify the default value, set a <cfparam> tag at the top of the mytemplate.cfm file:
<cfparam name="attributes.title" default="Community MX">
Next, change the title tag in the mytemplate.cfm file to utilize the variable instead of having a hard-coded title:
<title><cfoutput>#attributes.title#</cfoutput></title>
Finally, on the tagtest.cfm calling page, add a title attribute to the open tag:
<cfimport prefix="mytag" taglib="mycustomtags">
<mytag:mytemplate title="Testing the Title Custom Attribute">
<h1>This is a test of our template</h1>
<p>Any sort of content can go in the page now. The custom tag opening and
closing
tags are now acting as our HTML <body> tags</p>
</mytag:mytemplate>
If you browse the page now and view source, you should see the new custom title in the document.
We used an attribute named title here, but the effect is far reaching: you create your own attributes and populate them with static or dynamic data from any source.
By now you should see the advantages to using this method over other templating methods, such as Dreamweaver's own static Template feature. The power of the site-wide change is entirely in one file. By moving from one template to another, you can dramatically change the look and feel of the site without having to deal with updating the other pages. You can change a css file site-wide by changing one line in the template. You can change a doc type by changing one line in the template. You can even add a sidebar or banner by changing the template. The possibilities are endless.
This tutorial addressed the powerful feature of ColdFusion known as custom tags. With a custom tag, you can with a single page create a template for a site that will provide all of the basic frameworks of your pages: menus, titles, meta tags, css includes, JavaScript includes, and whatever else might be available to all of your pages. Part 1 addressed the basics: the tag library concept, the open and close tag, the attributes scope. Part II will show how to add additional features, such as dynamic <divs>, custom menus, and javascript functions.