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:
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:
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:
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.cfcAs 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).
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.
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 ProcessingWhen multiple methods are defined within Application.cfc, there are evaluated in the following order:
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:
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.cfmThe 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 FilesAlthough 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.
|