BackUp LevelNext

Client Variables

In ColdFusion, client variables help you to keep track of users as they move through the pages within an application. They offer a convenient way to store user preferences.

ColdFusion achieves client state management by creating a client record for each browser that requests a page in an application in which client state management is enabled. The client record is identified by a unique token (a combination of CFID and CFTOKEN), which is stored in an HTTP cookie in the user's browser.

The application can then define variables within the client record. These client variables are accessible as parameters in every application page that the client requests within the scope of an application.

See the Client Variables and Client State Management section in the Using the Application Framework chapter for information on setting up client state management using the CLIENTMANAGEMENT attribute in the CFAPPLICATION tag.

Creating a client variable

When client state management is enabled for an application, you can use the system to keep track of any number of variables associated with a particular client.

You create client variables by defining a variable with the Client scope using either the CFSET or CFPARAM tag.

To create a client variable:

  1. Turn on client state management by setting CLIENTMANGEMENT="Yes" in the CFAPPLICATION tag in your Application.cfm file.
    <CFAPPLICATION NAME="myapplication"
        ClientManagement="Yes">
    
  2. Also in the CFAPPLICATION tag, choose a storage location for your client variables by adding the CLIENTSTORAGE attribute.

    The default location is set in the Variables page of the ColdFusion Administrator. It can be the system registry, an existing datasource, or cookies.

    See Client variable storage options for more information.

    ClientStorage="mydatasource"
    
  3. In ColdFusion Studio, click the CFSET tool. Enter the variable name, preceded by the Client scope, and assign a value to it, for example:
    <CFSET Client.FavoriteColor="Cornflower Blue">
    

    See Variable names for guidelines on creating variable names.

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

Standard client variables

In addition to storing custom client variables, the Client object has several standard variables. These variables can be useful in providing customized 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>

The standard Client object attributes are read-only (they can be accessed but not set by your application) and include

Note

In the Variables page of the ColdFusion Administrator, you disable automatic updating of global variables. This keeps ColdFusion from updating every page when client variables are enabled. See Administering ColdFusion Server for more information.

Using client state management without cookies

You can use ColdFusion's client state management without cookies. To use this functionality, you must pass the client ID (CFID) and the client security token (CFTOKEN) between pages, either in hidden form fields or appended to URLs.

Note

In ColdFusion, client state management is explicitly designed to work with cookies, the standard tool for identifying clients. Using client state management without cookies requires careful programming to ensure that the URLToken is always passed between application pages.

Client variable storage options

The system-wide default for storing client variables is in the system registry. In the ColdFusion Administrator, you can change this setting and choose instead to store client variables in a SQL database or in cookies.

You do this in two steps: by configuring the client variable storage option in the ColdFusion Administrator, and then noting the client variable storage location in the CFAPPLICATION tag. See Administering ColdFusion Server for information on using the Administrator to set up a client variable storage location.

You use the CLIENTSTORAGE attribute in the CFAPPLICATION tag to specify where you want to store client variables, providing one of three values:

The following example shows how you enable client state management using a sample database called mydatasource.

<CFAPPLICATION NAME="myapplication"
    CLIENTMANAGEMENT="Yes"
    CLIENTSTORAGE="mydatasource">

If no CLIENTSTORAGE setting is specified, the default location, as noted in the ColdFusion Administrator Variables page, is used.

Note

Client storage mechanisms are exclusive; when one storage type is in use, the values stored in other client stores are unavailable.

Storing client variables in cookies

When you choose CLIENTSTORAGE="Cookie", ColdFusion creates a cookie named for the application 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 won't work.

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

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 variable names defined for the application context declared by CFAPPLICATION, if any. 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 persist over time. (In this fashion they are akin to cookies.) To delete a client variable, use the DeleteClientVariable function. For example:

<CFSET IsDeleteSuccessful=DeleteClientVariable("MyClientVariable")>

The DeleteClientVariable function operates only on variables within the scope declared by CFAPPLICATION, if any.

Also, through the Variables page of the ColdFusion Administrator, you can edit the client variable storage to remove client variables after a set number of days. (The default value is 90 days if client variables are stored in the registry, ten days if stored in a datasource.)

Note

You cannot delete the system-provided client variables (CFID, CFToken, URLToken, HitCount, TimeCreated, and LastVisit).

For more information

For more information about using client variables in ColdFusion applications, see Chapter 6, Using the Application Framework.


BackUp LevelNext

allaire

AllaireDoc@allaire.com
Copyright © 1998, Allaire Corporation. All rights reserved.