What Is the Application Framework?


What Is the Application Framework?

ColdFusion provides a framework for combining application pages or templates into a single coherent application. This application framework provides three basic sets of functionality:

  • Application-wide variables and code

  • Client and application state management

  • Error-handling services

The topmost parent in the application directory tree is known as the application root. This directory is usually located within a branch of the Web document root. The subdirectories below this are typically used to separate code templates and other media based on their functionality. For example, included files such as headers might be found in an ../includes directory, and images in a separate ../images directory, depending on your development methodology.

NOTE

The Web document root is the directory that has been mapped to the base Web site URL, such as www.forta.com. The location of this directory is configured in the Web server administration interface and can be different for each Web site hosted on your server. For example, the default Web document root for ColdFusion's integrated HTTP server (on a Windows machine) is c:\cfusionmx7\wwwroot\.


Global variables and application-wide functionality can be implemented within an application by the use of special files named Application.cfc or Application.cfm (the latter may also have an accompanying OnRequestEnd.cfm file).

NOTE

Application.cfm has been supported since early versions of ColdFusion. Application.cfc was first introduced in ColdFusion MX 7. Both are, and will continue to be, supported, but for new development you are generally advised to use Application.cfc which provides for far greater functionality.


Client state management is covered in detail in Chapter 10, "APPLICATION and SERVER Variables and SERVER Variables," and Chapter 11, "Session State Management." Error handling is covered in Chapter 26, "Error Handling."


Whenever a page is to be executed, the ColdFusion checks the page's local directory for either of the Application files. Keep the following in mind:

  • If an Application file doesn't exist, the server looks in the parent directory, and then the parent's parent, and so on up the directory tree until one is found or until the drive root directory is reached.

  • If more than one Application file exists in the directory tree, ColdFusion uses only the first one it finds.

  • If there is no Application file, the template page executes as per normal.

  • If both an Application.cfc and an Application.cfm exists, Application.cfc will be used.

CAUTION

Many developers incorrectly assume that the ColdFusion application server searches only to the document root of the Web server for an Application file. In fact, the server searches all the way up the directory tree to the hard drive's root directory.


Typical application uses of the Application files include:

  • Defining the application name.

  • Defining default variables and global constants such as data source names, and absolute file paths for image and file libraries.

  • Custom error handling for general exceptions.

  • Default style settings such as fonts or colors using the local or request scope (perhaps saved into structures for simplified organization and management).

  • Application-wide security code (such as requiring logins and redirecting to a login page if needed).

It is impossible to prevent Application files from being executed, if they are present ColdFusion will find them and process them.

On some operating systems (such as Solaris, Linux, and HP-UX), filenames are case sensitive. Therefore, Application.cfc, Application.cfm and OnRequestEnd.cfm must be named with exactly the right casing; capital A for Application and capital O, R, and E for OnRequestEnd.cfm. Although Windows NT, Windows 2000, and Windows XP have case-insensitive file systems, it is good practice for portability of the code to stick to the correct casing when you create these files.

NOTE

As a security measure, Application files cannot be called directly from a URL on the Web browser. They can be executed only in the context of another page in the application.


CAUTION

Presentation code such as HTML, JavaScript, and other client-side technologies should not be placed in the Application files. Application files are designed specifically as a globally included template for application-wide logic, and are not appropriate for any aspect of your application's presentation layer.


Application.cfc

As a ColdFusion Component, Application.cfc has a very specific format. The contents of the file must be enclosed within <cfcomponent> and </cfcomponent> tags.

Application.cfc is a special ColdFusion Component. ColdFusion Components in general is discussed in Chapter 31, "ColdFusion Components".


Application settings are defined in the constructor portion of the component (within the component but not within any specific method),. For example, to enable session state management the following Application.cfc could be used:

 <cfcomponent>   <cfset THIS.name="MyApp"> <cfset THIS.sessionManagement="true"> <cfset THIS.sessionTimeout=CreateTimeSpan(0,0,30,0)> </cfcomponent> 

