<!---
Application.cfc reference

materials for this page were obtained from the following sources:
	http://www.bennadel.com/blog/726-ColdFusion-Application-cfc-Tutorial-And-Application-cfc-Reference.htm
	http://ray.camdenfamily.com/downloads/app.pdf
--->

<cfcomponent displayname="Application" output="false" hint="Handle the application.">

	<!--- set up the application --->
	<cfset this.name 		= "YourApplicationNameHere" />
	<cfset this.applicationTimeout	= createTimeSpan(0,2,0,0) />		<!--- defaults to cf administrator value --->
	<cfset this.clientManagement 	= true|false />				<!--- defaults to cf administrator value --->
	<cfset this.clientStorage 	= cookie|registry|datasourceName />	<!--- defaults to cf administrator value --->
	<cfset this.loginStorage 	= cookie|session />
	<cfset this.sessionManagement 	= true|false />
	<cfset this.sessionTimeout 	= createTimeSpan(0,0,20,0) />		<!--- defaults to cf administrator value --->
	<cfset this.setClientCookies 	= true|false />
	<cfset this.setDomainCookies 	= true|false />
	<cfset this.scriptProtect 	= none|all|list />			<!--- defaults to cf administrator value --->

	<!--- define the page request properties --->
	<cfsetting requesttimeout="20" showdebugoutput="false" enablecfoutputonly="false" />

	<cffunction name="onApplicationStart" access="public" returntype="boolean" output="false" hint="fires when the application is first created.">

		
		<!---
		This is the perfect place to define application-scoped variables (ex. application.DSN for data source structures).
		If this method is invoked manually, be sure to call structClear() on the application scope before you re-initialize the data values.
		This will help to ensure a clean refresh.

		The return boolean signals as to whether or not the application loaded successfully.
		Returning false will halt the processing of the rest of the events of the current page request.
		--->
		
		<cfreturn true />
	</cffunction>

	<cffunction name="onSessionStart" access="public" returntype="void" output="false" hint="fires when the session is first created.">

		
		<!---
		This is the perfect place to define session-scoped variables (ex. session.cart for eCommerce cart data).
		If this method is invoked manually, be sure to call structClear() on the session scope before you re-initialized the data values.
		HOWEVER! before clearing the scope, get a copy of the CFID/CFTOKEN values so that you can store them back into the session during re-initialization.
		ColdFusion will not automatically re-create these values as calling this event method is not actually restarting the session.
		--->
		
		<cfreturn />
	</cffunction>

	<cffunction name="onRequestStart" access="public" returntype="boolean" output="false" hint="fires at first part of page processing.">

		<cfargument name="TargetPage" type="string" required="true" />
		
		<!---
		This the perfect place to define request-specific and other request-scoped variables (ex. request.attributes for the union of the form/URL scopes).
		This is also a good place to do universal form value scrubbing (such as removing smart quotes and trimming form field values).

		If your application or sessions can handle manual re-initialization, this is a good place to check for those URL flags (ex. structKeyExists(URL, 'resetApp'))
		and then manually invoke the OnApplicationStart() or OnSessionStart() application events.

		If you are using the OnRequest() method and you expect this application to be used for flash remoting or CFC-based web service calls,
		this is the ideal time at which to check for the request type (standard page request vs. web service) and if need be,
		delete the OnRequest() method from the Application.cfc (ex. structDelete(this, "OnRequest")).

		If the return value is false, the page processing will be halted.
		--->
		
		<cfreturn true />
	</cffunction>

	<cffunction name="onRequest" access="public" returntype="void" output="true" hint="fires after pre page processing is complete.">

		<cfargument name="TargetPage" type="string" required="true" />
		
		<!---
		If you include this event then you must include the requested page via a cfinclude tag.
		The relative path of the template is passed as the only argument to this function.
		If you include the page in this manner, the processed template becomes what is essentially a "Mix-In" of the Application.cfc,
		meaning that it is actually part of the Application.cfc code.
		If you do this, the processed page will have access to the this and variables scopes of the Application.cfc.

		If the request page is included in this manner, it also means that the requested page will have access to all methods defined in the Application.cfc.

		This is the perfect place to handle login management. Since this method determines which template gets executed,
		this is where you can check login status and conditionally include the login template rather than the requested template.
		--->
		
	 	<!--- include the requested page. --->
		<cfinclude template="#arguments.TargetPage#" />

		<cfreturn />
	</cffunction>

	<cffunction name="onRequestEnd" access="public" returntype="void" output="true" hint="fires after the page processing is complete.">

		
		<!---
		This is the perfect place to handle page logging.
		By doing it here (especially if the first command is a <cfflush> tag), the user experience will not be affected by any processing overhead of this event method.
		--->
		
		<cfreturn />
	</cffunction>

	<cffunction name="onSessionEnd" access="public" returntype="void" output="false" hint="fires when the session is terminated.">

		<cfargument name="sessionScope" type="struct" required="true" />
	 	<cfargument name="applicationScope" type="struct" required="false" default="#structNew()#" />
		
		<!---
		This is the perfect place to clean up sessions that have timed out (ex. deleting uncommitted shopping cart information).
		This method does not have inherent access to the application scope or the session scope (as the OnRequestEnd() method has access to the request scope).
		In order to access those scopes, you must use the passed in arguments.
		--->
		
		<cfreturn />
	</cffunction>

	<cffunction name="onApplicationEnd" access="public" returntype="void" output="false" hint="fires when the application is terminated.">

		<cfargument name="applicationScope" type="struct" required="false" default="#structNew()#" />
		
		<!---
		This is the perfect place to log information about the application.
		This method does not have inherent access to the application scope. In order to access that scope, you must used the passed in argument.
		--->
		
		<cfreturn />
	</cffunction>

	<cffunction name="onError" access="public" returntype="void" output="true" hint="fires when an exception occures that is not caught by a try/catch.">

		<cfargument name="Exception" type="any" required="true" />
		<cfargument name="EventName" type="string" required="false" default="" />
		
		<!---
		This event gets called when an event fires and allows you to handle that error and include an error handling template if you so desire.
		However, this event cannot display anything to the user if the error occurs during the OnApplicationEnd() or OnSessionEnd() events
		as those are not request-related (unless called explicitly during a request).

		One thing to be aware of (as of MX7) is that the <cflocation> tag throws a runtime Abort exception
		(which makes sense if you understand that the <cflocation> tag halts the page and flushes header information to the browser).
		As a work around to this, you can check the passed in Exception type and if its a Abort exception do not process the error:
		<cfif NOT compareNoCase(arguments.Exception.RootCause.Type, "coldfusion.runtime.AbortException")>
			<!--- do not process this error --->
			<cfreturn />
		</cfif>
		--->
		
		<cfreturn />
	</cffunction>

</cfcomponent>