| The Application.cfm file is the granddaddy of all ColdFusion templates. As previously mentioned, this template is a special template, and ColdFusion will try to include this template at the top of each and every ColdFusion page in our web site. NOTE The Application.cfm and OnRequestEnd.cfm templates are special reserved templates. It is not possible to request them directly via a browser. For example, if you were to type www.mywebapp.com/Application.cfm into a browser, you would receive an error even though the page does actually exist.
When any page with a .cfm extension is requested from the server, ColdFusion will try to locate the Application.cfm template and add it to the top of the requested page. The Application.cfm file acts in the same fashion as a standard <CFINCLUDE> file, and for all intents and purposes, it is as if the code contained in the Application.cfm file were copied and pasted into the top of the requested page. This makes Application.cfm a great place to store variables that we would like to use across many templates, such as the name of a data source. When a .cfm template is requested, ColdFusion Server looks for the Application.cfm file in the same directory as the file being requested (see Figure 8.2). When the AboutUs.cfm file is requested, ColdFusion Server will look in the same directoryin this case, the MyCompanyApp directoryfor the Application.cfm template. In this case, it finds the file and moves all the code in Application.cfm to the top of the AboutUs.cfm file. Figure 8.2. A single Application.cfm file.  If ColdFusion Server does not find an Application.cfm file in the same folder as the page being requested, it searches that folder's parent folder for an Application.cfm template. If it is not found in that folder, the search will continue in the parent's parent folder and so on up the chain to the root directory of the web site. In Figure 8.3, if the Sales\Report.cfm file is requested, ColdFusion will first look in the Sales directory for an Application.cfm file. Because it does not find one there, it continues up the chain to the root folder, finds an Application.cfm file there, and adds it to the top of the Report.cfm file for processing. In the case of the \Technology\Admin\Search.cfm page, ColdFusion would first look in the Admin subdirectory, then the Technology directory, and would finally find an Application.cfm file for processing in the root directory. If no Application.cfm file is found, the requested page processes as normal. Figure 8.3. A multiple-directory search.  When ColdFusion Server finds an Application.cfm file, it stops searching any other directories. Because ColdFusion Server searches in this fashion, we can use multiple Application.cfm files to compartmentalize certain sections of our application that might require slightly different application settings. For example, in Figure 8.4, if the Admin subfolder of our Technology directory requires some special settings (for example, added security), we can add an Application.cfm with the added settings to that directory. When the Technology\Admin\Search.cfm page is requested this time, ColdFusion searches the Admin subdirectory, finds an Application.cfm file there, adds it to the top of the Search.cfm page, and stops looking any further. Figure 8.4. Multiple Application.cfm files.  In the preceding scenario, after the Application.cfm file is found in the Admin subdirectory, ColdFusion will not look any further. If the files in the Admin directory need to share any of the settings or variables contained in the root-level Application.cfm file, those settings and values will have to be duplicated in the Admin-level Appliction.cfm file. If your Admin directory just requires everything in the root-level Application.cfm file plus additional settings (such as security), a clever thing to do would be to use <CFINCLUDE> in the Admin-level Application.cfm file to include the root-level Application.cfm file and then just add the additional Admin-level setting after that. Although you can use the Application.cfm file for presentation-type information like banners and site headers, it is not recommended. Macromedia best practices suggest that you only use the Application.cfm file for variables and application logic. When ColdFusion goes hunting for the Application.cfm file, it is very specifically looking for Application.cfm with an uppercase A. This is not such a big deal on Windows-based systems, but Linux and UNIX file systems are case sensitive, and application.cfm and Application.cfm are not the same thing. Even if you are working on a Windows-based system, you should make sure you use an uppercase A. Many web development shops do their development on Windows machines and deploy their sites onto Linux/UNIX-based machines for production. Additionally, you might decide in the future to move from a Windows system to a Linux/UNIX system, and if you have been lazy with the case of your filenames, it will cause you all kinds of grief. Enough said. Application Settings We have seen how the inclusion functionality of the Application.cfm template works, but how do we actually use it to create an "application?" Well, a good place to start is with the <CFAPPLICTION> tag. We can begin by giving our application a name. <CFAPPLICATION NAME="MyCompanyApp"> If we add this line of code to our Application.cfm file, and each page request includes that Application.cfm file, every page in our web site will know that it is part of an application called MyCompanyApp. That might not seem like much, but many web servers host more than one application, and this serves to separate our application from other applications that might be running on the same server (provided everyone has chosen different names). In addition, as we will see later in this step, the concept of being part of an application becomes very important when we start using shared memory on the server. The Application.cfm template can also contain other types of ColdFusion variables. This template is usually used to set the values of variables that will appear repeatedly throughout the site. See the sidebar "Making Your Application Portable" later in this step for further information. Using the <CFAPPLICATION> Tag To make our web site into an "application," we begin by adding the <CFAPPLICATION> tag to our Application.cfm template, as shown in the preceding section. This tag, however, has several attributes other than NAME that we need to be aware of. Table 8.1 lists all the attributes of the <CFAPPLICATION> tag. Table 8.1. <CFAPPLICATION> Attributes| Element Name | Description |
|---|
| NAME | This attribute sets the name of the application. Names can be up to 64 characters. This attribute is required when using Application and Session scope variables. It is optional when using Client scope variables. | | CLIENTMANAGEMENT | Yes or No (default). Must be set to Yes to enable the use of Client scope variables. | | CLIENTSTORAGE | Defines the type of storage used for Client scope variables. The three options are: Registry: Stores Client scope information in the Registry of the server. Cookie: Stores Client info in cookies on the client's machine. Datasource: Stores Client info in a specified data source. | | SETCLIENTCOOKIES | Yes (default) or No. Enables the use of client cookies to store CFID and CFToken information. | | SESSIONMANAGEMENT | Yes or No (default). Enables the use of Session scope variables. | | SESSIONTIMEOUT | Sets the lifespan of Session scope variables. | | APPLICATIONTIMEOUT | Sets the lifespan of Application scope variables. | | SETDOMAINCOOKIES | Yes or No (default). Typically used in clustered environments to allow cookies to be read by multiple servers. |
The use of Session, Application, and Client scope variables will be discussed in detail in the section "State Management" later in this step. In the meantime, we need to understand just a little about Session scope variables. A session begins whenever a new user arrives at our site and ends when that user logs out, leaves the site, or remains inactive for a certain amount of time. We can use Session scope variables to track certain things about that user during the time he is visiting our site. For example, let's say a user visits our site and logs in. We can store that visitor's username and the fact that he is logged in by using Session scope variables, such as Session.UserName and Session.UserLogginIn. These variable values are stored in the server's memory and will eventually "die out." The amount of time these variables are "alive" depends on either the settings in the <CFAPPLICATION> tag or the settings in ColdFusion Administrator. For example, we don't want to store that visitor's username forever. Suppose he just leaves the site and goes somewhere else. We don't want to take up server memory storing that value any longer than is necessary. So, when using Session scope (and Application scope) variables, we give those variables a certain lifespan. For example, if we want Session scope variables to "live" for 20 minutes, our server will keep that visitor's username stored in its memory, and when that visitor has been idle for 20 minutes (or has left the site), the server will simply delete that variable from its memory. If the visitor continues to browse our site and stay active, that 20-minute period will be continually reset with each page request. The amount of time that Session and Application variables will "live" can be set in two places: the <CFAPPLICATION> tag and ColdFusion Administrator. Using the <CFAPPLICATION> tag, you must set the SESSIONMANAGEMENT attribute to YES to enable the use of session variables, and then you can then set the lifespan for Session variables using the SESSIONTIMEOUT attribute and the CreateTimeSpan() function. See the following sidebar "Creating Time Spans" for more information on the CreateTimeSpan() function. The following code illustrates using the <CFAPPLICATION> tag to enable the use of Session scope variables. <CFAPPLICATION NAME="MyCompanyApp" SESSIONMANAGEMENT="Yes" SESSIONTIMEOUT="#CreateTimeSpan(0,0,15,0)#"> The preceding code creates an application called MyCompanyApp, enables the use of Session scope variables, and gives them a lifespan of 15 minutes. Creating Time Spans Certain variables, such as Session and Application scope variables, require a certain time to live, or time span. We can create a time span in ColdFusion using the CreateTimeSpan() function. The CreateTimeSpan() function takes four parameters, all separated by commas: CreateTimeSpan(days, hours, minutes, seconds) For example, the following function would create a time span that lasted for 2 days, 3 hours, 4 minutes, and 5 seconds. CreateTimeSpan(2, 3, 4, 5) |
ColdFusion Administrator Settings The attributes of the <CFAPPLICATION> tag allow you to enable Session and Application scope settings for an individual application. To use Application and Session scope variables on the server as a whole, they must also be enabled in ColdFusion Administrator. Figure 8.5 shows the Session and Application settings for the server on the Memory Variables page of ColdFusion Administrator. Figure 8.5. The ColdFusion Administrator Memory Variables settings.  As you can see in Figure 8.5, Application and Session variables have been enabled by checking the appropriate boxes. This is the default setting. This page also contains boxes for setting maximum possible durations and default durations for these variables. If you use the <CFAPPLICATION> tag and set the SESSIONMANAGEMENT to YES but do not specify a SESSIONTIMEOUT value, your Session variables will use the default value set in ColdFusion Server. If you do use the SESSIONTIMEOUT attribute of the <CFAPPLICATION> tag, you can set the timeout for an individual application to any value up the Maximum Timeout value set in ColdFusion Administrator. Using Figure 8.5 as an example, if we used <CFAPPLICATION> with a SESSIONTIMEOUT value of 15 minutes, the Session scope variables for that particular application would time out after 15 minutes. If we used <CFAPPLICATION> with a SESSIONTIMEOUT value of 2 hours, however, our Session scope variables would only last for 1 hour, the Maximum Timeout set in ColdFusion Administrator. |
