Managing requests in Application.cfc

ColdFusion MX provides three methods for managing requests: onRequestStart, onRequest, and onRequestEnd. ColdFusion processes requests, including these methods, as follows:

1. ColdFusion always processes onRequestStart at the start of the request.
2. If you implement an onRequest method, ColdFusion processes it; otherwise, it processes the requested page. If you implement an onRequest method, you must explicitly call the requested page in your onRequest method.
3. ColdFusion always processes onRequestEnd at the end of the request.

The following sections explain how you can use each of the Application.cfc request methods to manage requests. For more information, see entries for onRequestStart, onRequest, and onRequestEnd in CFML Reference.

Using the onRequestStart method

This method runs at the beginning of the request. It is useful for user authorization (login handling), and for request-specific variable initialization, such as gathering performance statistics.

If you use the onRequestStart method and do not use the onRequest method, ColdFusion MX automatically processes the request when it finishes processing the onRequestStart code.

Note: If you do not include an onRequest method in Application.cfm file, the onRequestStart method does not share a Variables scope with the requested page, but it does share Request scope variables.

User authentication

When an application requires a user to log in, put the authentication code, including the cflogin tag or code that calls this tag, in the onRequestStart method. Doing so ensures that the user is authenticated at the start of each request. For detailed information on security and creating logins, see Securing Applications. For an example that uses authentication code generated by the Macromedia Dreamweaver CF Login Wizard, see onRequestStart in CFML Reference.

Using the onRequest method

The onRequest method differs from the onRequestStart method in one major way: the onRequest method intercepts the user's request. This difference has two implications:

• ColdFusion does not process the request unless you explicitly call it, for example, by using a cfinclude tag. This behavior lets you use the onRequest method to filter requested page content or to implement a switch that determines the pages or page contents to be displayed.
• When you use cfinclude to process request, the CFC instance shares the Variables scope with the requested page. As a result, any method in the CFC that executes can set the page's Variables scope variables, and the onRequestEnd method can access any Variable scope values that the included page has set or changed. Therefore, for example, the onRequestStart or onRequest method can set variables that are used on the page.

To use this method as a filter, put the cfinclude tag inside a cfsavecontent tag, as the following example shows:

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

Using the onRequestEnd method

You use the onRequestEnd method for code that should run at the end of each request. (In ColdFusion versions through ColdFusion MX 6.1, you would use the OnRequestEnd.cfm page for such code.) Typical uses include displaying dynamic footer pages. For an example, see onSessionEnd in CFML Reference.

Note: If you do not include an onRequest method in Application.cfm file, the onRequestEnd method does not share a Variables scope with the requested page, but it does share Request scope variables.

View comments in LiveDocs