onMissingTemplate

Description

Runs when a request specifies a non-existent CFML page.

Syntax

<cffunction name="onMissingTemplate" returnType="boolean"> 
    <cfargument type="string" name="targetPage" required=true/> 
    ... 
    <cfreturn BooleanValue /> 
</cffunction>

See also

Method summary, Handling errors in Application.cfc in the Developing ColdFusion Applications

Parameters

ColdFusion passes the following parameters to the method:

Returns

A Boolean value. True or no return value specifies that the event has been processed. False specifies that the event was not processed.

Usage

ColdFusion invokes this method when it encounters a file not found condition, that is, when a URL specifies a CFML page that does not exist.

The onMissingTemplate function must return true to indicate that the event has been processed, or return false to indicate that the event has not been processed. If the function does not return a value, it is assumed to be true. If the function returns false, ColdFusion invokes the standard error handler. If an error occurs within the onMissingTemplate function, the error handler is not invoked. Therefore, you must use try/catch blocks in your missing template handler and, if the catch block cannot handle the error, it must set the function return value to false so the standard error handler can report the error.

If the onMissingTemplate function is invoked, the onApplicationStart and onSessionStart event handlers are first invoked, if appropriate, but the onRequestStart, onRequest and onRequestEnd handlers are not invoked, and processing of the request terminates when the onMissingTemplate handler returns.

All standard scopes, including the Application, Session, and Client scopes, are available in the onMissingTemplate function, if they are enabled.

To include the contents of a page in the onMissingTemplate function, use the cfinclude tag. Do not any other method to include or redirect other page content, including tags and functions such as cflocation, GetPageContext().forward(), and GetPageContext().include().

Use the This.welcomeFileList variable to keep this function from executing if all of the following are true:

• Your web server uses a welcome file list with one or more CFML files (such as index.cfm), that it tries to access when a user enters a URL that ends with a directory name

• The web server sends a request for a CFML page on the welcome list to ColdFusion without first determining if the page exists.

• You want to allow users to browse web directories that do not have any files on the list.

For more information, see welcomeFileList in Application variables.

Example

<!--- The web.xml welcome-file-list includes index.cfm.  
    To allow web browsing, specify index.cfm in This.welcomFileList. ---> 
<cfset This.welcomeFileList="index.cfm"> 
 
<cffunction name="onMissingTemplate"> 
    <cfargument name="targetPage" type="string" required=true/> 
    <!--- Use a try block to catch errors. ---> 
    <cftry> 
        <!--- Log all errors. ---> 
        <cflog type="error" text="Missing template: #Arguments.targetPage#"> 
        <!--- Display an error message. ---> 
        <cfoutput> 
            <h3>#Arguments.targetPage# could not be found.</h3> 
            <p>You requested a non-existent ColdFusion page.<br /> 
                Please check the URL.</p> 
        </cfoutput> 
        <cfreturn true /> 
        <!--- If an error occurs, return false and the default error 
            handler will run. ---> 
        <cfcatch> 
            <cfreturn false /> 
        </cfcatch> 
    </cftry> 
</cffunction>