When you enable client variables for an application, you can use them to keep track of long-term information that is associated with a particular client.
Client variables must be simple data types: strings, numbers, lists, Booleans, or date and time values. They cannot be arrays, record sets, XML objects, query objects, or other objects. If you must store a complex data type as a client variable, you can use the cfwddx tag to convert the data to WDDX format (which is represented as a string), store the WDDX data, and use the cfwddx tag to convert the data back when you read it. For more information on using WDDX, see Using WDDX.
To create a client variable and set its value, use the cfset or cfparam tag and use the Client scope identifier as a variable prefix; for example:
<cfset Client.FavoriteColor="Red">
After you set a client variable this way, it is available for use within any 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 set a default value if the parameter does not already exist:
<cfparam name="Client.FavoriteColor" default="Red">
Accessing and changing client variables
You use the same syntax to access a client variable as for other types of variables. You can use client variables anywhere you use other ColdFusion variables.
To display the favorite color that has been set for a specific user, for example, use the following code:
<cfoutput> Your favorite color is #Client.FavoriteColor#. </cfoutput>
To change the client's favorite color, for example, use code such as the following:
<cfset Client.FavoriteColor = Form.FavoriteColor>
The Client scope has the following built-in, read-only variables that your application can use:
Variable |
Description |
---|---|
Client.CFID |
The client ID, normally stored on the client system as a cookie. |
Client.CFToken |
The client security token, normally stored on the client system as a cookie. |
Client.URLToken |
Value depends on whether J2EE session management is enabled. No session management or ColdFusion session management: A combination of the CFID and CFToken values, in the form CFID J2EE session management: A combination of CFID, CFToken, and session ID values in the form CFID= |
Client.HitCount |
The number of page requests made by the client. |
Client.LastVisit |
The last time the client visited the application. |
Client.TimeCreated |
The time the CFID and CFToken variables that identify the client to ColdFusion were first created. |
You use the Client.CFID, Client.CFToken, and Client.URLToken variables if your application supports browsers that do not allow cookies. For more information on supporting browsers that do not allow cookies, see Using client and session variables without cookies.
You can use the Client.HitCount and time information variables to customize behavior that depends 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>
Getting a list of client variables
To obtain a list of the custom client parameters associated with a particular client, use the GetClientVariablesList function, as follows:
<cfoutput>#GetClientVariablesList()#</cfoutput>
The GetClientVariablesList function returns a comma-separated list of the names of the client variables for the current application. The standard system-provided client variables (CFID, CFToken, URLToken, HitCount, TimeCreated, and LastVisit) are not returned in the list.
To delete a client variable, use the StructDelete function or the DeleteClientVariable function. For example, the following lines are equivalent:
<cfset IsDeleteSuccessful=DeleteClientVariable("MyClientVariable")> <cfset IsDeleteSuccessful=StructDelete(Client, "MyClientVariable")>
The Client Variables page in the ColdFusion Administrator lets you set a time-out period of inactivity after which ColdFusion removes client variables stored in either the Registry or a data source. (The default value is 10 days for client variables stored in the Registry, and 90 days for client variables stored in a data source.)
Using client variables with cflocation
If you use the cflocation tag to redirect ColdFusion to a path that ends with .dbm or .cfm, the Client.URLToken variable is automatically appended to the URL. You can prevent this behavior by adding the attribute addtoken="No" to the cflocation tag.
When ColdFusion reads or writes client variables, it caches the variables in memory to help decrease the overhead of accessing the client data. As a result, ColdFusion only accesses the client data store when you read its value for the first time or, for values you set, when the request ends. Additional references to the client variable use the cached value in ColdFusion memory, thereby processing the page more quickly.
Exporting the client variable database
If your client variable database is stored in the Windows 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 lets you export and import Registry entries.
To export your client variable database from the Registry in Windows:
After you create a Registry file, you can copy it to a new machine and import it by clicking Import Registry File on the Registry editor Registry menu.