Handling Application Events

In this section of the User Guide we will talk about handling application events. When we say "application events" we are referring to custom methods you can define in your Application.cfc to handle key CFML events such as session start, application start, and more.

Application.cfc

Before diving into the various methods available to you let's first take a peek at how a Basis Application.cfc is structured.

<cfcomponent extends="Basis.App" output="false">
	
	<cfset this.name = "skeleton" />
	<cfset this.applicationTimeout = createTimeSpan(0, 2, 0, 0) />
	<cfset this.clientManagement = false />
	<cfset this.sessionManagement = true />
	<cfset this.sessionTimeout = createTimeSpan(0, 1, 0, 0) />
	
         <cffunction name="applicationStart" output="false">
		<cfset application.dsn = "" />
	</cffunction>

	<cfset variables.frameworkSettings.reloadFrameworkEveryRequest = true />

</cfcomponent>

Above is the stock Application.cfc found in the skeleton scaffolding application. Most things here should look familiar if you have done CFML development before. The only new item here would be variables.frameworkSettings. For more information about that see Framework Settings.

It is here in Application.cfc where you can setup session management, application timeouts, framework settings, and custom event handling.

Custom Events

The following are the event you may hook into:

• applicationStart
• applicationEnd
• sessionStart
• sessionEnd
• preRequest
• validateAccess
• postRequest

applicationStart()

This method is called when the application starts and is first created. The object factory is created and plugins are first loaded, then this method is called. You may create this method to provide additional handling on top of what Basis does on application start.

Example:

<cffunction name="applicationStart" output="false">
   <!--- Do something useful --->
</cffunction>

applicationEnd()

This method is called when the application ends and is destroyed. You may create this method to provide custom functionality for when the application is ended.

Example:

<cffunction name="applicationEnd" output="false">
   <!--- Do something useful --->
</cffunction>

sessionStart()

This method is called when a session is first created. You may create this method to provide custom functionality for when this happens.

Example:

<cffunction name="sessionStart" output="false">
   <!--- Do something useful, like load user variables, or components, or whatever --->
</cffunction>

sessionEnd()

This method is called when a session is destroyed. You may create this method to provide custom functionality for when this happens.

Example:

<cffunction name="sessionEnd" output="false">
   <!--- Do something useful, like logging or whatever --->
</cffunction>

preRequest()

This method is called when a request comes in. It will be called after the request and action has been parsed and before validateAccess().

Example:

<cffunction name="preRequest" output="false">
   <!--- Do something useful, like put extra stuff in the RC object, or whatever --->
</cffunction>

validateAccess()

This method is called after preRequest() and before the output is built and postRequest() is called. Here the intent is to provide a change to interrupt the request workflow for something like access validation.

Example:

<cffunction name="validateAccess" output="false">
   <!--- Do something useful, validate stuff, or whatever --->
   <cfif request.rc.isSecuredPage && !session.isLoggedIn>
      <cflocation url="/?action=main.whoahThere" />
</cffunction>

postRequest()

This method is called when a request is finished processing and the output has been constructed.

Example:

<cffunction name="postRequest" output="false">
   <!--- Do something useful, like change the output, or whatever --->
</cffunction>

Next up: Services, DAOs, and Factories