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

Writing your first custom tag

This is going to walk you through creating a simple custom tag that echo?s your input. This really does not have much use, but will give you the structure of a custom tag. After this, we will go into more difficult tag writing, but this is a good place to start. 
Start your tag with the following code:

<cfsetting enablecfoutputonly="yes">

This will block the output that the tag creates that is NOT inside the <CFOUTPUT></CFOUTPUT> tag. This is helpful if you are trying to reduce some white space if the tag creates it. On some tags, you may not want to use this tag, but since this is not necessary in this tag, we will use it.

We want to pass this tag an attribute to return. Lets name this attribute ?echo?. We want to be able to throw an error if this has not been passed, so we will then insert the next few lines of code:

<cfif not isDefined("Attributes.echo")>
    <CFOUTPUT>
    Error, you must provide a string to echo!<BR>
    </CFOUTPUT>
    <cfexit method="EXITTAG">
</cfif>

The CFIF checks to make sure that attributes.echo (remember, we are passing echo), and makes sure that is has been defined. If it is not defined, it will throw the error ?Error, you must provide a string to echo!?. Notice that there are <CFOUTPUT> tags that surround the error message, even though there are no Cold Fusion variables being used. This is because of the first line that does not allow any text unless it is encapsulated within the <CFOUTPUT> tags. 

Second, you will notice the tag <CFEXIT>. This tag is used to break out of processing the custom tag. If this did not exist, it would throw the error message and then keep trying to process everything else in the tag, throwing more errors. It is better to just stop the tag from completing, and save you a lot of headaches in the future.

Now let?s go ahead and return the echoed string. We have decided to give the returned variable the name of return_echo. So lets go ahead and set that value. Insert the following code into your tag:

<cfset caller.return_echo = attributes.echo>

This sets the value to be attributes.echo, what we originally passed the tag. Notice that the variable is called caller.return_echo. This is because you are returning the variable to the caller, the page you will be calling the custom tag from. 

We are almost done, one more line to add to the custom tag. Remember that first line where we suspended all output that was not within the <CFOUTPUT> tags? As you may have guessed, this will have an effect on the rest of the document that calls the custom tag, so we need to switch that off. So let?s add the last line of this custom tag:

<cfsetting enablecfoutputonly="no">

And there, you are done writing your first custom tag! Here is what your code should look like:

<cfsetting enablecfoutputonly="yes">
    <cfif not isDefined("Attributes.echo")>
        <CFOUTPUT>
            Error, you must provide a string to echo!
        </CFOUTPUT>
        <cfexit method="EXITTAG">
</cfif>
<cfset caller.return_echo = attributes.echo>
<cfsetting enablecfoutputonly="no">

Now let us write a page to call this tag. First we will make sure that it does throw an error. That is where I like to start, so I am sure that the error works. Make sure you save the code you have just written to a file called ECHO.cfm. Put this in the same directory that we are creating the document to call it.

Create a new CFM page and call it call_echo.cfm. It is very important that you save this in the same directory that your echo.cfm tag was just save in, either that or place it in your Custom tag directory. 

One you have created the call_echo.cfm page, add these lines in the body:

<CF_ECHO>
    <CFOUTPUT>
    #return_echo#<BR>
    </CFOUTPUT>
    Woo hoo! I have written a custom tag!

When making a call to your tag, you have to append CF_ to the beginning, so that ColdFusion knows that it is a custom tag. Notice we did not pass a string to the tag yet, we want to make sure that it returns the error. Go ahead and save call_echo.cfm and run it. See your error message? You should also see that the variable return_echo is not defined. This is because it was not returned by the tag.

Now let?s pass it a string. Replace <CF_ECHO> with <CF_ECHO echo=?I like fruity pebbles for breakfast?> or whatever you do like for breakfast. Now save call_echo.cfm and run it again. It should return the following:

I like fruity pebbles for breakfast
Woo hoo! I have written a custom tag!

There you go, your first simple custom tag. Now lets make some simple adjustments to the tag itself. Anything that you can do in a CFM page, you can pretty much add to a tag. Lets add one more line above the last <CFSETTING> tag:

<cfset caller.echo_count = len(attributes.echo)>

You guessed it, this will now return the length of the string as well. So lets add this output to our call_echo.cfm page and see what we get returned. Your call_echo.cfm page should have the following:

<CF_ECHO echo="I like fruity pebbles for breakfast">
    <CFOUTPUT>
    #return_echo#<BR>
    This has #echo_count# characters in it.<BR>
    </CFOUTPUT>
    Woo hoo! I have written a custom tag!

When we run this, we should get the following output:

I like fruity pebbles for breakfast
This has 35 characters in it.
Woo hoo! I have written a custom tag!

See where I am going with this? There are so many things you can do within the tag, play around with it. 

Now I am going to show you one more thing that is helpful when creating a tag. Sometimes you may want a tag that will include a menu or things of that nature. You may not want to return variables, so lets change this tag so that we do not want to return the variables.

After your closing </CFIF>, remove your to <CFSET> tags. We do not need them for this. Now above the last <CFSETTING> tag, add the next 2 lines:

<CFOUTPUT>
    Echo String: #attributes.echo#<BR>
    I have found #len(attributes.echo)# characters!<BR>
</CFOUTPUT>

Now go back to your call_echo.cfm page and lets get rid of that <CFOUTPUT> tag and everything between it, so now all you should have in this document is:

<CF_ECHO echo="I like fruity pebbles for breakfast">

Woo hoo! I have written a custom tag!

So run it and see what you get. You should get the following returned:

Echo String: I like fruity pebbles for breakfast
I have found 35 characters!
Woo hoo! I have written a custom tag!

See the difference? So it is up to you and your needs if you want to return the variables or just display it like we have just done. You may want to display a list of links on your website using a custom tag. You can create the tag like we did, query a database or hand code the links, and just call the tag on your page when you want it displayed. Maybe you can do this for your contact information as well. These are simple uses, but I hope you get the idea that the possibilities are only limited by your imagination.

Good luck and happy coding!