This is the sixth installment of a 6 part series. All sections will help to introduce you to some basic programming concepts that will all carry through and help you as you learn ColdFusion. If you are looking for any of the other installments to this series, you can get to them below.
- What is Programming?
- Proper Syntax
- Variables and Data Types
- Conditional Processing
- Arrays and Structures
- Modular Code
One of the things that I love about ColdFusion is that it gives you plenty of tools to keep from reinventing the wheel. Being able to use the same set of code in multiple places, otherwise known as “code reuse” will not only save you time from doing things over again, but will let you make a change to that code in one place but have it affect everywhere you are using it.
This is one of the most useful things you will use in ColdFusion so let’s take a look at how we can take advantage of the four most common ways to reuse code in ColdFusion.
- Custom Tags
- CFC Functions
An “include” is a ColdFusion file that is included within another ColdFusion file. These include files work as if you were to copy and paste the code directly into a page, but instead of copying and pasting the entire set of code, we are simply going to include via a <cfinclude> tag.
One of the more common uses of an include is to use them to display your header and footer file on a website application. Imagine you had a website with a navigation bar at the top and let’s assume you have 100 pages in your website. What would happen if you had to add a new item to your navigation bar if you had all your code on each of those individual 100 pages? Aside from spending hours trying to make the change to every page, you’d probably be a little frustrated.
But if you were using an include, you could update the navigation bar in one file and because it’s included on all 100 pages, the change you make in the single file will affect every page in the site.
Let’s look at some code to demonstrate. This is a sample welcome page with some very basic HTML to simply display a welcome message and a navigation bar near the top of the page.
<!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>Welcome Page</title> </head> <body> <div align="center"><a href="home.cfm">Home</a> | <a href="contact.cfm">Contact</a></div> <p>Hi and welcome to How to Program with ColdFusion.</p> </body> </html>
As you can see this is all located in one single page and would require an update to any page that was using this information. But let’s put this into a header and footer file so we can reuse this code efficiently. To get started we want to copy everything from the <body> tag up to use as our header.
<!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>Welcome Page</title> </head> <body>
Create a new file and call it header.cfm and paste the above code into it. Next we will do the same thing with the code from the ending </body> tag down.
What you are then left with on the original page:
<div align="center"><a href="home.cfm">Home</a> | <a href="contact.cfm">Contact</a></div> <p>Hi and welcome to How to Program with ColdFusion.</p>
Next we want to include the header and footer file back into the original document. We do this using the <cfinclude> file along with a parameter called “template”.
<cfinclude template="header.cfm"> <div align="center"><a href="home.cfm">Home</a> | <a href="contact.cfm">Contact</a></div> <p>Hi and welcome to How to Program with ColdFusion.</p> <cfinclude template="footer.cfm">
If you were to load that page now, you would find that the page looks exactly the same, only now if you want to add in a new navigation item, you would add it to the header file and it will change that code on every page you use that file in.
A custom tag is another really powerful way to reuse your code. Most developers use custom tags to create code functions that will process something to be displayed on your page like special formatting or page navigation. To give you just a basic understanding of the concept, however, we are going to use the header example above to create a custom tag.
A custom tag starts off like any other ColdFusion page, just a blank page named with a .cfm extension. In this example, we have a page called header.cfm. Your custom tag name is always going to be the name of the file minus the extension. So in this case our custom tag is called “header”. Custom tags should be placed in either the same directory as the calling page or in the \CustomTags directory located in the ColdFusion installation root.
To call a custom tag you call it using special syntax starting with “<cf_”. This let’s ColdFusion know that you aren’t trying to use any of its ColdFusion tags and should instead look for a file with this particular name. In this case we are going to use <cf_header>. As you can below we have replaced the <cfinclude> of the header and instead are now calling it as a custom tag.
<cf_header> <div align="center"><a href="home.cfm">Home</a> | <a href="contact.cfm">Contact</a></div> <p>Hi and welcome to How to Program with ColdFusion.</p> </body> </html>
There are more advanced things you can do with a custom tag like passing it parameters that the custom tag will then process and I will show you how to do that in later tutorials. But this example, should have given you a good understanding of how we can use custom tags in our daily programming activities.
CFModule is very similar to a custom tag, except that you aren’t required to place your custom tag in the customtags folder. This is useful for example, when using a shared hosting environment and you don’t have access to the custom tag directory or if you just want to easily manage your custom tags on your main website directory. You can call the custom tag using the <cfmodule> tag and passing in any name/value pairs as shown.
You can pass variables to the custom tag the same way you would with a standard custom tag call as well.
<cfmodule template="header.cfm" title="My Home Page" BackgroundColor="white">
The last type of code reuse we will talk about is a CFC or ColdFusion Component. With my first two examples of using an include and a custom tag, we were sending data back to the browser. CFC’s, however, typically are used for behind the scenes type functions. This would include things like calculations, database queries and other processing or business rule types of tasks.
The nice thing about CFC’s is that they are plain text files with a .cfc extension and do not require compilation like other programming languages.
A CFC will contain several required parts to it. First, the entire set of code must be wrapped inside of a <cfcomponent> tag. Inside the <cfcomponent> tag there can be one or more <cffunction> tags. The <cffunction>’s are the methods within the component that you are going to call. Sound confusing? Well, let’s break down the code for you so you can see exactly how it looks.
<cfcomponent> <cffunction name="GetCatalog" returntype="query"> <cfargument name="UserID" required="true"> <cfquery name="qCatalog"> SELECT CatalogName, CatalogID FROM Catalogs WHERE UserID = #arguments.UserID# </cfquery> <cfreturn qCatalog /> </cffunction> </cfcomponent>
This is a basic example of a CFC making a simple call to a database and returning a record set. It starts off with the required component tag. Inside the component tag I have one single <cffunction> with a method I called “GetCatalog”. Inside the function, I am requiring that a variable called UserID be passed so that I can use it to pull the correct catalog for that user.
After I run the query passing in the UserID, I will get back a result set from the query called qCatalog. It is that value that I will pass back to the calling page. I return it back by with the syntax <cfreturn qCatalog />.
Now that we have this CFC how do we go about using it?
You can call a CFC from within the same page the CFC is located in. To do this you would simply reference the component by name in the “component” variable in the tag. However, I like to store my CFC’s in a separate folder called “components”. So in this example, I would save this set of code as CatalogObj.cfc in the components folder I have already created on my server and reference the path with dot notation as “components.CatalogObj” from my root directory. To call a CFC we will be using the <cfinvoke> tag along with the <cfinvokeargument> tag to pass the UserID variable I require.
<cfinvoke component="components.CatalogObj" method="GetCatalog" returnvariable="menuReturn"> <cfinvokeargument name="UserID" value="#userid#"> </cfinvoke>
As you can see by the code above, the code I have to keep on the calling page is minimal but I can return a large set of results back to it via the CFC page. And because I have stored this set of code as a separate object within the website I can reuse the code many times over by using the <cfinvoke> tag anywhere else within the application.
This last lesson in our 6 part series is probably the most useful lesson but can also be the most confusing because it introduces several new ColdFusion tags and code snippets. But don’t panic. We are only introducing them as concepts to you in this tutorial and will go over the actual code in much more detail in later tutorials. After a short time, these will become second nature to you as you use them in your daily programming activities.
I hope you have enjoyed this tutorial and I invite you to browser through our other introduction level tutorials and learn more about the ColdFusion language here at How to Program with ColdFusion. Good luck!