Creating the Application.cfm page

The Application.cfm page defines application-level settings and functions such as the following:

Application name
Client, application, and session variable variable management options
Page processing settings
Default variables, data sources, style settings, and other application-level constants
Login processing
Application-specific error handling

Naming the application

In ColdFusion, you define an application by giving it a name using the cfapplication tag. By using a specific application name in a cfapplication tag, you define a set of pages as part of the same logical application. Although you can create an application by putting a cfapplication tag with the application name on each page, you normally put the tag in the Application.cfm file; for example:

<cfapplication name="SearchApp">

Note: The value you set for the name attribute in the cfapplication tag is limited to 64 characters.

ColdFusion supports unnamed applications, which are useful for ColdFusion applications that must interoperate with JSP tags and servlets. Consider creating an unnamed application only if your ColdFusion pages must share Application or Session scope data with existing JSP pages and servlets. You cannot have more than one unnamed application on a server. For more information on using unnamed applications, see Chapter 32, "Integrating J2EE and Java Elements in CFML Applications".

Setting the client, application, and session variables options

You use the cfapplication tag to specify client state and persistent variable use, as follows:

To use Client scope variables, you must specify clientManagement=True.
To use Session scope variables, you must specify sessionManagment=True.

You can also optionally do the following:

Set application-specific time-outs for Application and Session scope variables. These settings override the default values set in the ColdFusion Administrator.
Specify a storage method for Client scope variables. This setting overrides the method set in the ColdFusion Administrator.
Specify not to use cookies on the client browser.

For more information on configuring these options, see Chapter 15, "Using Persistent Data and Locking" and CFML Reference.

Defining page processing settings

The cfsetting tag lets you specify the following page processing attributes that you might want to apply to all pages in your application:

Attribute

Use

showDebugOutput

Specifies whether to show debugging output. This setting cannot enable debugging if it is disabled in the ColdFusion Administrator. However, this option can ensure that debugging output is not displayed, even if the Administrator enables it.

requestTimeout

Specifies the page request time-out. If ColdFusion cannot complete processing a page within the time-out period, it generates an error. This setting overrides the setting in the ColdFusion Administrator. You can use this setting to increase the page time-out if your application or page frequently accesses external resources that might be particularly slow, such as external LDAP servers or web services providers.

enableCFOutputOnly

Disables output of text that is not included inside cfoutput tags. This setting can help ensure that extraneous text that might be in your ColdFusion pages does not get displayed.

Attribute	Use
showDebugOutput	Specifies whether to show debugging output. This setting cannot enable debugging if it is disabled in the ColdFusion Administrator. However, this option can ensure that debugging output is not displayed, even if the Administrator enables it.
requestTimeout	Specifies the page request time-out. If ColdFusion cannot complete processing a page within the time-out period, it generates an error. This setting overrides the setting in the ColdFusion Administrator. You can use this setting to increase the page time-out if your application or page frequently accesses external resources that might be particularly slow, such as external LDAP servers or web services providers.
enableCFOutputOnly	Disables output of text that is not included inside `cfoutput` tags. This setting can help ensure that extraneous text that might be in your ColdFusion pages does not get displayed.

Often, you use the cfsetting tag on individual pages, but you can also use it in your Application.cfm. For example, you might use it in multi-application environment to override the ColdFusion Administrator settings in one application.

Setting application default variables and constants

You can set default variables and application-level constants on the Application.cfm page. For example, you can specify the following values:

A data source
A domain name
Style settings, such as fonts or colors
Other important application-level variables

Often, an Application.cfm page uses one or more cfinclude tags to include libraries of commonly used code, such as user-defined functions, that are required on many of the application's pages.

Processing logins

When an application requires a user to log in, you typically put the cflogin tag on the Application.cfm page. For detailed information on security and creating logins, including an Application.cfm page that manages user logins, see Chapter 16, "Securing Applications".

Handling errors

You can use the cferror tag on your Application.cfm page to specify application-specific error-handling pages for request, validation, or exception errors, as shown in the example in the following section. This way you can include application-specific information, such as contact information or application or version identifiers, in the error message, and you display all error messages in the application in a consistent manner.

You can also use the Application.cfm page to develop more sophisticated application-wide error-handling techniques, including error-handling methods that provide specific messages or use structured error-handling techniques.

For more information on error pages and error handling, see Chapter 14, "Handling Errors".

Example: an Application.cfm page

The following example shows a sample Application.cfm file that uses several of the techniques typically used in Application.cfm pages. For the sake of simplicity, it does not show login processing; for a login example, see Chapter 16, "Securing Applications".

<!--- Set application name and enable Client and Session variables --->

<cfapplication name="Products"
  clientmanagement="Yes"
  clientstorage="myCompany"
  sessionmanagement="Yes">

<!--- Set page processing attributes --->
<cfsetting showDebugOutput="No" >

<!--- Set custom global error handling pages for this application--->
<cferror type="request"
  template="requesterr.cfm"
  mailto="admin@company.com">
