Inside Coldfusion MX
| ColdFusion provides its developers with a tool that helps them tie together a group of templates into one or more applications. This tool is called the Web Application Framework. The Web Application Framework is designed with four basic concepts in mind:
Applicationwide Settings
The Web Application Framework enables the use of applicationwide settings by enabling developers to create two special templates within the ColdFusion application. These templates make it possible for chunks of code to be "included" in each template that is requested. These settings might range from the establishment of variable values on each template to the inclusion of look and feel elements. It also enables them to include templates that contain user-defined function libraries. The two special templates enable developers to execute common code before and after each page request. These templates are as follows:
It is these two templates that maintain and control the Web Application Framework. Application.cfm
The Application.cfm template is a special template within ColdFusion applications. The very name of the template has special significance in a ColdFusion application and should always start with a capital "A." This is especially important on Linux or UNIX installations. The Application.cfm template should be placed in the root directory of your application. It is a best practice that you always capitalize the "A" in Application.cfm because it enables your code to be used in multiple environments without modification. When any ColdFusion template is requested, ColdFusion checks the directory where that template is located for an Application.cfm template. If it finds one, it executes the Application.cfm prior to the execution of the requested template. Essentially, ColdFusion automatically processes a CFINCLUDE of the Application.cfm into the top of the requested template. If ColdFusion does not find an Application.cfm file in that directory, it begins to look up the directory tree, all the way to the root directory, until it finds an Application.cfm. If it does not find one, no error occurs. If it does find one, it includes it in the requested template as previously described. The significance of this is that you can use one Application.cfm file throughout your application to set variables that might be needed in every template. One of the most common variables used in a ColdFusion application might be the datasource name. It also means, of course, that you can have multiple Application.cfm templates throughout your directory structure. Templates within any given directory execute only the Application.cfm file that resides in the same directory. A very common use of this type of structure is application login. For example, you want users of your application to log in so that you can keep some record of who logs on when. Thus, you create a bit of conditional logic in your root directory Application.cfm: <cflock scope="session" type="readonly" timeout="10"> <cfif IsDefined("session.LoggedIn")> <cfset request.LoggedIn=session.LoggedIn> </cfif> </cflock> <cfif NOT IsDefined("request.LoggedIn")> <cflocation url="/login/index.cfm"> </cfif> Thus, you create a login directory and a login page. Within that login directory, you create an Application.cfm template so that the code that we wrote in our root-level Application.cfm (shown previously) does not execute. If this code does execute, you experience an endless loop because the CFIF statement runs and then executes the CFLOCATION tag. ColdFusion processes from the top of the template, down. Therefore, because the Application.cfm template executes first, any variables that you set or code execute prior to the code that resides in the requested template. One of the original intentions for creating the Application.cfm template and its special characteristics was to enable developers to create sites and applications with a common header. However, in our discussion of Application.cfm, we've seen how you could have an Application.cfm template in every directory throughout your directory structure. Using the Application.cfm as a "header" template totally defeats the purpose of writing reusable code. It would mean that you'd have to maintain code in each Application.cfm template throughout your application. Use your Application.cfm templates to execute the following types of code:
The following types of code should not be present in your Application.cfm templates:
OnRequestEnd.cfm
The OnRequestEnd.cfm template serves a purpose similar to that of Application.cfm. However, when it is present, it executes at the end of each template request. The OnRequestEnd.cfm template should always have the "O", "R", and "E" capitalized. This is especially important on Linux or UNIX installations. Again, making sure that your OnRequestEnd.cfm is properly capitalized helps to ensure that you can deploy your application code in various environments. The OnRequestEnd.cfm template must be located in the same directory as a corresponding Application.cfm and cannot execute without one. If an error occurs within a template or if a CFABORT, CFEXIT, or CFLOCATION tag is executed, the OnRequestEnd.cfm template does not execute. Custom Error Handling
The Web Application Framework lets developers use the CFERROR tag within their applications to create custom HTML error messages when an error occurs within the application. The effect that this has on the application is that it integrates the custom look and feel of the application into the error messages themselves rather than throwing up an ugly (and sometimes cryptic) default error screen. Custom error handling also enables you to control the amount of information that the user sees about the error. This is not the time or place for a complete discussion of custom error handling and the CFERROR tag. Refer to Chapter 9, "Error Handling," for more detailed information. Application Security
The Web Application Framework enables developers to integrate the security of their application with that of their web server. ColdFusion Server also offers security features to control access to applications or specific pages within those applications, to a specific datasource, or to specific users. These features are accessible using the CFLOGIN, CFLOGINUSER, and CFLOGOUT tags. Refer to Chapter 17, "Common Application Development Requirements," for more detailed information. Enabling Variable Scopes
The Web Application Framework provides ColdFusion developers with a means of enabling variable scopes that are accessible throughout the application. These scopes are the application, session, and client scopes. Before you use any of these scopes, they must be enabled by applying the CFAPPLICATION tag, which is most commonly called in the Application.cfm template. |