• Home
• Tutorials
• Forums
• Reference
• Developers
• Advertise
• About Us

A quick intro into the world of Custom Tags!

What is a custom tag and why do i need it?

This is a question I get a lot when I bring up custom tags. A custom tag is a piece of code that you create and you call it from within your ColdFusion applications. Think of it as a "SNIPPLET" that you can implement at any time, anywhere in your site. What can you do with a custom tag? Well, just about anything!

In this tutorial I will demonstrate how you can use a custom tag to add a list of states (in a drop down select box) in a form. 

Let's see how you call a custom tag. The easiest (and probably most used) method is: <cf_states>. 
What does that mean?
Ok, you are simply telling ColdFusion to look in the same folder (as the file you are accessing to call the custom tag) or in the custom tags folder (Usually C:\CFusion\CustomTags\) for a file called: states.cfm. If it finds that file, you are saying to the server, execute it, process it and send me the results of it. So it's like an include, but with the difference that you can do other neat things! I'll explain more below.

You can pass values to the custom tag, as follows:

<cf_states DefaultState="TX"
               FieldName="States">

This basically says that when executing the custom tag "states.cfm" the default state I want selected is "TX - Texas". Of course you'll have to write the code that will select the stat, but it's basically allowing you to tell the code in the "states.cfm" file that that is the default state. Let's create the actual states.cfm file so you can see how it works. Notice also that I'm passing a value called "FieldName" this will become the name of the form field that will be generated. That ay when you process the page in the end you'll know what name to reference.

(Note: Since you are specifying a variable for the custom tag called "DefaultState", within the custom tag, this variable is referenced as follows: "Attributes.DefaultState". All variables you pass when calling the tag (i.e.  one=""   two="") will always be referenced within the custom tag as "Attributes.[name of variable]".)

<!--- States.cfm custom tag --->
<!--- Make sure that user specified a name for the form field --->
<cfif NOT IsDefined("Attributes.FieldName")>
    <!--- No Name Was Specified, stop custom tag and ask that user specify field --->
    <font color="red" size="4" face="Verdana">You did not specify a valid name for the select field!</font>
    <cfabort>
</cfif>
<!--- define a variable called "Attributes.DefaultState" to be Arizona --->
<cfif NOT IsDefined("Attributes.DefaultState")>
    <!--- No Default State Was Define, Set Default To Be Arizona --->
    <cfset Attributes.DefaultState = "AZ">
</cfif>

<!--- Now Create the Select Box With The States --->
<cfoutput>
   <select name="#Attributes.FieldName#">
        <option value="AZ"<cfif Attributes.DefaultState eq "AZ"> SELECTED</CFIF>>AZ - Arizona</option>
        <option value="CA"<cfif Attributes.DefaultState eq "CA"> SELECTED</CFIF>>CA - California</option>
        <option value="MS"<cfif Attributes.DefaultState eq "MS"> SELECTED</CFIF>>MS - Mississippi</option>
        <option value="NJ"<cfif Attributes.DefaultState eq "NJ"> SELECTED</CFIF>>NJ - New Jersey</option>
        <option value="NY"<cfif Attributes.DefaultState eq "NY"> SELECTED</CFIF>>NY - New York</option>
        <option value="TX"<cfif Attributes.DefaultState eq "TX"> SELECTED</CFIF>>TX - Texas</option>
   </select>
</cfoutput>

OK, so what was the purpose of this custom tag? Well imagine that you are building 30 web sites for 30 different customers that all ask for users information. So now with this custom tag you can simply type in:
<cf_states DefaultState="TX"
               FieldName="States">
So for customer one you created an automatic states drop down in the form on the fly.

Now say your second customer likes that the database values be written as tblflStates and the default state for this customer has to be New York. So in the "FieldName" you can no longer use "states". If you hadn't used a custom tag you'd have to recreate the file, use unnecessary space and waste time with something you could of already have had done. So for this customer so simple modify as follows:
<cf_states DefaultState="NY"
               FieldName="TblflStates">

Are you starting to see the value of Custom tags? Well in short they're a way for you reuse your code easily and fast!

You can also do other neat things with them, but that's a whole other tutorial! :)

Congratulations, you now know how custom tags work!

Questions? Comments? Email Me.... webmaster@easycfm.com