In this example an application name is specified in property THIS.name, THIS.sessionManagement is used to enable session state management, and the session timeout is set to 30 minutes. Table 6.1 lists the supported application properties (settings).

Table 6.1. Application.cfc Properties

PROPERTY

DESCRIPTION

applicationTimeout

Application timeout interval (specified as a time span). The default is the interval specified in the ColdFusion Administrator.

clientManagement

Whether or not to enable CLIENT variable support. Defaults to FALSE.

clientStorage

Where to store CLIENT variables. Default value is COOKIE.

loginStorage

Where to store login information. Default value is COOKIE.

name

The application name. This must always be provided.

scriptProtect

Whether or not to enable protection against cross-site scripting attacks. Defaults to whatever is specified in the ColdFusion Administrator.

sessionManagement

Whether or not to enable SESSION variable support. Defaults to FALSE.

sessionTimeout

Session timeout interval (specified as a time span). The default is the interval specified in the ColdFusion Administrator.

setClientCookies

Whether or not to save client identification tokens as cookies. Default is TRUE.

setDomainCookies

Whether or not to set domain cookies (usually only needed if an application is running on a cluster of servers). Default is FALSE.


Application.cfc can also contain code to be executed when specific events occur (for example, when an application starts up, or before and after every page request, or when an error occurs). Table 6.2 lists the support methods.

Table 6.2. Application.cfc Methods

METHOD

DESCRIPTION

OnApplicationEnd

Executed on server shut-down or on application timeout.

OnApplicationStart

Executed the first time code within an application is executed (after server start-up, or after application timeout).

OnError

Executed whenever an error not explicitly trapped with <cftry>/<cfcatch> code occurs.

OnRequest

Executed in lieu of the page requested.

OnRequestEnd

Executed after each and every page request.

OnRequestStart

Executed before each and every page request.

OnSessionEnd

Executed whenever a session expires.

OnSessionStart

Executed whenever a new session is created.


The following example defines an application, sets two variables upon application startup, and initializes a shopping cart when a new session is created.

 <cfcomponent>   <!--- Set up app --->   <cfset THIS.name="MyApp">   <cfset THIS.sessionManagement="true">   <cfset THIS.sessionTimeout=CreateTimeSpan(0,0,30,0)>   <!--- When application starts --->   <cffunction name="onApplicationStart">     <cfset APPLICATION.FileLibrary="d:\lib">     <cfset APPLICATION.DataSource="ows">   </cffunction>   <!--- When new session starts --->   <cffunction name="onSessionStart">     <cfset SESSION.cart=StructNew()>     <cfset SESSION.cart.items=ArrayNew(1)>   </cffunction> </cfcomponent> 

Order Of Processing

When multiple methods are defined within Application.cfc, there are evaluated in the following order:

  1. onApplicationStart()

  2. onSessionStart()

  3. onRequestStart()

  4. onRequest()

  5. onRequestEnd()

The remaining three event methods are called when specific events occur, when an application or session times out or the server is shutdown, or when an error occurs.

TIP

Generally, use onApplicationStart() to set APPLICATION data, onSessionStart() to set SESSION data, and onRequestStart() to set REQUEST data.


Using onRequest()

onRequest() is a little different from the other Application.cfc methods in that it is not executed when as event occurs, rather it is executed in lieu of an event. If present, onRequest() will be executed instead of the page that was requested, and the requested pages name is passed to onRequest() as an attribute. This allows developers to trap page requests if needed.

Possible uses for onRequest() include:

  • Temporarily blocking application access during maintenance.

  • Restricting access based on IP address or subnet.

  • Grabbing generated output and performing processing on it, including stripping whitespace or compressing data.

It is important to note that if onRequest() is used then ColdFusion will not automatically execute the requested page. If that page is to be executed that it must be explicitly included using <cfinclude>.

