TechNote (Archived)

ColdFusion MX: Incorrect output behavior when using Sitewide Error Handler

Issue

In Macromedia ColdFusion MX, the sitewide error handler does not function properly. The template where the error occurred will be displayed up to the point where the error occurred and the sitewide error handler template displays after the template on the same page. This TechNote explains how to work around this problem.

In ColdFusion MX versions up to and including Updater 3, the sitewide error handler does not function properly. This has been reported as Macromedia issue 48921 and is resolved in ColdFusion MX 6.1.

This problem is only apparent if you have defined a sitewide error handler in the Settings page of the ColdFusion Administrator. When an error occurs in a template, ColdFusion MX will generate the output of the template up to the point of the error, then it will display the sitewide error template. This can cause the page to display improperly. For instance, if the error occurs in the middle of an HTML table, then the sitewide error template is displayed, it may not be rendered properly by the browser. The result is that the user may not see the sitewide error template and may even see garbled output. A workaround is provided here that ensures that only the sitewide error template is displayed when an error occurs.

Solution

Enter the following code as the body of your sitewide error handler template:

 <cfset request.myerror = structnew()><cfset request.myerror = duplicate(error)><cfscript> getPageContext().forward("/error2.cfm");</cfscript>

Do not put any other code in this template.

Create a new template or rename the previously non-functioning error template. This template will be your properly functioning sitewide error handler template. Note that in the example code above, a new template called œerror2.cfm is created and it is located in the web root. It must be in the web root and the path should be relative to the web root. For instance, if the sitewide error template is going to be in a directory off the web root called œerrors and will be called œnewerror.cfm, the code would look like this:getPageContext().forward("/errors/newerror.cfm");
Put the following code at the top of the new template created in step 2:
```
 <cfset error = structnew()><cfset error = duplicate(request.myerror)> 
```
Note: The first line of this code is not necessary. It is simply included to illustrate that the results are being put into a structure.
Use the new sitewide error handler template to display whatever generic sitewide error messages you would like to display to your users. The error scope will still be available in this template for displaying specific information about the error, or for sending messages with error details.

ColdFusion MX has the ability to interact with J2EE elements so that it can integrate easily with JSPs and servlets. A bonus of this capability is the ability to do server-side page forwarding while sharing the request scope.getPageContext().forward() is significantly different than using a client-side forwarding approach like thecflocation tag. cflocation issues a 302 response to the client and gives it a new URL to request. Since this is a new client request, all of the data in the request scope is lost. Using the forward method of the pageContext object as we do in this example allows us to forward the request to a new page while maintaining all of the variables in the current request scope. Thus we simply copy the error scope into the request scope and forward to the new page. We then keep all of the error details (which we want) and get rid of the partially generated template that threw the error (which we do not want).