Custom Errors

In some cases, you might want to develop custom errors that control the way that error related output is presented to the end user in a given situation. In ColdFusion, you can do this by making use of the CFERROR tag. The CFERROR tag enables you to specify different types of error handling pages for various types of errors that might be encountered when working through your ColdFusion application.

CFERROR enables you to specify error pages for four specific types of errors:

• Validation. Validation errors occur when a user inputs something into a form field or other user-input device and the information causes problems with your applications logic flow. As an example, suppose you have a form action page that depends on knowing the age of a user. The user is supposed to have input his or her age into a form that was submitted to the action page. If for any reason the user age is not present or if the data entered is invalid, you'll want a way to control the way that the error caused by this validation failure is presented to the user.

• Exception. Exception errors are errors that are produced as a direct result of an application exception occurring. There are many reasons (such as memory corruption and corrupt templates) why an application exception can occur. Generally, however, these errors are unrecoverable from an application operation standpoint. This is in direct contrast to the validation error, which can easily be corrected by the user, allowing processing to continue. Because of this, you'd most likely want to have different error handling templates with different message sets for these two different types of errors.

• Request. Request errors act as the "catchall" error handler. Request errors handle any error that occurs that is not caught by any other portion of the error handling that you have in place. As a result of the way in which request errors occur, it's a good idea to make the error message you present to the user as a result of these errors very general in nature. It has to be general because it's unlikely that you'll be able to anticipate all the conditions that might generate a request error.

• Monitor. The monitor error type is a special type of custom error handler that you can use when debugging your applications. Specifying a template to run as a monitor error handler causes the contents of that template to be run prior to any other error handling processing (such as CFTRY/CFCATCH blocks within a given template). This is useful if you want to log the specifics of any errors encountered to a special log file prior to running the code through the standard CFTRY/CFCATCH blocks in your code.

Using CFERROR

You can use the CFERROR tag when you want to create and generate custom error messages from within your ColdFusion application code. Table 9.4 explains the attributes available for use with the CFERROR tag.

Table 9.4. CFERROR Attributes

Attribute	Description
Exception	This is a required attribute that specifies the type of exception that this particular custom error will handle. The choices available to you include validation, exception, request, and monitor. Each exception type was discussed in the previous section of this chapter.
MailTo	This optional attribute enables you to specify an email address for a person to whom you would like to have any errors mailed that were handled by this custom error template.
Template	This is a required attribute that contains the path to the template you want to use to handle this type of error.
Type	This is a required attribute that enables you to specify the type of error that this custom error template is designed to handle.

With CFERROR, you are somewhat limited in the types of errors that you can handle. With the exception of the monitor error type, all the types handled by CFERROR will be caught only when they are not explicitly handled elsewhere in your ColdFusion code. What does this mean? Examine the following example:

 <cftry>       <cfif NOT isDefined("UserID")>  <cfthrow message="I threw an error when I checked for ID">       </cfif>  <cfcatch type="any">       An error occurred  </cfcatch> 

You can see by this example that we are using a CFTRY/CFCATCH block to check whether the UserID value is defined. If it is not, we throw an error, presumably because this value will be required later in the processing.

With the CFTRY/CFCATCH block in place, if the UserID variable doesn't exist, the try/catch error handling will let us know. We then can tell the user this message: "I threw an error when I checked for ID." This alerts the user that a required parameter is missing and that our processing has come to a halt.

Assume that the try/catch error handling block was missing from our code. When our template got to the point where our logic depended on the presence of the UserID variable and it wasn't there, the user would get a messy standard ColdFusion message about an invalid or missing expression.

With CFERROR, even if we have no try/catch code in place, our error would still be caught. Suppose in the application.cfm file of our ColdFusion application that we have added the following line of code:

 <cferror type = "REQUEST" template = "defaultError.cfm"> 

The CFERROR type request acts as a catchall. Thus, when our application found that the UserID variable was missing, it didn't throw the ugly ColdFusion error back to our user. Instead, it presented him or her with the contents of the defaultError.cfm file, which is the template we've specified in our CFERROR statement.

When making use of the CFERROR tag, you are given some default variables that are returned if CFERROR is executed. These variables can be used to provide you or your users with more information about the error encountered. These variables can be output or appended to an email message to the administrator of your site, just like any other ColdFusion variable.

The variables that you have available to you differ depending on the error type that your CFERROR statement has been written to handle. Table 9.5 lists the variables returned by CFERROR for the exception, request, and monitor error types.

Table 9.5. Error Variables Returned by CFERROR When the Error Type Is Exception, Request, or Monitor

Variable Returned	Description of Variable
Error.Browser	This variable returns to you the variable running on the client machine when the error was returned.
Error.DateTime	This variable returns to you the date/time value associated with the time when the error was generated.
Error.Diagnostics	This variable returns detailed error information from the ColdFusion Server (if available) about the error.
Error.GeneratedContent	This variable returns the generated content of the request that failed.
Error.HTTPReferer	This variable returns the uniform resource locator (URL) of the page that the client was on prior to coming to the page where the error was generated (in other words, the referring page).
Error.MailTo	This is the email address to which this error message was reported (if one was specified in the original CFERROR statement).
Error.QueryString	This variable returns the URL query string of the request that generated the error.
Error.RemoteAddress	This variable returns the Internet Protocol (IP) address of the client machine that generated the error.
Error.Template	This variable returns the name of the template that was being executed when the error was generated.

Table 9.6 demonstrates the variables returned by CFERROR for the validation error type.

Table 9.6. Error Variables Returned by CFERROR When the Error Type Is Validation

Variable Returned	Definition of Variable
Error.InvalidFields	This variable returns a list of validation errors that occurred.
Error.ValidationHeader	This variable returns the text of the validation header.
Error.ValidationFooter	This variable returns the text of the validation footer.