|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Client Variables and Client State Management
|
|
|
|
The Web is a stateless system. Each connection that a browser makes to a Web server is unique in the eyes of the Web server. However, within an application it is important to be able to keep track of users as they move through the pages within the application. This is the definition of client state management.
ColdFusion achieves client state management by creating a client record for each browser that requests an application page in an application in which client state management is enabled. The client record is identified by a unique token that 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 the application.
|
|
|
|
Enabling Client State Management
|
|
|
To set up client state management, each page in the application must contain a CFAPPLICATION tag that sets the name of the application and enables the CLIENTMANAGEMENT attribute. The best place to put this tag is at the beginning of the Application.cfm file, which is included in all of the application's pages. This way client state management is enabled for every page in the application.
For example, to enable client state management for the sample Products application, add this CFAPPLICATION code to the beginning of the Application.cfm file:
<CFAPPLICATION NAME="Products" CLIENTMANAGEMENT="Yes">
All application pages at and beneath this Application.cfm file in the directory structure are now able to use client state management.
|
|
|
|
Note
|
|
|
Client state management can work without cookies as well. See Using client state management without cookies in this chapter.
|
|
|
|
Choosing a client variable storage method |
|
|
|
The system-wide default is for client variables to be stored in the system registry. But your site administrator can choose to store them instead in a SQL database or in cookies.
There are two steps to changing client variable storage: by setting a client variable storage option in the Variables page of the ColdFusion Administrator, and then by noting the client variable storage location in the CFAPPLICATION tag. See Administering ColdFusion Server for information on using the ColdFusion Administrator.
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 set in other storage options are unavailable.
|
|
|
|
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 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. This limits you to 17 unique applications per host.
- Netscape Navigator sets a size limit of 4K bytes per cookie. ColdFusion encodes non-alpha-numeric 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 will throw an error if you try to store more than 4000 encoded bytes of data for a client.
|
|
|
|
Using client state management |
|
|
|
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.
|
|
|
|
Creating a client variable
|
|
|
To create a client variable and set the value of the parameter, use the CFSET or CFPARAM tag.
|
|
|
|
Example
|
|
|
The following example sets the value of a client variable named FavoriteColor to "Red":
<CFSET Client.FavoriteColor="Red">
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.
|
|
|
|
Example
|
|
|
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">
|
|
|
|
Using client variables
|
|
|
A client variable is accessed using the same syntax as other types of variables, and can be used anywhere other ColdFusion variables are used.
|
|
|
|
Example
|
|
|
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
|
|
|
In addition to storing custom client variables, the Client object has several standard parameters. These parameters 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, and LastVisit.
|
|
|
|
Using client state management without cookies
|
|
|
You can use ColdFusion's client state management without cookies. However, we do not recommend this course. Developers who choose to maintain client state without cookies must ensure that every request carries CFID and CFTOKEN.
To maintain client state without cookies, set the SETCLIENTCOOKIES attribute of the CFAPPLICATION tag to No. Then, the developer must maintain client state in URLs. by passing the client ID (CFID)and the client security token (CFTOKEN) between pages, either in hidden form fields or appended to URLs. You accomplish this using the variable Client.URLTOKEN or Session.URLTOKEN.
|
|
|
|
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.
|
|
|
|
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. See the CFML Language Reference for more information on this function.
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 when client variables are stored in the registry, ten days when stored in a data source.)
See Administering ColdFusion Server for more information about setting time-out values.
|
|
|
|
Note
|
|
|
The system-provided client variables (CFID, CFToken, URLToken, HitCount, TimeCreated, and LastVisit) cannot be deleted.
|
|
|
|
Client variables with CFLOCATION behavior
|
|
|
When using CFLOCATION to redirect to a path that contains .dbm or .cfm, the Client.URLToken is automatically appended to the URL. This behavior can be suppressed by adding the attribute ADDTOKEN="No" to the CFLOCATION tag.
|
|
|
|
Variable caching
|
|
|
All client variable reads and writes are cached to help decrease the overhead of client state management operations. See the Adminstering ColdFusion Server book for information on variables and server clustering.
|
|
|
|
Exporting the client variable database
|
|
|
If your client variable database is stored in the 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 registry allows you to export and import registry entries.
|
|
|
|
To export your client variable database from the registry:
|
|
|
- Open the registry editor. In UNIX, use the program,
/<install_dir>/coldfusion/bin/regedit.
- Find and select the following key:
HKEY_LOCAL_MACHINE\SOFTWARE\Allaire\ColdFusion\ CurrentVersion\Clients
- On the Registry menu, click Export Registry File.
- Enter a name for the registry file.
Once you've created a registry file, you can take it to a new machine and import it by selecting Import Registry File on the Registry Editor Registry menu.
For more information on using variables in ColdFusion applications, see Chapter 4, Creating and Manipulating Variables in this book.
|
|
|
  
|
|
|
AllaireDoc@allaire.com
Copyright © 1998, Allaire Corporation. All rights reserved.
|