CFML Reference
|
|
ColdFusion Tags
|
cferror
Description
Enables the display of customized HTML pages when errors occur. This lets you maintain a consistent look and feel within your application, even when errors occur.
Category
Exception handling tags
Syntax
<cferror type = "request" or "validation" or
"monitor" or "exception"
template = "template_path"
mailTo = "email_address"
exception = "exception_type">
See also
cfrethrow,
cfthrow,
cftry cfcatch
Attributes
Attribute |
Description |
type
|
Required. The type of error that the custom error page handles.
|
Template
|
Required. The relative path to the custom error page.
|
mailTo
|
Optional. The e-mail address of the administrator to notify of the error. The value is available to your custom error page in the MailTo property of the error object. For example: #error.mailTo# .
|
exception
|
Required. Type of exception. Required if type = "exception" or "monitor" .
|
Usage
Use the cferror
tag to customize error messages for all the pages in an application. You generally embed the cferror
tag in the Application.cfm
file. For more information, see Advanced ColdFusion Administration.
To ensure that error pages display successfully, do not use the cfencode
utility to encode pages that include cferror
.
Templates
The following table describes the template to use for each type of error.
Template type |
Description |
Use |
Exception
|
Dynamically invoked by the CFML language processor when it detects an unhandled exception condition. You can specify exception-handling templates in several ways:
- As part of an application using
cferror type = "exception"
- Using the ColdFusion Administrator
|
Uses the full range of CFML tags, making it more powerful than cferror type = "request" . |
Request
|
Includes only the error variables described in the Usage section. Cannot include CFML tags.
|
Use as a backup error handler for sites with high user interface requirements.
|
Validation
|
Handles data input validation errors that occur when submitting a form.
|
You must include the validation error handler in the Application.cfm file.
|
Monitor
|
Dynamically invoked by the CFML language processor when it first detects an exception condition, before it searches for cftry/cfcatch or cferror handlers for the exception.
|
Use for monitoring and debugging exception handling within complex applications.
|
Error variables
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.
|
Note If you specify type = "exception" or type = "monitor" , you can substitute the prefix cferror for Error ; for example, cferror.diagnostics , cferror.mailTo , or cferror.dateTime .
|
Example
<!--- This example shows the use of cferror. --->
<html>
<head>
<title>cferror Example</title>
</head>
<body>
<H3>cferror Example</H3>
<P>cferror provides the ability to display customized
HTML pages when errors occur. This allows you to
maintain a consistent look and feel within your
application even when errors occur. Note that no CFML
can be displayed in the resulting templates except
for the specialized error variables.
<P>cftry/cfcatch provides a more interactive way to
handle your CF errors within a CF template than cferror,
but cferror is still a good safeguard against general
errors.
<P>You can also use cferror within the Application.cfm
to specify error handling responsibilities for an entire
application.
<!--- Example of cferror call within a template --->
<cferror type = "REQUEST"
template = "request_err.cfm"
mailTo = "admin@mywebsite.com">
<!--- Example of the template to handle this error --->
<!---
<html>
<head>
<title>We're sorry -- An Error Occurred</title>
</head>
<body>
<UL>
<cfoutput>
<LI><B>Your Location:</B> #error.remoteAddress#
<LI><B>Your Browser:</B> #error.browser#
<LI><B>Date and Time the Error Occurred:</B> #error.dateTime#
<LI><B>Page You Came From:</B> #error.HTTPReferer#
<LI><B>Message Content</B>: <BR><HR width = 50%>
<P>#error.diagnostics#<HR width = 50%><P>
<LI><B>Please send questions to:</B>
<a href = "mailto:#error.mailTo#">#error.mailTo#</A>
</cfoutput>
</UL>
</body>
</html> --->
Copyright © 2001, Macromedia Inc. All rights reserved. |
|