Included files are covered in detail in Chapter 5, "Redirects and Reuse."


NOTE

onRequest() cannot be used if Web Services or Flash Remoting are needed.


Application.cfm

The Application.cfm file behaves in the same way as a standard <cfinclude> in that it is run as if it were cut and pasted into the top of the executing template. Local variables defined in the Application.cfm file are unprotected and are available to the rest of the code template. An Application.cfm file placed in the application root is implicitly included at the top of every page in the application. Therefore, it is an ideal place to assign global variables such as file paths and data source names, and to implement application-wide functionality such as security authentication.

The following example is the Application.cfm equivalent of the previously seen Application.cfc example:

 <!--- Set up app ---> <cfapplication name="MyApp"                sessionmanagement="Yes"                sessionTimeout="#CreateTimeSpan(0,0,30,0)#"> <!--- When application starts ---> <cfif NOT IsDefined("APPLICATION.settings")   <cflock type="exclusive" scope="application">     <cfset APPLICATION.FileLibrary="d:\lib">     <cfset APPLICATION.DataSource="ows">     <cfset APPLICATION.settings="true">   </cflock> </cfif> <!--- When new session starts ---> <cfif NOT IsDefined("SESSION.cart")   <cflock type="exclusive" scope="session">     <cfset SESSION.cart=StructNew()>     <cfset SESSION.cart.items=ArrayNew(1)>   </cflock> </cfif> 

Local or request-scope variables that are set in Application.cfm are available in all pages that include the file. Such variables do not need to be locked. However, Application.cfm is often used for the setting of SERVER, APPLICATION, and SESSION variables, and careful consideration must be given to the appropriate locking of these shared variable types.

Client state management is covered in detail in Chapter 10, "APPLICATION and SERVER Variables and SERVER Variables," and Chapter 11, "Session State Management." The importance of locking in ColdFusion is discussed in Chapter 12, "Locking."


In the same way that Application.cfm is executed at the beginning of every page in the application, you can create a file called OnRequestEnd.cfm that is executed at the end of every page. However, unlike Application.cfm, OnRequestEnd.cfm must be located in the same directory as the calling page's Application.cfm. It will not be executed if it is placed in another directory. If you choose to use OnRequestEnd.cfm files in your application, they are in effect linked to the Application.cfm file residing in the same directory.

OnRequestEnd.cfm can be useful in a multitude of ways for more advanced Cold Fusion implementations: for example, to control debugging directives or to manage the logging of code that responds to specific page settings.

 <!--- OnRequestEnd.cfm example ---> <!--- suppress debugging output ---> <cfsetting showdebugoutput="No"> <!--- activate logging module ---> <cfif request.logpage>  <cf_log_module> </CFIF> 

Multiple Application Files

Although you can use a single Application file to govern an entire application, it is often useful to break up an application into individual sections or modules. In these instances, you might need to define a different Application for each section of code in order to provide different global variables and functions.

If you place an Application file in the application root of your Web application, the file will be automatically included in all files throughout the branches of the subdirectory tree. However, by placing an Application file in a subdirectory below the application root, it is possible to define different parameters and functionality for all the pages in that specific branch of the directory structure. Remember that ColdFusion will execute only one Application file per page and will look in the current directory first.

  • If using Application.cfc, the <cfcomponent> extends attribute can be used to extend another Application.cfc. The methods and settings in the Applciation.cfc being extended will be executed unless overwritten in the new Application.cfc.

  • If using Application.cfm, <cfinclude> can be used to include another Applciation.cfm. Care must be taken to use the same application name in <cfapplication> or APPLCIATION and SESSION data will not be shared.



Macromedia ColdFusion MX 7 Certified Developer Study Guide
Macromedia ColdFusion MX 7 Certified Developer Study Guide
ISBN: 0321330110
EAN: 2147483647
Year: 2004
Pages: 389
Authors: Ben Forta

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net