<cferror type="validation" 
  template="validationerr.cfm">

<!--- Set the Application variables if they aren't defined. --->
<!--- Initilialize local app_is_initialized flag to false --->
<cfset app_is_initialized = False>
<!--- Get a readonly lock --->
<cflock scope="application" type="readonly" timeout=10>
<!--- Read init flag and store it in local variable --->
  <cfset app_is_initialized = IsDefined("Application.initialized")>
</cflock>
<!--- Check the local flag --->
<cfif not app_is_initialized >
<!--- Application variables are Not initialized yet.
    Get an exclusive lock to write scope --->
  <cflock scope="application" type="exclusive" timeout=10>
    <!--- Check the Application scope initialized flag since another request could
      have set the variables after this page released the read-only lock. --->
    <cfif not IsDefined("Application.initialized") >
      <!--- Do initializations --->
      <cfset Application.ReadOnlyData.Company = "MyCompany" >
      <!--- and so on ---> 
      <!--- Set the Application scope initialization flag --->
      <cfset Application.initialized = "yes">
    </cfif>
  </cflock>
</cfif>

<!--- Set a Session variable.--->
<cflock  timeout="20" scope="Session" type="exclusive">
  <cfif not IsDefined("session.pagesHit")>
    <cfset session.pagesHit=1>
  <cfelse>
    <cfset session.pagesHit=session.pagesHit+1>
  </cfif>
</cflock>

<!--- Set Application-specific Variables scope variables. --->
<cfset mainpage = "default.cfm">
<cfset current_page = "#cgi.path_info#?#cgi.query_string#">

<!--- Include a file containing user-defined functions called throughout
    the application --->
<cfinclude template="commonfiles/productudfs.cfm">

Reviewing the code

The following table describes the code and its function:

Code

Description

<cfapplication name="Products" clientmanagement="Yes" clientstorage="myCompany" sessionmanagement="Yes">

Names the application, enables Client and Session scope variables, and sets the client variable store to the myCompany data source.

<cfsetting showDebugOutput="No" >

Ensure that debugging output is not displayed, if the ColdFusion MX Administrator enables it.

<cferror type="request" template="requesterr.cfm" mailto="admin@company.com"> <cferror type="validation" template="validationerr.cfm">

Specifies custom error handlers for request and validation errors encountered in the application. Specifies the mailing address for use in the request error handler.

<cfset app_is_initialized = False> . . .

Sets the Application scope variables, if they are not already set. For a detailed description of the technique used to set the Application scope variables, see Chapter 15, "Using Persistent Data and Locking".

<cflock timeout="20" scope="Session" type="exclusive"> <cfif not IsDefined("session.pagesHit")> <cfset session.pagesHit=1> <cfelse> <cfset session.pagesHit= session.pagesHit+1> </cfif> </cflock>

Sets the Session scope pagesHit variable, which counts the number of pages touched in this session. If the variable does not exist, creates it. Otherwise, increments it.

<cfset mainpage = "default.cfm"> <cfset current_page = "#cgi.path_info#?#cgi.query_string#">

Sets two Variables scope variables that are used throughout the application. Creates the current_page variable dynamically; it's value varies from request to request.

<cfinclude template= "commonfiles/productudfs.cfm">

Includes a library of user-defined functions that are used in most pages in the application.

Developing ColdFusion MX Applications with CFML
Designing and Optimizing a ColdFusion Application

Code	Description
<cfapplication name="Products" clientmanagement="Yes" clientstorage="myCompany" sessionmanagement="Yes">	Names the application, enables Client and Session scope variables, and sets the client variable store to the myCompany data source.
<cfsetting showDebugOutput="No" >	Ensure that debugging output is not displayed, if the ColdFusion MX Administrator enables it.
<cferror type="request" template="requesterr.cfm" mailto="admin@company.com"> <cferror type="validation" template="validationerr.cfm">	Specifies custom error handlers for request and validation errors encountered in the application. Specifies the mailing address for use in the request error handler.
<cfset app_is_initialized = False> . . .	Sets the Application scope variables, if they are not already set. For a detailed description of the technique used to set the Application scope variables, see Chapter 15, "Using Persistent Data and Locking".
<cflock timeout="20" scope="Session" type="exclusive"> <cfif not IsDefined("session.pagesHit")> <cfset session.pagesHit=1> <cfelse> <cfset session.pagesHit= session.pagesHit+1> </cfif> </cflock>	Sets the Session scope `pagesHit` variable, which counts the number of pages touched in this session. If the variable does not exist, creates it. Otherwise, increments it.
<cfset mainpage = "default.cfm"> <cfset current_page = "#cgi.path_info#?#cgi.query_string#">	Sets two Variables scope variables that are used throughout the application. Creates the current_page variable dynamically; it's value varies from request to request.
<cfinclude template= "commonfiles/productudfs.cfm">	Includes a library of user-defined functions that are used in most pages in the application.