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:
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:
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:
Of course, client variable storage has its downside too:
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.
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.
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.
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.
<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:
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:
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:
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.