Custom Tags
ColdFusion custom tags are ColdFusion templates just like any other CFML file but are designed to be reused. Coders can save much time by packaging code that is used frequently or can easily add functionality by using free or inexpensive custom tags. There are two general categories of custom tags, one uses only ColdFusion's CFML code. The other packages C++, Java, or other languages into a custom tag that is used by ColdFusion. We'll cover only CFML based tags in this article. For our discussion we will be using CF_States from AspiringGeek.com.
Simple Custom Tags
A simple custom tag is one that is used in a page and adds code to that
template without using any inputs. To add a custom tag's functionality
to your page, you will place the custom tag in the custom tag directory
or in the same folder as the page that you call the custom tag in from.
For version control (managing updates to the custom tag) it is best to
place the custom tag in the custom tags folder which is assigned through
the ColdFusion Administration panel. If you are in a
shared hosting environment, you may have to place in each
folder where the tag is used.
After the tag is located on the server, you can use it by simply adding a single tag to your template. In the case of CF_States , the file name is states.cfm so we add cf_ to the start of the file name and drop the .cfm extension place the result within mark up brackets: <cf_states>. In your sample you should see a drop down select box listing all US states with California selected.
Custom Tags with Attributes
The previous example saves over 70 lines of code but it may not
produce a select box to you or your clients taste. Custom tags can have
attributes. Attributes are passed to the custom tag and are used within
the custom tag to vary the tag's output. In the CF_States
example, we can change what state is pre-selected and also abbreviate
the state name to two letters. The attributes for CF_States
are NONVERBOSE and SELECTED. By including these attributes, you can control
the look of the select box. To show only two letters with Virginia selected
use:
<cf_states nonverbose="yes" selected="va">
Creating Custom Tags
Creating a simple
custom tag requires saving a portion of code as a ColdFusion template.
Creating a custom tag that use attributes, only requires that you reference
the attributes using the attributes scope. Within
CF_States, attributes.nonverbose and attributes.selected are used to reference
the nonverbose and selected attributes that are passed into the custom
tag.
Sources for Custom
Tags
A great way to learn about ColdFusion code and custom tags is
to download sample tags and review the way they are coded. Free and inexpensive
custom tags and applications can be found at the following sites:
Various Ways to Include
CF Code
There are several ways to include ColdFusion code. Two ways were addressed
above, they are summarized below with two other methods.
Ways
of Including CF Code |
||
| Type | Syntax | Consideration |
| Custom Tag |
<CF_filename> | This is the simplest syntax for calling in a custom tag. The syntax is adding CF_ to the start of the file name and dropping the .cfm. |
| Custom Tag |
<CF_filename ATTRIBUTE-name ="attribute value"> |
Same as simple custom tags but includes attribute/value pairs. |
| CFINCLUDE | <CFINCLUDE TEMPLATE="templatename" > |
CFINCLUDE places the content of one template into another as a simple way to include code. |
| CFMODULE | <CFMODULE NAME="path" TEMPLATE="path" ATTRIBUTE ="attribute value" ATTRIBUTESCOLLECTION="" > |
CFMODULE is an alternative way to call a custom tag. It is required when calling a custom tag from within a sub-directory of the custom tag directory. Either Name or Template is used and attributes can be called in indivdually or as a collection from a structure. |
Summary
Custom tags provide a great way to use your code or code from others.
Custom tags simplifies coding while improving quality by using tested
code. The use of attributes adds flexibility while maintaining reusibility.
ColdFusions server's central location for custom tags promotes version
control.
More CFNewbie?com Articles
More CFNewbie?com Articles