![]() ![]() ![]() |
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.
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.
Client state management can work without cookies as well. See Using client state management without cookies in this chapter.
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
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.
Client storage mechanisms are exclusive; when one storage type is in use, the values set in other storage options are unavailable.
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:
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.
To create a client variable and set the value of the parameter, use the CFSET or CFPARAM tag.
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.
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">
A client variable is accessed using the same syntax as other types of variables, and can be used 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>
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.
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.
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.
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.
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.
The system-provided client variables (CFID, CFToken, URLToken, HitCount, TimeCreated, and LastVisit) cannot be deleted.
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.
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.
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.
/<install_dir>/coldfusion/bin/regedit.
HKEY_LOCAL_MACHINE\SOFTWARE\Allaire\ColdFusion\ CurrentVersion\Clients
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.