The CFINCLUDE Library

 
Dec 20, 1999

by Michael Dinowitz

We have a problem. There are two ways to include code dynamically in a ColdFusion template: CFINCLUDEs and CFMODULEs. So what's our problem? A CFMODULE takes a little over twice as long as a CFINCLUDE (as a base) for the same operation. This is not really a problem with CFMODULEs, but with programmers. Few of us know when to use a CFMODULE or when a CFINCLUDE is better. This paper will tell you which is best when and lay out a new method of using code.
Let's start by looking at a small piece of code.

<CFLOCK TIMEOUT ="15" THROWONTIMEOUT="No" NAME="SessionClear" TYPE="EXCLUSIVE">
<CFSET StructClear(Session)>
</CFLOCK>

This is a very easy piece of code that many people use to clear out all session variables for a user. Most people will use it directly in their code if they can. Others will wrap it into a CFMODULE for use. The first way is, of course, the faster, but not many people will do it. The real question here is: why wrap it as in a CFMODULE at all?

Why?

Why is a CFMODULE slower than a CFINCLUDE? Don't they do the same thing? The answer has to do with processing. A CFMODULE is processed in its own 'memory space', basically as its own template totally separate from the calling template. This means that certain information has to be passed in. Url, Form, CGI and the various state management variables have to be passed in (automatically by ColdFusion). This has a lot of overhead. Add to this passing whatever variables you want manipulated and you'll start to see the CFMODULE take longer. (Please note that when I talk about time and overhead, I'm talking in 10's of milliseconds. A difference that few will ever notice, but is important, especially in large sites). A CFINCLUDE, on the other hand, is processed in the same 'space' as the calling template. It uses all the variables from the template and nothing is passed. This results in a large savings in time.

When?

The real question is, which do I use when? My rule is rather simple. If you're not passing anything around, you don't really need a CFMODULE. If you're just working on CGI, URL, Form, Session, Server, Application or Client variables, a CFINCLUDE might be better. If you're just doing a set of a lot of variables, then a CFINCLUDE is definitely better.

What to do?

What we need here is structure. We know when to use CFINCLUDEs over CFMODULEs. We know what we'll be saving and we know how to use CFINCLUDEs. The problem now is having a way of re-using code. We need some form of 'standard library' for CFINCLUDEs. (We also need a 'standard library' for CFMODULEs, but that's a different paper.) We need a location to store these CFINCLUDEs much like the CustomTags directory for CFMODULEs. For this I suggest using the following directory:

CFINCLUDE Directory

This will allow people to use a 'standard library' of CFINCLUDE code that has a set location that will be the same on most (if not all) machines. This also happens to mimic the structure that Allaire has created for their own includes.

<CFINCLUDE Template="/CFIDE/Includes/DeleteSession.cfm">

JavaScript

You'll also notice that there's a location there for scripts as well. This is used by Allaire for JavaScripts that they want to be used 'globally' to the site like the WDDX JavaScript. I suggest that you look at the CFMLjsLibrary from Shlomy Gantz and JavaScript Vision from Gary Krajci. These are two JavaScript libraries that can be included in this directory. The effect is the same as the CFINCLUDEs Library. You have a standard location with a collection of well-tested code to do some operations. This code can be used at any time on the site without worrying about where the files are. This will also enhance your programming abilities as you now have a new library to 'install' on any machine which you can work with. Standard code that has been written and tested by people in the field can save you a ton of time and effort.
Before you start thinking I'm developing a rival to Fusebox or CFSAM, think again. This library setup is an enhancement to both of these coding methods. This library is an enhancement to almost any coding method you may choose.

Oh, as for those speed stats: Without passing any variables to a CFMODULE, the difference in time was 130 ms. vs. 60 ms. in favor of the CFINCLUDE. Now that's significant.

Add a Comment
(If you subscribe, any new posts to this thread will be sent to your email address.)
  
Privacy | FAQ | Site Map | About | Guidelines | Contact | Advertising | What is ColdFusion?
House of Fusion | ColdFusion Jobs | Blog of Fusion | AHP Hosting