Using Application.cfc

Using `Application.cfc`

To get started with the Web application framework, you first must create a special file called Application.cfc. In most respects, this file is just an ordinary ColdFusion component. (Components are discussed in depth in chapter 23, "Building Reusable Components.") Only two things make Application.cfc special:

The code in your Application.cfc file will be automatically executed just before any of your application pages.
You can't visit an Application.cfc page directly. If you attempt to visit an Application.cfc page with a browser, you will receive an error message from ColdFusion.

The Application.cfc file is sometimes referred to as the application component. It might not sound all that special so far, but you will find that the two special properties actually go a long way toward making your applications more cohesive and easier to develop.

NOTE

On Unix/Linux systems, filenames are case sensitive. The Application.cfc file must be spelled exactly as shown here, using a capital A. Even if you are doing your development with Windows systems in mind, pay attention to the case so ColdFusion will be capable of finding the file if you decide to move your application to a Linux or Unix server later.

NOTE

Previous versions of ColdFusion used another file, Application.cfm, to enable the application framework. This still works in the current version of ColdFusion. However, the use of Application.cfc is now recommended instead of Application.cfm.

Placement of `Application.cfc`

As we said, the code in your Application.cfc file is automatically executed just before each of the pages that make up your application. You might be wondering how exactly ColdFusion does this. How will it know which files make up your application and which ones don't?

The answer is quite simple: Whenever a user visits a .cfm page, ColdFusion looks to see whether a file named Application.cfc exists in the same directory as the requested page. If so, ColdFusion automatically executes it. Later on, you'll see exactly which methods of the CFC are executed.

If no Application.cfc exists in the same folder as the requested page, ColdFusion looks in that folder's parent folder. If no Application.cfc file exists there, it looks in that parent's folder, and so on, until there are no more parent folders to look in.

All this means is that you should do something you were probably already going to do anyway, namely, put all the ColdFusion templates for a particular application within a single folder, somewhere within your Web server's document root. Let's call that directory your application folder. Within the application folder, you can organize your ColdFusion templates any way you choose, using any number of subfolders, sub-subfolders, and so on. If you put an Application.cfc file in the application folder, it will be executed when any the application's templates are run. It's that simple.

For instance, consider the fictional folder structure shown in Figure 19.1. Here, the application folder is the folder named MyApp, which is sitting within the Web server's document root. Some basic Web pages are located in there, such as the company's Home page (Index.cfm), a How To Contact Us page (ContactUs.cfm), and a Company Info page (CompanyInfo.cfm). There is also a SiteHeader.cfm template there, which we intend to include at the top of each page.

Figure 19.1. The `Application.cfc` file gets included before any of your application's templates.

Because a file called Application.cfc also exists in this folder, it's automatically included every time a user visits Index.cfm or ContactUs.cfm. It's also included whenever a user visits any of the ColdFusion templates stored in the Intranet or Store folders, or any of the subfolders of the Intranet folder. No matter how deep the subfolder structure gets, the Application.cfc file in the MyApp folder will be automatically included.

NOTE

Don't worry about recreating this folder structure yourself. None of the code examples for this chapter rely on it. We're just trying to clarify where your Application.cfc template might go in a real-world application.

`Application.cfc` Structure

As you will learn in chapter 23, "Building Reusable Components," a ColdFusion Component is a collection of methods and data. You can think of it as a package of information (the data) and things you can do with the information (the methods). The Application.cfc file let's you do just thatcreate both data and methods. However, some methods are special. For example, if you create a method called onRequestStart, the method will execute before each and every page request. Table 19.1 lists these methods and how they work. Later in the chapter we will demonstrate how these work.

Table 19.1. `Application.cfc Methods`
METHOD	PURPOSE
`onApplicationStart`	Run when the application begins. This will run the first time a user executes a page inside the application. This method can be used to initialize application variables.
`onApplicationEnd`	Executed when the application ends. All applications have a timeout, defined either by the application itself or the default application timeout value specified in the ColdFusion administrator. An application times out when no one requests a file. You can use this method to record the status of application variables to a database, log to a file, or even send an email notifying you that the application has timed out.
`onRequestStart`	Executed before each page request. This could be used to specify Request scoped variables needed for pages in the application, check security credentials, or perform other checks that need to happen on every page request.
`onRequestEnd`	Executed at the end of each page request. This could be used for logging, tracking changes of request variables, or any other task that needs to happen at the end of a page request.
`onRequest`	Executed immediately after `onRequestStart`. Can be used to filter requests and modify the result.
onSessionStart	Executed when a user's session starts. Sessions are covered in Chapter 20, "Working with Sessions."
onSessionEnd	Executed when a user's session ends.
`onError`	Executed when an error occurs. This will be covered in greater depth later in the chapter.

In our examples for this chapter, we will focus mainly on the onApplicationStart, onRequestStart, and onError methods. Chapter 20 will cover onSessionStart and onSessionEnd.

A Basic `Application.cfc` Template

Take a look at Listing 19.1, a simple Application.cfc file. This example makes use of the onRequestStart method. Because the two <cfset> tags are executed before each page request, the dataSource and companyName variables can be referred to within any of the application's ColdFusion templates. For instance, the value of the dataSource variable will always be ows.

If you save this listing, be sure to save it as Application.cfc, not Application1.cfc.

Listing 19.1. `Application1.cfc`A Simple Application Template

 <!---  Filename: Application.cfc (The "Application Component")  Created by: Raymond Camden (ray@camdenfamilyc.om)  Purpose: Sets "constant" variables and includes consistent header ---> <cfcomponent output="false">   <cffunction name="onRequestStart" returnType="boolean" output="true">     <!--- Any variables set here can be used by all our pages --->     <cfset REQUEST.dataSource = "ows">     <cfset REQUEST.companyName = "Orange Whip Studios">     <!--- Display our Site Header at top of every page --->     <cfinclude template="SiteHeader.cfm">     <cfreturn true>   </cffunction> </cfcomponent>

