onRequest

Description

Runs when a request starts, after the onRequestStart event handler. If you implement this method, it must explicitly call the requested page to process it.

Syntax

<cffunction name="onRequest" returnType="void"> 
    <cfargument name="targetPage" type="String" required=true/> 
    ... 
    <cfinclude template="#Arguments.targetPage#"> 
    ... 
</cffunction>

See also

onRequestStart, onRequestEnd, Method summary, Managing requests in Application.cfc in the Developing ColdFusion Applications

Parameters

ColdFusion passes the following parameters to the method:

Returns

This method does not return a value; do not use the cfreturn tag.

Usage

This event handler provides an optional request filter mechanism for CFML page requests (that is, .cfm pages requested using a browser). Use it to intercept requests to target pages and override the default behavior of running the requested pages. The following rules specify where and how you use the onRequest method.

• Implement this method only if the following are true:

  • The directory, and any subdirectories affected by this Application.cfc contain CFM files. The affected directory and subdirectories do not contain any CFC files that are intended to be accessed as web services, AJAX bind, using Flash Remoting, or using an event gateway.

  • You want to intercept the request and process it in a special way.

• If you do not implement this method, ColdFusion automatically calls the target page (or the CFC for a web service, Flash Remoting, or event gateway event).

• If you implement this method, it must explicitly call the target page, normally by using a cfinclude tag.

• Do not implement the onRequest method in any Application.cfc file that affects .cfc files that implement web services, process Flash Remoting or event gateway requests; ColdFusion does not execute the requests if you implement this method.

• Code in this method that precedes the call to the target page can perform the same functions as the onRequestStart method, and shares the Variables scope with the target page.

• Code in this method that follows the call to the target page can perform the same functions as the onRequestEnd method, and shares the Variables scope with the target page.

• If you implement this method, you can also implement the onRequestStart and onRequestEnd methods.

You can use this method to do preprocessing that is required for all requests. Typical uses include filtering and modifying request page contents (such as removing extraneous white space), or creating a switching mechanism that determines the exact page to display based on available parameters.

Example

<cffunction name="onRequest"> 
    <cfargument name="targetPage" type="String" required=true/> 
    <cfset var content=""> 
    <cfsavecontent variable="content"> 
        <cfinclude template="#Arguments.targetPage#"> 
    </cfsavecontent> 
    <cfoutput> 
        #replace(content, "report", "MyCompany Quarterly Report", "all")# 
    </cfoutput> 
</cffunction>