cfapplication

Description

Defines the scope of a ColdFusion application; enables and disables storage of Client variables; specifies the Client variable storage mechanism; enables Session variables; and sets Application variable time-outs.

History

ColdFusion 9: Added datasource, googleMapKey, and serverSideFormValidation attribute ColdFusion 8: Added secureJSON and SecureJSONPrefix attributes ColdFusion MX 7: Added scriptProtect attribute ColdFusion MX 6.1: Added loginStorage attribute ColdFusion MX: Changed how persistent scopes are available: Server, Session, and Application scope variables are stored in memory as structures. In earlier releases, only Session and Application scope variables were stored this way. You cannot access the UDF function scope as a structure. Changed the algorithm for setting the CFTOKEN variable value: if the registry key UUIDToken is a nonzero value, ColdFusion uses a number constructed from the UUID plus a random number. Otherwise, ColdFusion sets the CFTOKEN variable default value using a positive random integer. (In earlier releases, ColdFusion always used a number constructed from the UUID plus a random number.)

Syntax

<cfapplication  
    datasource="data_source_name" 
    name = "application name" 
    applicationTimeout = #CreateTimeSpan(days, hours, minutes, seconds)# 
    clientManagement = "yes|no" 
    clientStorage = "data_source_name|Registry|Cookie"  
    loginStorage = "cookie|session" 
    googleMapKey = "map key" 
    scriptProtect = "none|all|list" 
    serverSideFormValidation = "yes|no" 
    sessionManagement = "yes|no" 
    sessionTimeout = #CreateTimeSpan(days, hours, minutes, seconds)# 
    setClientCookies = "yes|no"  
    setDomainCookies = "yes|no">

Note: You can specify this tag’s attributes in an attributeCollection whose value is a structure. Specify the structure name in the attributeCollection and use the tag’s attribute names as structure keys.

Attributes

Attribute	Description	Required	Default
applicationTimeout	Lifespan of application variables. CreateTimeSpan function and values in days, hours, minutes, and seconds, separated by commas.	Optional	Specified in Variables page of ColdFusion Administrator
clientManagement	yes: enables client variables. no	Optional	no
clientStorage	How client variables are stored: datasource_name: in ODBC or native data source. Create storage repository in the Administrator. registry: in the system registry. cookie: on client computer in a cookie. Scalable. If client disables cookies in the browser, client variables do not work.	Optional	registry
datasource	Name of the data source from which the query retrieves data.	Optional
googleMapKey	The Google Maps API key required to embed Google Maps in your web pages.	Optional
loginStorage	cookie: store login information in the Cookie scope. session: store login information in the Session scope.	Optional	cookie
name	Name of application. Up to 64 characters. For Application and Session variables: Required. For Client variables: Optional	See Description
scriptProtect	Specifies whether to protect variables from cross-site scripting attacks none: do not protect variables all: protect Form, URL, CGI, and Cookie variables comma-delimited list of ColdFusion scopes: protect variables in the specified scopes. For more information, see Usage.	Optional	Determined by ColdFusion Administrator Enable Global Script Protection setting
secureJSON	A Boolean value that specifies whether to add a security prefix in front of any value that a ColdFusion function returns in JSON-format in response to a remote call. The default value is the value of the Prefix serialized JSON setting in the Administrator Server Settings > Settings page (which defaults to false). You can override this variable value in the cffunction tag. For more information see Improving security in the Developing ColdFusion Applications.	Optional	Administrator value
secureJSONPrefix	The security prefix to put in front of the value that a ColdFusion function returns in JSON-format in response to a remote call if the secureJSON setting is true. The default value is the value of the Prefix serialized JSON setting in the Administrator Server Settings > Settings page (which defaults to //, the JavaScript comment character). For more information see Improving security in the Developing ColdFusion Applications.	Optional	Administrator value
serverSideFormValidation	If no, disables validation on cfform fields when the form is submitted.	Optional	yes
sessionManagement	yes: enables session variables. no	Optional	no
sessionTimeout	Life span of session variables. CreateTimeSpan function and values in days, hours, minutes, and seconds, separated by commas.	Optional	Specified in Variables page of ColdFusion Administrator
setClientCookies	yes: enables client cookies. no: ColdFusion does not automatically send CFID and CFTOKEN cookies to client browser; you must manually code CFID and CFTOKEN on the URL for every page that uses Session or Client variables.	Optional	yes
setDomainCookies	yes: uses domain cookies for CFID and CFTOKEN cookies and for all Client variables when using cookies for client variable storage. Required for applications running on clusters. no: uses host-specific cookies for CFID, CFTOKEN, and all client variable cookies.	Optional	no

Usage

This tag is typically used in the Application.cfm file, to set defaults for a ColdFusion application.
Note: You can also set the application defaults in the Application.cfc file. For more information, see Application variables.
This tag enables application variables, unless they are disabled in the ColdFusion Administrator. The Administrator setting also overrides the sessionManagement attribute. For more information, see Configuring and Administering ColdFusion.
If ColdFusion is running on a cluster, specify clientStorage = "cookie" or a data source name; you cannot specify "registry".
ColdFusion generates an error if the application name is longer than 64 characters.
The CFTOKEN variable is 8 bytes in length. Its range is 10000000 —99999999.
Note: If you specify ClientStorage=cookie, any Client scope variables set following a cfflush tag are not saved in the Client browser.

Example

<!--- This example shows how to use cflock to prevent race conditions during data updates to variables in Application, Server, and Session scopes. ---> 
<h3>cfapplication Example</h3> 
cfapplication defines scoping for a ColdFusion application and enables or disables application and/or session variable storage. This tag is placed in a special file called Application.cfm that automatically runs before any other CF page in a directory (or subdirectory) where the Application.cfm file appears.</p> 
 
<cfapplication name = "ETurtle"  
sessionTimeout = #CreateTimeSpan(0, 0, 0, 60)#  
sessionManagement = "Yes"> 
 
<!--- Initialize session and application variables used by E-Turtleneck. --->  
<cfparam name="application.number" default="1"> 
<cfparam name="session.color" default= ""> 
<cfparam name="session.size" default=""> 
 
<cfif IsDefined("session.numPurchased") AND IsNumeric(trim(session.cartTotal))> 
<!--- Use the application scope for the application variable to prevent race condition. This variable keeps track of total number of turtlenecks sold. ---> 
    <cflock scope = "Application" timeout = "30" type = "Exclusive"> 
    <cfset application.number = application.number + session.numPurchased> 
    </cflock> 
</cfif> 
 
<cfoutput> 
E-Turtleneck is proud to say that we have sold #application.number# turtlenecks to date. 
</cfoutput> 
<!--- End of Application.cfm --->

cfmldocs