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.

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,this is not recommended. If you choose to maintain client state without cookies, you 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, you 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 applicati.

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 Administering ColdFusion Server 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.

Note To export your client variable database from the registry:
  1. Open the registry editor. In UNIX, use the program, /<install_dir>/coldfusion/bin/regedit.
  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.

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.