ColdFusion does not have a lot of functionality to aid in debugging your applications. The built-in debug information that you can access through the ColdFusion administrator gives you some basic information, but if you are using complex objects, structures, or CFCs, you are left without a way to examine these constructs. For example, if you use custom User and Cart objects in a session variable, the debugging information will only show you the following:
Session Variables:
cart=Struct (17)
cfid=11235
cftoken=23412440
sessionid=MYAPP_11235_23412440
urltoken=CFID=11235&CFTOKEN=23412440
user=Struct (5)
The information is not very useful. One way to handle this is to add debugging information to each page as you develop. The technique I will show here can also be used in a production environment because it can be turned on through a URL variable, and is tied to the user's session.
The Application.cfm file has a lot of uses, because of it's ubiquitous nature -- it is processed before every page in your site. You can use this versatility to capture URL variables to perform a variety of different functions, such as logging in, logging out, and setting up global variables. We'll use it to set up a debug variable that when set will display information at the bottom of each page. To make it secure, we'll put a password on it, but you can also use the same technique to incorporate your own login system.
The basic flow is this:
That is all we need to do in the Application.cfm. The reason we set a session variable is so that you can set up debugging for a single user session that will work on any page in the site. In other words, when you initialize debugging, you will be able to view any page on your site and see the same info. When the session ends, debugging ends also.
The debugger functionality will be contained in OnRequestEnd.cfm, which will be explained next. For now, here is the code for Application.cfm:
<!---Debugging stuff!!!! --->
<cfif isdefined ("url.debug")>
<cfif url.debug EQ "mypassword">
<cfif NOT IsDefined("session.debug")>
<cfset session.debug = true>
<cfelse>
<cfset session.debug = NOT(session.debug)>
</cfif>
<cfelse>
<cfset session.debug = false>
</cfif>
</cfif>
<!--- End debugging stuff --->
To call the debug information, all we need to do is type the variable into the URL:
http://www.mysite.com/somepage.cfm?debug=mypassword
That will activate the session variable and display the info to you.
The Application.cfm file is executed before every page in your site. ColdFusion also has a file that is executed AFTER every page in your site. It's called OnRequestEnd.cfm, and if it exists, it will be executed. This is where we will put the debugging information.
The debugging information will vary from application to application, but the following will display info about a variety of different built-in structures using the <cfdump> tag. The <cfdump> tag has built-in formatting for structures, including the form, URL, session, and other built-in structures of ColdFusion. XML structures will also be broken down for examining the contents of XML.
Everything will be wrapped in a <cfif> statement checking to see if the session.debug variable is set to true:
<cfif IsDefined("session.debug") and session.debug EQ "true">
<div>
<h1>Session</h1>
<cfdump var=#session# />
<br><br>
<h1>Application</h1>
<cfdump var=#application# />
<br><br>
<h1>Form</h1>
<cfdump var=#form# />
<br><br>
<h1>URL</h1>
<cfdump var=#url# />
<br><br>
<h1>Request</h1>
<cfdump var=#request# />
<br><br>
<h1>Cookies</h1>
<cfdump var=#cookie# />
<br><br>
<h1>CGI</h1>
<cfdump var=#CGI# />
<br><br>
<h1>Server</h1>
<cfdump var=#Server# />
<br><br>
<h1>Variables</h1>
<cfdump var=#variables# />
<br><br>
</div>
There are a few things you'll notice when you run this code. For one, if there are any structures in your session or other variables, the structures will be broken down into a neat table for viewing. Also, the Variables structure will show up all user-defined function references, and also queries executed on the page. You can turn off debugging by simply returning to any page in your site with the debug URL variable in place.
http://www.mysite.com/somepage.cfm?debug=mypassword
The url will work with any page in your site, because it keys off the Application.cfm file.
If you've ever turned debugging on in the ColdFusion administrator with a site designed with CSS positioning, you know that the debugging info is lost behind the page. Debugging info has no CSS positioning attributes, so it gets lost. The same will happen if you attempt to use the code in OnRequestEnd.cfm as outlined above. A quick fix is to introduce some JavaScript to the page to force the debugging information <div> tag to the bottom. First, name the <div> and give it some attributes:
<div id="forceBottom" style="position:absolute; top:0; left:0;">
Next, at the bottom of the page (still within the <cfif> statement) add some scripting to calculate the page bottom and force the forceBottom <div> tag to the bottom of the page:
<script language="text/javascript">
var allDivs = document.getElementsByTagName("div");
var maxBottom = 0;
for(var i=0; i<allDivs.length; i++) {
var divBottom = allDivs[i].offsetTop + allDivs[i].offsetHeight;
if (divBottom > maxBottom){
maxBottom = divBottom;
}
}
document.getElementById("forceBottom").style.top = maxBottom + "px";
</script>
Now the debug information will work with a CSS-positioned site as well.
You can also add custom elements to the debug info page, such as sending an email to yourself with a specific variable:
<cfmail to="me@mydomain.com"
from="me@mydomain.com"
subject="Debugging CF page #DateFormat(Now())# for user #session.user.name#"
type="html"
>
<cfdump var=#session.user#>
</cfmail>
or logging the debug session:
<cflog file="myAppLog"
text="Debugging http://#CGI.http_host##cgi.script_name#
on #DateFormat(Now())# #TimeFormat(Now())#">
There are many possibilities. You can also format your variables in different ways rather than using the <cfdump> tag. In any case, this was only designed as a basic tutorial to show you the technique. How you use it is up to you.
The Application.cfm and OnRequestEnd.cfm pages have many uses. Using a simple technique to trap a URL variable, we were able to set up a private debugger for the site developer.