|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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:
|
|
|
- Turn on client state management by setting
CLIENTMANGEMENT="Yes" in the CFAPPLICATION tag in your Application.cfm file.
<CFAPPLICATION NAME="myapplication"
ClientManagement="Yes">
- 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"
- 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
- CFID
- CFToken
- URLToken
- HitCount
- TimeCreated
- LastVisit
|
|
|
|
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:
Registry
- The name of a configured client store
Cookie
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:
- Netscape Navigator allows 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.
- Netscape Navigator sets a size limit of 4K bytes per cookie. ColdFusion encodes non-alphanumeric 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 for each client. ColdFusion will throw an error if you try to store more than 4000 encoded bytes of data for a client.
|
|
|
|
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.
|
|
|
  
|
|
|
AllaireDoc@allaire.com
Copyright © 1998, Allaire Corporation. All rights reserved.
|