Configuring and using client variables

Use client variables for data that is associated with a particular client and application and that must be saved between user sessions. Use client variables for long-term information such as user display or content preferences.

This section describes the following topics:

Enabling client variables

To enable client variables, you specify This.clientmanagement="True" in the Application.cfc initialization code, or set the cfapplication tag clientmanagement attribute to Yes in the Application.cfm file. For example, to enable client variables in an application named SearchApp, you can use the following line in the application's Application.cfm page:

<cfapplication NAME="SearchApp" clientmanagement="Yes">

Choosing a client variable storage method

By default, Coldfusion stores client variables in the Registry. In most cases, however, it is more appropriate to store the information as client cookies or in a SQL database.

The ColdFusion MX Administrator Client Variables page controls the default client variable location. You can override the default location by specifying a This.clientStorage value in Application.cfc or by setting the clientStorage attribute in the cfapplication tag.

You can specify the following values for the client storage method:

Registry(default). Client variables are stored under the key HKEY_LOCAL_MACHINE\ SOFTWARE\Macromedia\ColdFusion\CurrentVersion\Clients.
Name of a data source configured in ColdFusion MX Administrator
Cookie

Generally, it is most efficient to store client variables in a database. Although the Registry option is the default, the Registry has significant limitations for client data storage. The Registry cannot be used in clustered systems and its use for client variables on UNIX is not supported in ColdFusion MX.

Using cookie storage

When you set the client storage method to 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. In particular, if the client turns off cookies in the browser, client variables do not work.

Consider the following additional limitations before implementing cookie storage for client variables:

Any Client variable that you set after a cfflush tag is not sent to the browser, so the variable value does not get saved.
Some browsers allow only 20 cookies to be set from a particular host. ColdFusion uses two of these cookies for the CFID and CFToken identifiers, and also creates a cookie named cfglobals to hold global data about the client, such as HitCount, TimeCreated, and LastVisit. This limits you to 17 unique applications per client-host pair.
Some browsers set a size limit of 4K bytes per cookie. ColdFusion encodes nonalphanumeric data in cookies with a URL encoding scheme that expands at a 3-1 ratio, which means you should not store large amounts of data per client. ColdFusion throws an error if you try to store more than 4,000 encoded bytes of data for a client.

Configuring database storage

When you specify a database for client variable storage, do not always have to manually create the data tables that store the client variables.

If ColdFusion can identify that the database you are using supports SQL creation of database tables, you only need to create the database in advance. When you click the Add button on the Select Data Source to Add as Client Store box on the Memory Variables page, the Administrator displays a Add/Edit Client Store page which contains a Create Client Database Tables selection box. Select this option to have ColdFusion create the necessary tables in your database. (The option does not appear if the database already has the required tables.)

If your database does not support SQL creation of tables, or if you are using the ODBC socket [Macromedia] driver to access your database, you must use your database tool to create the client variable tables. Create the CDATA and CGLOBAL tables.

The CDATA table must have the following columns:

Column	Data type
cfid	CHAR(64), TEXT, VARCHAR, or any data type capable of taking variable length strings up to 64 characters
app	CHAR(64), TEXT, VARCHAR, or any data type capable of taking variable length strings up to 64 characters
data	MEMO, LONGTEXT, LONG VARCHAR, CLOB, or any data type capable of taking long, indeterminate-length strings

The CGLOBAL table must have the following columns:

Column	Data type
cfid	CHAR(64), TEXT, VARCHAR, or any data type capable of taking variable length strings up to 64 characters
data	MEMO, LONGTEXT, LONG VARCHAR, CLOB, or any data type capable of taking long, indeterminate-length strings
lvisit	TIMESTAMP, DATETIME, DATE, or any data type that stores date and time values

Note: Different databases use different names for their data types. The names in the preceding tables are common, but your database might use other names.

To improve performance, you should also create indexes when you create these tables. For the CDATA table, index these cfid and app columns. For the CGLOBAL table, index the cfid column.

Specifying client variable storage in your application

The override the default client variable storage location, set the This.clientstorage variable in the Application.cfc initialization code, or use the cfapplication tag clientStorage attribute.

The following lines from an Application.cfc file tell ColdFusion to store the client variables in the mydatasource data source:

<cfscript>
   This.name"SearchApp";
   This.clientManagement="Yes";
   This.clientStorage="mydatasource";
</cfscript>

The following code from an Application.cfm file does the same thing as the previous example:

<cfapplication name"SearchApp" 
   clientmanagement="Yes"
   clientstorage="mydatasource">

View comments in LiveDocs