By Bouton Jones
© 2009 Bouton Jones
About the Workshop
Custom Error Handler Templates in CF MX 7 and Above
This workshop is accessible for beginner ColdFusion developers but it will be innovative enough for the more advanced developers. The topic is error customization through CFERROR and the Application template (using CF MX 7.)
Typically, the default ColdFusion Error message is ugly and alarming. Customizing error messages can make a more pleasant experience for the user and a more robust solution for the developer --- but they come with new challenges and liabilities. While the basic technique in this workshop is straight from a Forta book, the presentation implements several improvements and techniques that Forta left out as well as tips for addressing some of the hidden challenges inherant with these techniques.
PLEASE NOTE: There are several methods for customizing error messages but this workshop will ONLY focus on CFERROR customization though the Application.cfm / Application.cfc file. Although at the end of the work shop I will list other methods that you are encouraged to look up online or in books.
Preface
This workshop assumes a beginner developer's understanding of ColdFusion. It assumes you can create a simple template, add a few CF tags, create a Aplication.cfm or Application.cfc template, and debug your errors. But while the target of this workshop is begining developers, I hope some of the more advanced users can benefit from a few innovations in this solution. When I implemented the Custom Error procedure, I started with Chapter 19 "Introducing the Web Application Framework" (pgs. 542-551) in Macromedia ColdFusion MX 7 Web Application Construction Kit by Ben Forta & Raymond Camden. But I added a unique improvement --- or a least so I thought.
(After implementing this technique, I found that another developer had arrived at a similar solution before me:
CF Error Handling - A pinch of this, a pinch of that
By: Al DiMarzio, HB Graphics
Guilford, CT
http://www.hbgraphics.com/tips_tutorials/
9-cf_error_error_handling.cfm#2
As the saying goes "Great minds think alike.")
Files
Rather than reinventing the wheel, I suggest you download the templates I've already created and debugged and adapt them to your own situations.
Default ColdFusion Error Messages
Here are some screen captures of error messages before customization:


Aren't they pretty?
[Hint: No.]
Benefits?
What are the benefits over the usual ColdFusion error messages?
- More professional and attractive appearance. (Doesn't look broken.)
- More user friendly. Addresses the user directly with comprehensible information.
- More comforting: Reassures the user that we are aware of the problem and will act to fix it.
- Faster: Notifies the developer quicker. (Usually before the client has time to call the application owner and the application owner has time to contact the developer)
- More efficient: Collects valuable information about a programming error for the developer without having the developer interview the user
- More proactive: Tracks user validation errors. Is someone trying to crack your web form? Are a lot of users having the same problem submitting a form? (IE are several users consistently getting confused by the same instructions?)
Caveats
- Two of the three custom error templates are limited in the ColdFusion tags and variables they can use. This limits their customization and functionality. (Fortunately there is a way around these limitation which this workshop will address. Thatis the part of the presentation that goes "beyond Forta.")
- Custom error messages are less informative that the ugly default error messages. I recommend temporarily disabling the custom error messages once you're aware of an error and restore the templates once you've identified a solution.
- You must debug the error templates before making them live. If you have any errors in the custom error templates when you call them though the
CFERRORtags, they will generate an infinite loop: A blank browser window and a persistant "reload" noise.
Steps
Development can be broken down into five major steps.
- Create four or five new templates. The first three are the "Custom Error" Templates (a Request Error template, an Exception Error template, and a Validation Error template as described by Forta)
- Debug each template by opening them in a browser.
- Add the three CFERROR tags to your Application.cfs file. (Or your Application.cfm if you haven't gotten around to using Application.cfc.)
- Further test and debug on development. Don't wait for errors. Create errors where there are none.
- Further test and debug on production. Create errors even in applications that don't have any.
Definitions
- Request Error
- Handles any exception that is not otherwise-handled. The request error page runs after the CFML language processor finishes. As a result, the request error page cannot include CFML tags, but can display error page variables. A request error page is useful as a backup if errors occur in other error handlers.
- Exception Error
- Handles specific exception errors. You can specify individual error pages for different types of exceptions.
- Validation Error
- Handles server-side form field data validation errors. The validation error page cannot include CFML tags, but it can display error page variables. You can use this attribute only on the Application.cfm page. It has no effect when used on any other page. Therefore, you can specify only one validation error page per application, and that page applies to all server-side validation errors.
[Source: Adobe Livedocs]
Error Variables Info
(From Adobe Website)
The exception-handling template specified in the template attribute of the cferror tag contains one or more error variables. ColdFusion substitutes the value of the error variable when an error displays.
The following table lists the error variables:
Template type |
Error variable |
Description |
|---|---|---|
| Exception Request Monitor |
error.diagnostics |
Detailed error diagnostics from ColdFusion Server. |
error.mailTo |
E-mail address of administrator notified (corresponds to the value set in the mailTo attribute of cferror). |
|
error.dateTime |
Date and time when the error occurred. |
|
error.browser |
Browser that was running when the error occurred. |
|
error.generatedContent |
The failed request's generated content. |
|
error.remoteAddress |
IP address of the remote client. |
|
error.HTTPReferer |
Page from which the client accessed the link to the page where the error occurred. |
|
error.template |
Page being executed when the error occurred. |
|
error.queryString |
URL query string of the client's request. |
|
| Validation |
error.validationHeader |
Text for header of validation message. |
error.invalidFields |
Unordered list of validation errors that occurred. |
|
error.validationFooter |
Text for footer of validation message. |
[Source: Adobe Livedocs]
Step One: Making the Exception Error Template
The most effective means of developing a set of customized error message templates is to adapt a working set of templates to your own needs. (BTW: It won't be necessary in this workshop to write down any of this code or variable names because the necessary files are availalble for download.) The Exception Error Template will use a special set or variables in the ERROR scope that help in debugging the error. In addition you can all of the other ColdFusion variables, attributes, and tags that can help you --- including the CGI variables and the CFMAIL tag.
