Developing ColdFusion Applications
Using the Application Framework

Configuring and Using Client Variables

To use Client variables effectively, you set up the Client variable options and use the variables on your ColdFusion pages.

Setting up Client variable options

If you want to enable Client variables, you must do so on every page in an application. Because the Application.cfm file is included in all of the application's pages, you enable client management in the cfapplication tag, at the beginning of Application.cfm.

To enable client state management:

1. Open the file Application.cfm in ColdFusion Studio and modify it so that it appears as follows:

   <!--- This example illustrates cfapplication --->
   
   
   
   <!--- Name the application and enable client management--->
   
   <cfapplication NAME="SearchApp" 
   
   clientmanagement="Yes">
   
   

2. Save the file as Application.cfm in the root directory of your application framework.

Choosing a Client variable storage method

After you enable client state management, you must determine where you want to store Client variables. The system-wide default is to store Client variables in the Registry. But you can choose to store them instead in a SQL database or in cookies.

The ColdFusion Administrator Server Client Variables page controls the default Client variable location. You can override the default location by specifying a clientstorage attribute in the cfapplication tag.

You can specify the following values in the clientStorage attribute:

• Registry(the default)
• Name of a data source configured in the ColdFusion Administrator
• Cookie

As a general rule, it is most efficient to store Client variables in a database.

Cookie storage

When you set clientstorage="Cookie" the cookie that ColdFusion creates has the application's name. Storing client data in a cookie is scalable to large numbers of clients, but this storage mechanism has some limitations. Chief among them is that if the client turns off cookies in the browser, Client variables do not work.

Consider these additional limitations before implementing cookie storage for Client variables:

• Many browsers allow only 20 cookies from a particular host to be set. ColdFusion uses two of these cookies for CFID and CFToken and also creates a cookie named cfglobals to hold global data about the client, such as HitCount, TimeCreated, and LastVisit. This limits you to 17 unique applications per host.
• Some browsers set a size limit of 4K bytes per cookie. ColdFusion encodes nonalphanumeric data in cookies with a URL encoding scheme that expands at a 3-1 ratio, which means you should not store large amounts of data per client. ColdFusion throws an error if you try to store more than 4000 encoded bytes of data for a client.

Specifying Client variable storage in Application.cfm

The following example shows how to enable Client variable management using a sample database called mydatasource.

To specify the Client variable storage method:

1. Open the file Application.cfm in ColdFusion Studio and modify it so that it appears as follows:

   <!--- This example illustrates cfapplication --->
   
   
   
   <!--- Name the application and enable client management--->
   
   <cfapplication NAME="SearchApp" 
   
   clientmanagement="Yes"
   
   clientstorage="mydatasource">
   
   

2. Save the file as Application.cfm in the root directory of your application framework.

Using Client variables

When you enable Client variables for an application, you can use them to keep track of long-term information that is associated with a particular client.

Creating a Client variable

To create a Client variable and set the value of the parameter, use the cfset or cfparam tag; for example:

<cfset Client.FavoriteColor="Red">

After you set a Client variable in this manner, it is available for use within any page in your application that is accessed by the client for whom the variable is set.

The following example shows how to use the cfparam tag to check for the existence of a client parameter and to set a default value if the parameter does not already exist:

<cfparam name="Client.FavoriteColor" default="Red">

Accessing and changing Client variables

You use the same syntax to access a Client variable as other types of variables. You can use Client variables anywhere other ColdFusion variables are used.

To display the favorite color that has been set for a specific user, use the following code:

<cfoutput>

  Your favorite color is #Client.FavoriteColor#.

</cfoutput>

Standard Client variables

The Client scope has six built-in, read-only variables that your application can use:

Variable	Description
Client.CFID	The client ID, normally stored on the client system as a cookie.
Client.CFToken	The client security token, normally stored on the client system as a cookie.
Client.URLToken	A combination of the CFID and CFToken in the form CFID=IDNum&CFTOKEN=tokenNum. This variable is useful if the client does not support cookies and you must pass the CFID and CFToken variables from page to page.
Client.HitCount	The number of page requests made by the client.
Client.LastVisit	The last time the client visited the application.
Client.TimeCreated	The time the CFID and CFToken variables that identify the client to ColdFusion were first created.

You can use the Client.HitCount and time information variables in customizing behavior, depending on how often users visit your site and when they last visited. For example, the following code shows the date of a user's last visit to your site:

<cfoutput>

Welcome back to the Web SuperShop. Your last 

visit was on #DateFormat(Client.LastVisit)#.

</cfoutput>

Getting a list of Client variables

To obtain a list of the custom client parameters associated with a particular client, use the GetClientVariablesList function.

<cfoutput>#GetClientVariablesList()#</cfoutput>

The GetClientVariablesList function returns a comma-separated list of the names of the Client variables for the current application. The standard system-provided Client variables (CFID, CFToken, URLToken, HitCount, TimeCreated, and LastVisit) are not returned in the list.

Deleting Client variables

Unlike normal variables, Client variables and their values are not stored in volatile memory and persist over time. To delete a Client variable, use the DeleteClientVariable function; for example:

<cfset IsDeleteSuccessful=DeleteClientVariable("MyClientVariable")>

The DeleteClientVariable function deletes only Client variables for the application specified by cfapplication, if any. For more information on this function, see the CFML Reference.

Also, using the Client Variables page of the ColdFusion Administrator Server tab, you can edit the Client variable storage to remove Client variables stored in either the Registry or a database after a set number of days. (The default value is 90 days when Client variables are stored in the registry, 10 days when stored in a data source.)

For more information about setting timeout values, see Advanced ColdFusion Administration.

Using Client variables with cflocation

If you use the cflocation tag to redirect to a path that ends in .dbm or .cfm, the Client.URLToken is automatically appended to the URL. You can suppress this behavior by adding the attribute addtoken="No" to the cflocation tag.

Client variable caching

All Client variable reads and writes are cached to help decrease the overhead of client state management operations. For information on variables and server clustering, see Advanced ColdFusion Administration.

Exporting the Client variable database

If your Client variable database is stored in the Windows system registry and you need to move it to another machine, you can export the registry key that stores your Client variables and take it to your new server. The system tegistry allows you to export and import Registry entries.

To export your Client variable database from the registry in Windows:

1. Open the Registry editor.
2. Find and select the following key:

   HKEY_LOCAL_MACHINE\SOFTWARE\Allaire\ColdFusion\ 
   
   CurrentVersion\Clients
   
   

3. On the Registry menu, click Export Registry File.
4. Enter a name for the registry file.

After you create a registry file, you can copy it to a new machine and import it by selecting Import Registry File on the Registry Editor Registry menu.

On UNIX systems, the registry entries are kept in /opt/coldfusion/registry/cf.registry, a text file that you can copy and edit directly.

Copyright © 2001, Macromedia Inc. All rights reserved.

---