The ColdFusion Application Framework is documented in chapter 13 " Designing and Optimizing a ColdFusion Application" of the "Developing ColdFusion MX Applications" manual, however, it does not provide information about how you can use ColdFusion's object oriented architecture to extend the Framework. This TechNote uses an example to show how ColdFusion CFC's can be leveraged to extend the existing ColdFusion MX 7 Application Framework.
It is recommended that you read Chapter 13 of the "Developing ColdFusion MX Applications" manual, " Designing and Optimizing a ColdFusion Application", especially the Application Framework section, before proceeding.
We will use the BandwidthAssociates application and file structure, as documented in the above mentioned manual. Specifically, under the ColdFusion MX 7 document root, we have a BandwidthAssociates directory and aSales subdirectory under that. Both directories have their own Application.cfc and Index.cfm. These four files can be downloaded here (3 K). Take a look at their CFML source before continuing.
Let's briefly review how the ColdFusion MX 7 Application Framework functions. When a page is requested, ColdFusion searches the directory where the page resides for a file with the nameApplication.cfc. If it finds one, it executes it and stops there. If it doesn't find one, it searches up the directory tree until it does. For a more detailed description of what ColdFusion goes through, look at the section, How ColdFusion MX finds and processes application definition pages, in the ColdFusion MX 7 documentation.
<cfset this.name="BandwidthAssociates"><cfset this.sessionManagement="true"><cfset this.clientManagement="true"><cfset this.setClientCookies="true"><cfset this.applicationTimeout=CreateTimeSpan(0,0,0,10)><cfset this.sessionTimeout=CreateTimeSpan(0,0,0,10)>
In our WebApplication, we first requestBandwidthAssociates/Index.cfm. ColdFusion then finds the Application.cfc in the same directory and uses it, then processes Index.cfm. Look at theBandwidthAssociates/Application.cfc file and find the comment set Application settings. Here you will see that the application name is BandwidthAssociates, sessionManagement is true, clientManagement is alsotrue, setClientCookies is true, and sessionTimeout and applicationTimeout are 10 seconds each.
Now, back to requesting Index.cfm, ColdFusion finds the Application.cfc in the same directory and the following things happen:
- In the browser, we see the table that dumps the contents of the application settings before any of them are set
- Again, we see the table that dumps the content of the application settings, but this time it's after they've been set by Application.cfc
- The onApplicationStart event fires because this is the first time the application has been accessed
- The onSessionStart event fires because a new session is being created/started
- The onRequestStart event fires because a new request is being created/started
- The onRequest event fires because we're making a request
- The Index.cfm template is displayed showing the current time
The four events mentioned above fired because ColdFusion called them. They are displayed in the browser because they are implemented in BandwidthAssociates/Application.cfc and the CFML code writes the strings to the browser. What aboutonRequestEnd, why don't we see that event firing since the request obviously ended? Actually, the event did fire, we just didn't have any code implemented in Application.cfc to show us that it fired. Similarly, why didn't we see theonSessionEnd or onApplicationEnd events? The onApplicationEnd and onSessionEnd events do not execute in the context of a page request, so they cannot access request variables or display information to the user. In our case, both events fire 10 seconds after the last request in the session (as per the sessionTimeout and applicationTimeout we set in Application.cfc).
If you go back and requestBandwidthAssociates/Index.cfm again and refresh it before the session and application timeout settings of 10 seconds, you'll see different results.
- You'll see the two tables that dump the contents of the application settings.
- Now though, you only see the onRequestStart andonRequest events displayed. This is because theapplicationTimeout and sessionTimeout settings were not exceeded, therefore the events didn't fire. You're still within the same application and session.
- The Index.cfm template is displayed with the current time.
- The onRequestEnd event isn't displayed because it's not implemented in the Application.cfc. The event fired but there was no code to show it to us.
Now, click the BandwidthAssociates Sales link at the bottom of the page. This requests the templateBandwidthAssociates/Sales/Index.cfm in theSales subdirectory. ColdFusion does the same directory tree search for Application.cfc and it finds one in the same directory (BandwidthAssociates/Sales) and uses it. But there is one very important difference between thisApplication.cfc and the one in the directory above. Itextends the one from above (see the attached source files).
Because it extends the one from above, we see the two application settings tables as we did before (before and after setting the variables) but then we see a third table. This one is displayed to show that the application name has been reset. This is because in BandwidthAssociates/Sales/Application.cfc, we override the this.name variable and reset it toBandwidthassociates_sales. All the other settings were not touched, so they remain as they were.
Now, back to requestingBandwidthAssociates/Sales/Index.cfm. ColdFusion finds the Application.cfc in the same directory and the following things happen:
- In the browser, we see the table that dumps the contents of the application settings before any of them are set.
- Again, we see the table that dumps the content of the application settings, but this time it's after they've been set byBandwidthAssociates/Application.cfc.
- The onApplicationStart event fires because the application name has been changed toBandwidthassociates_sales, so it's a different application. Notice that there is noonApplicationStart event implemented inBandwidthAssociates/Sales/Application.cfc, yet the event fired and showed up in the browser. This is because theApplication.cfc in the Sales subdirectoryextends the one from above, and the one above implements the onApplicationStart event, so we see it.
- The onSessionStart event fires because the application name has been changed toBandwidthassociates_sales and a session is within the context of an application. Notice that the event implementation was found in BandwidthAssociates/Sales/Application.cfc, not the Application.cfc from the directory above. That's because the onSessionStart event overrides the implementation from the directory above.
- The onRequestStart appears twice--once from theSales/Application.cfc and once from the one above. The event only fires once but because the code in theSales/Application.cfc implementation uses thesuper keyword (<cfset super.onRequestStart()>) to call theonRequestStart implementation from above, it displays in the browser twice.
- The onRequest event fires fromSales/Application.cfc. It does not call the event from above (doesn't use the super keyword), so you only see it once.
- The BandwidthAssociates/Sales/Index.cfm template is displayed showing the current time.
- Now you see the onRequestEnd event displayed because it's implemented inSales/Application.cfc.
If you refresh the page before the session and application timeout settings of 10 seconds, you'll see different results.
- You'll see the three tables that dump the contents of the application settings.
- Now you only see the onRequestStart andonRequest events displayed. This is because theapplicationTimeout and sessionTimeout settings were not exceeded, therefore the events didn't fire.
- The Index.cfm template is displayed with the current time.
- The onRequestEnd event is displayed because it's implemented in the Application.cfc.
This is how you can use the ColdFusion MX 7 Application Framework in conjunction with CFC inheritance (extends) to manage your ColdFusion applications and subapplications. You can set/implement everything that applies to all your applications at the top level, and then inherit from it as many levels deep as you need to. If you need to override something in a lower level Application.cfc, you have that ability as well. This provides for a great level of flexibility and makes it much easier to maintain your ColdFusion MX 7 WebApplications.