Client Variables

Client variables are a great variable scope to use for persistent application variables. Client variables might be the best choice for your application. Things that you need to consider when deciding on which variable type to use for your application include the following:

Are there any web-browser version issues or user limitations?
Do you want to risk server stability?
Does your application currently need to be deployed across a clustered environment or might it be in the future?

One of the greatest advantages of client variables is that they are not stored in the server memory, so we don't have to worry about memory corruption issues. Client variables can be stored in any of three places:

In the web server's registry
In cookies
In a database (with or without cookies)

Understanding Client Variables

Client variables are persistent variables that you can use in your ColdFusion application to keep track of user variable values as that user moves from page to page within the application. Each user is tagged with a unique CFID / CFTOKEN combination. Depending on how you choose to implement client variables, the values of CFID and CFTOKEN might be stored and passed from page to page in different manners.

We've said that client variables can be stored in the ColdFusion Server's registry, in cookies on the client machine, or in a database. The choice of which of these methods to use for storage of the client variables can have a negative effect on application performance, but can save you some headaches in the bigger picture.

Here are a few reasons that you might want to use client variables:

Variable values can be saved in a number of manners.
Each method of storage has its own timeout period.
Client variables are application-specific; so if you're running multiple applications on the same server, you can set client variables that are specific to each application.
You don't need to worry about using CFLOCK on your client variables because their values are not stored in server memory.

Of course, client variable storage has its downside too:

Client variables can be stored only as strings and cannot be complex data types, such as arrays and structures.

Enabling Client Variables

Prior to using client variables in your application, you must enable them. To enable client variables, you must enable them within the CFAPPLICATION tag in the Application.cfm template.

<cfapplication 
   name="ICFMX" 
   applicationtimeout="#CreateTimeSpan(0,12,0,0)#" 
   sessionmanagement="Yes" 
   sessiontimeout="#CreateTimeSpan(0,0,30,0)#" 
    clientmanagement="Yes">

Storing Client Variables

We've already discussed the fact that client variables can be stored in a number of locations. By default, client variables are stored in the ColdFusion Server's registry. You can specify, however, that they be stored in cookies or in a separate database.

Table 8.3 runs down the advantages and disadvantages of storing client variables in the server's registry.

Table 8.3. Advantages and Disadvantages of Registry-Based Client Variable Storage

Advantages	Disadvantages
Easy implementation Good performance Registry can be easily exported to other servers Server-side control	Registry- size limitations Limited to specific server; not cluster-friendly OS limitations

You might choose to store your client variables in simple cookies on the client machine. You need to be aware that you face the standard limitations of cookies and user preferences regarding them. Cookies perform well and are easy to implement, but you might want to consider all the pros and cons of storing client variables in cookies, as outlined in Table 8.4.

Table 8.4. Advantages and Disadvantages of Cookie-Based Client Variable Storage

Advantages	Disadvantages
Easy implementation Good performance Flexible expiration Client-side control	User preferences Limits on cookie size Browser limitations on the number of cookies stored

{% if main.adsdop %}{% include 'adsenceinline.tpl' %}{% endif %}

Storing client variables in a database of their own is a great idea for a number of reasons. However, it also has its downsides. Table 8.5 presents both sides of the issue.

Table 8.5. Considerations of Database Client Variable Storage

Advantages	Disadvantages
Can use existing datasource Portable Cluster-friendly	Complex to implement Performance issues due to frequent database interaction

Using Client Variables

Of the variable scopes used to maintain user state, client variables are the one solution that could really be considered long- term . They do have their limitations, though. We mentioned earlier that client variables must be strings. They cannot be arrays, structures, query objects, eXtensible Markup Language (XML) documents, or other complex data types. You could, however, convert the complex data type to WDDX format for storage as a client variable and then convert it back to its original state prior to use.

Client variables are created just like many of the other variable scopes in ColdFusion, by using the CFSET or CFPARAM tags.

<cfset client.AppStyle="Patriotic">

<cfparam name="client.AppStyle" default="Standard">

After you have set the client variable, it is available for use within any page in the application for the particular client that set the variable. By using the CFPARAM tag to set a default value for the variable name, you can be assured that you can always use the variable without using a CFIF statement to evaluate the variable's existence.

Accessing client variables is easy. You don't have to refer to their storage method or anything like that; you simply call the variable name with the client scope:

<cfoutput> 
  Show the application in the #client.AppStyle# theme. 
</cfoutput>

If you're not sure what client variables are currently available to a client, you can always call the CFDUMP tag to output the client structure. However, this shows you all the existing client variables. If you only want to output the custom variables that have been created through the application, you can use the GetClientVariablesList() function:

<cfoutput>#GetClientVariablesList()#</cfoutput>

Because client variables are held in a structure, you can delete or manipulate client variables with any of the standard structure functions. There is, however, another method of deleting a client variable. You can use ColdFusion's DeleteClientVariable() function:

<cfset tmp=DeleteClientVariable("client.AppStyle")>

Only custom client variables can be deleted. This excludes the default client variables (see Table 8.6). Client variables can also be timed out. Within the ColdFusion MX Administrator, you can set default timeouts for your client variables.

If you call a CFLOCATION when using client variables in your application, the CFID and CFTOKEN automatically are appended to your URL when you are calling a CFM or DBM page. You can disable this feature by adding the addtoken attribute to your CFLOCATION tag and specifying the following:

<cflocation url="/index.cfm?display=News" Addtoken="No">

If you need to pass other parameters along the URL, you can run into trouble with the automatic inclusion of CFID and CFTOKEN . What happens is that the automatically included parameters are formatted as ?CFID=3&CFTOKEN=39297791 . The problem occurs when this is appended to a URL that already has URL parameters included. The resulting URL call might look like this:

http://www.insidecoldfusionmx.com/index.cfm?display_code=News?CFID=3&CFTOKEN=39297791

Errors will result.

As with many of our other variable scopes, there are a few client variables that are predefined. The client scope has six built-in, read-only variables. These are outlined in Table 8.6.

Table 8.6. Client Scope Variables

Variable	Description
`Client.CFID`	The client ID.
`Client.CFToken`	The client security token.
`Client.URLToken`	A concatenation of `CFID` and `CFTOKEN` . Stored as `CFID=123&CFTOKEN=23457323` . This variable is useful if the client does not support cookies and you must pass the `CFID` and `CFTOKEN` values.
`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 at which the `CFID` and `CFTOKEN` variables of the client were created.