As you will learn in Chapter 23, all components begin and end with the <cfcomponent> tag. This component only uses one method, onRequestStart. This method will execute before each request. The method begins by defining two REQUEST scope variables, dataSource and companyName.

In addition, the <cfinclude> tag in Listing 19.1 ensures that the company's standard page header will be shown at the top of each page. Listing 19.2 shows the SiteHeader.cfm template itself. Note that it can use the CompanyName variable that gets set by Application.cfc.

If this were your application, you would no longer have to put that <cfinclude> tag at the top of the Index.cfm or CompanyInfo.cfm pages (see Figure 19.1), and you wouldn't have to remember to include it in any new templates. ColdFusion would now be taking care of that for you.

Listing 19.2. `SiteHeader.cfm`Simple Header Included on Each Page

 <!---  Filename: SiteHeader.cfm  Created by: Nate Weiss (NMW)  Please Note Included in every page by Application.cfc ---> <html> <head>   <title><cfoutput>#REQUEST.companyName#</cfoutput></title> </head> <body> <font face="sans-serif" size="2"> <!--- Company Logo ---> <img src="/books/2/448/1/html/2/../images/logo_c.gif" width="101" height="101" alt=""      align="absmiddle" BORDER="0"> <cfoutput><font size="4">#REQUEST.companyName#</font></cfoutput> <br clear="left">

Using `OnRequestEnd`()

The Web application framework also reserves the special OnRequestEnd method, which is executed automatically at the end of every page request, rather than at the beginning. Listing 19.3 is a modification of listing 19.1. This time our Application.cfc includes an onRequestEnd method. It has just one line of code, a simple <cfinclude> tag to include the SiteFooter.cfm template at the bottom of every page. Listing 19.4 shows the SiteFooter.cfm file itself, which displays a copyright notice. The net effect is that the copyright notice is displayed at the bottom of every page in the application, as shown in Figure 19.2.

Figure 19.2. The application framework makes it easy to keep things consistent throughout your site.

Of course, there are other ways to get this effect. You could forget about this OnRequestEnd() business and just put the <cfinclude> tag at the bottom of every page in your application. But that might be tedious, and you might occasionally forget to do it. Or, you could just put the copyright notice in the OnRequestEnd method and get rid of the SiteFooter.cfm file altogether. That would be fine, but leaving them in separate files keeps things more manageable if the footer becomes more complicated in the future.

If you save this listing, be sure to save it as Application.cfc, not Application2.cfc.

Listing 19.3. `Application2.cfc`Including a Site Footer at the Bottom of Every Page

 <!---  Filename: Application.cfc (The "Application Component")  Created by: Raymond Camden (ray@camdenfamilyc.om)  Purpose: Sets "constant" variables and includes consistent header ---> <cfcomponent output="false">   <cffunction name="onRequestStart" returnType="boolean" output="true">     <!--- Any variables set here can be used by all our pages --->     <cfset REQUEST.dataSource = "ows">     <cfset REQUEST.companyName = "Orange Whip Studios">     <!--- Display our Site Header at top of every page --->     <cfinclude template="SiteHeader.cfm">     <cfreturn true>   </cffunction>   <cffunction name="onRequestEnd" returnType="void" output="true">        <!--- Display our Site Footer at bottom of every page --->        <cfinclude template="SiteFooter.cfm">   </cffunction> </cfcomponent>

Listing 19.4. `SiteFooter.cfm`Simple Footer That Gets Included by `OnRequestEnd()`

 <!---  Filename: SiteFooter.cfm  Created by: Nate Weiss (NMW)  Please Note Included in every page by OnRequestEnd.cfm ---> <!--- Display copyright notice at bottom of every page ---> <cfoutput>  <font size="1" FACE="sans-serif" COLOR="Silver">  <p>(c) #year(now())# #REQUEST.companyName#. All rights reserved.<br> </cfoutput> </body> </html>

NOTE

The expression #year(Now())# is a simple way to display the current year. You also could use #dateFormat(now(),"yyyy")# to get the same effect. You can find out more about the dateFormat, year, and now functions in Appendix C, "ColdFusion Function Reference."

Listing 19.5 provides preliminary code for Orange Whip Studio's home page. As you can see, it's just a simple message that welcomes the user to the site. Of course, in practice, this is where you would provide links to all the interesting parts of the application. The point of this template is to demonstrate that the site header and footer are now going to be automatically included at the top and bottom of all ordinary ColdFusion templates in this folder (or its subfolders), as shown in Figure 19.2. Note that this template is also able to use the REQUEST.companyName variable that was set in the Application.cfc file.

If you save this file, be sure to save it as index.cfm, not index1.cfm.

Listing 19.5. `Index1.cfm`A Basic Home Page for Orange Whip Studios

 <!---  Filename: Index.cfm  Created by: Nate Weiss (NMW)  Please Note Header and Footer are automatically provided ---> <cfoutput>  <blockquote>  <p>Hello, and welcome to the home of  #REQUEST.companyName# on the web! We certainly  hope you enjoy your visit. We take pride in  producing movies that are almost as good  as the ones they are copied from. We've  been doing it for years. On this site, you'll  be able to find out about all our classic films  from the golden age of Orange Whip Studios,  as well as our latest and greatest new releases.  Have fun!<br>  </blockquote> </cfoutput>