Understanding ColdFusion Error Handling

By default, when an error occurs, ColdFusion displays diagnostic information to the user, and an entry is made in one of the ColdFusion logs. Not only does this make for a poor user experience, but it also means that the error was not trapped and dealt with in a better manner.

Several ColdFusion tools are available to handle errors in a better way. We'll discuss <cferror>, onError(), then <cftry>.

<cferror type="request">

When an error occurs, diagnostic information is displayed using a default page that looks nothing like the rest of the application. Using <CFERROR> allows you to decide the following:

• What parts, if any, of the error message are shown to the user

• The look and feel of the page

The attributes of the <cferror> tag are listed in Table 26.1.

Table 26.1. <cferror> Tag Attributes

ATTRIBUTE	DESCRIPTION
exception	To be discussed later in the chapter.
mailto	An optional attribute that sends an email address to the template specified.
template	The template to be displayed instead of the default error diagnostic page.
type	The type of error to catch. For now, consider Request and Validation.

The first type of error we'll cover is Request. It traps any error unless it is a server-side validation error. The ideal location for a <cferror> tag is in the Application.cfm file. If you don't place the <cferror> tag in Application.cfm, you'd have to place the tag on every page in your application.

You can find further information about server-side form field validation errors in Chapter 9, "FORM Variables Variables," and more on the Application files in Chapter 6, "The Application Framework."

Consider the following <cferror> tag placed in an Application.cfm file:

 <cferror type="Request"          template="ErrorTemplate.cfm"> 

Any errors that occur in a ColdFusion template call for ErrorTemplate.cfm to be processed. This includes ColdFusion syntax errors, which cause parsing errors, as well as errors that occur during template execution. For instance, a <cfquery> tag without a datasource attribute causes the error template to be called, because that is a syntax error. By the same token, a <cfquery> tag with a datasource attribute that points to a nonexistent data source also calls the error template.

What should be on the error template? That is your decision. Most likely, you will want it to look like the rest of your site. You may also choose to have some information about the error, and error variables can help you do that.

The error variables available are listed in Table 26.2.

Table 26.2. Error Variables for Type Request

VARIABLE	DESCRIPTION
Error.Browser	Browser that was running when the error occurred.
Error.DateTime	Date and time when the error occurred.
Error.Diagnostics	Detailed error diagnostics from the ColdFusion server.
Error.GeneratedContent	The failed request's generated content.
Error.HTTPReferer	Page from which the client accessed the link to the page where the error occurred. This will be an empty string if there is no referrer.
Error.MailTo	Email address of the administrator who should be notified (corresponds to the value set in the mailto attribute of <cferror>).
Error.QueryString	URL query string of the client's request. It is equal to the empty string if there is not a referrer.
Error.RemoteAddress	IP address of the remote client.
Error.Template	Page being executed when the error occurred.

You can use these variables only on the error template page. They act like regular ColdFusion variables in that they must have number signs (#) around them. But unlike other ColdFusion variables, they need not be surrounded with a <cfoutput> block. In fact, when the type is Request or Validation, no ColdFusion tags on the page specified in the TEMPLATE attribute are executed.

NOTE

There is a very good reason that no ColdFusion tags can be used on the error template when the type is Request or Validation. Consider what would happen if the error template itself had a syntax error. It would call the error template again, which would have an error, and call the error template again, which would have an error, and so on.

To avoid the chance of having an infinite loop, you cannot use ColdFusion tags on the error template when the type is Request or Validation. Even if you use some ColdFusion tags on the page, they are ignored.

<cferror type="validation">

As you learned earlier, when the type is Request, it traps all errors except server-side validation errors. Those are trapped when the type is Validation.

On a form, you can use two <input> tags as follows:

 <input type="text"        name="TheNumber"> <input type="hidden"        name="TheNumber_integer"        value="This is my error message"> 

You can use a <cferror> tag in the Application.cfm, like this:

 <cferror type="validation"          template="DisplayErrorValidation.cfm"> 

When you use the tags shown here, if the user fills the text box with a string, an error of type Validation will occur and the DisplayErrorValidation.cfm template will be called. The same rules apply to building this error template as to building the Request template, except that the CFERROR variables you can use on a validation error template are different. They are listed in Table 26.3.

Table 26.3. Error Variables for Type Validation

VARIABLE	DESCRIPTION
Error.InvalidFields	Unordered list of validation errors that occurred
Error.ValidationFooter	Text for the footer of a validation message
Error.ValidationHeader	Text for the header of a validation message

NOTE

Error.ValidationHeader is the following text: "Form Entries Incomplete or Invalid. One or more problems exist with the data you have entered."

Error.ValidationFooter is the following text: "Use the Back button on your web browser to return to the previous page and correct the listed problems."

Error.InvalidFields is a bulleted list of the default error messages, or the message in the VALUE attribute of the hidden form tag, if used.

onError()

Application.cfc is used to define code that is executed when specific events occur. The onEvent method is called when an error occurs, much like <cferror type="request">.

Application.cfc is explained in Chapter 6, "The Application Framework."

When an error occurs, ColdFusion executes the onError method, passing to it two required arguments as listed in Table 26.4.

Table 26.4. onError Arguments

ARGUMENT	DESCRIPTION
Exception	An exception structure, containing the error variables listed in Table 26.2 previously.
EventName	The name of the event handler that generated the exception (this will be a blank string if an error occurred during page processing).