Using Client Variables to Preserve Data Through Multiple User Visits

< Day Day Up >

Consider an application in which you allow the user to customize some of the display patterns to his or her liking. For example, a user can build his or her own custom portal page by defining a background color, font color, and font style; then each time that user returns to your site, the information is preserved. ColdFusion's' client variables make this possible. By using client variables, you can allow the user to custom-define background and font parameters that exist every time a user visits your site.

The first time he or she visits, ColdFusion automatically sets a cookie on the user's machine containing the cfid/cftoken autogenerated for that particular user. This creates a drawer for the user, into which you can place any variables you'd like. These variables will until the user deletes the cookie.

Enabling client variables in Application.cfm

To use client variables, you need to "turn them on" by including some text in your Application.cfm file. Take a look at Listing 52-2.

Listing 52-2: Application.cfm

<cfapplication name="portal_site" clientmanagement="yes">     <!---define default values for colors and font face. These will be used  throughout the site until the user defines his or her preferences---> <cfparam name="client.bgcolor" default="##FFFFFF"> <cfparam name="client.fontface" default="Arial"> <cfparam name="client.fontcolor" default="##000000">

The listing adds clientmanagment="yes" to the <cfapplication> tag, which is all that's required to enable client variables.

Note

Remember that this Application.cfm page applies to all templates in the current directory, and all folders within it that don't contain their own Application.cfm page.

The listing next uses <cfparam> to define three default values for background color, font face, and font color. These variables use the special scope client to signify that they will be persistent client variables that "live" indefinitely and are associated with a specific user. You use any variable names you like, as long as they use the client scope. At this point you're just defining default values — in a moment you'll learn how to allow the user to change these values. Note that an extra hash mark is used before the hex color values to let ColdFusion know that the hash mark should be interpreted as a literal rather than part of a variable name.

Note

Client variables are designed to hold string values rather than complex variables like structures and arrays. You'll learn more about the latter in Chapter 54.

Creating a preference selection form

After the variables are defined, you can use them the same way you would any ColdFusion variable. In this example, you'll need to plug them into your templates' <body> and <font> tags, as shown in Listing 52-3. Figure 52-1 shows the form as it appears in the user's browser.

Listing 52-3: customize_form.cfm

 <html> <head> <title>Customize Your Page</title> <meta http-equiv="Content-Type" content="text/html; charset=iso- 8859-1"> </head>     <cfoutput> <body bgcolor="#client.bgcolor#">     <h2><font face="#client.fontface#" color="#client.fontcolor#">Customize  Your Page</font></h2>     <p><font face="#client.fontface#" color="#client.fontcolor#">Choose  from the values below to customize your viewing experience on our  site.</font></p>     <form action="customize_action.cfm" method="post">      <p><font face="#client.fontface#"  color="#client.fontcolor#">Choose a Background Color:</font>      <select name="bgcolor">           <option value="##FFFFFF">white</option>           <option value="##FFFF00">yellow</option>           <option value="##00FFFF">cyan</option>       </select></p>            <p><font face="#client.fontface#"  color="#client.fontcolor#">Choose a Font Face</font>      <select name="fontface">           <option>Arial</option>           <option>Times New Roman</option>           <option>Courier</option>      </select></p>            <p><font face="#client.fontface#"  color="#client.fontcolor#">Choose a Font Color:</font>      <select name="fontcolor">           <option value="##000000">black</option>           <option value="##FF0000">red</option>           <option value="##008080">teal</option>       </select></p>            <input type="submit">     </form>     </body> </cfoutput>     </html>

click to expand
Figure 52-1: Collecting user preferences with a form

This listing is a form that allows the user to choose custom values for page parameters. We'll discuss the form itself for a moment, but let's first concentrate on the <body> and <font> tags used throughout the page. Note that the entire body section is enclosed in a pair of <cfoutput> tags, allowing you to display the contents of ColdFusion variables throughout the body of the page. The variable #client.bgcolor# is inserted into the <body> tag where you'd usually supply a hex value, #client.fontface# goes in the <font> tag where you'd usually supply a font face, and so on.

Now, take a look at the form elements in Listing 52-3. This form allows the users to select a background color, font face, and font color to customize their experience. As you've probably guessed, the action page you'll create next uses the user's selections to redefine the values of client.bgcolor, client.fontface, and client.fontcolor.

Note

Notice that the color values in the form in Listing 52-3 use an extra hash mark (#). Remember that all literal hash marks used within <cfoutput> tags need to be preceded by an extra hash mark so that ColdFusion doesn't attempt to interpret the surrounding text as a variable name. A user who makes a selection and submits the form is taken to the action page shown in Listing 52-4.

Setting client variables on an action page

Listing 52-4 shows the action page for the form created in the previous section. It uses <cfset> to assign the user's color and font face selections to the three client variables. When this template is executed, the new variable values overwrite the default values supplied in Application.cfm, and the variables remain in that state until the user either changes them again, or deletes the cookies from his or her system.

Listing 52-4: customize_action.cfm

<!---set client variables based on user preferences passed by form---> <cfset client.bgcolor = form.bgcolor> <cfset client.fontface = form.fontface> <cfset client.fontcolor = form.fontcolor>     <html> <head> <title>Customization Complete</title> <meta http-equiv="Content-Type" content="text/html; charset=iso- 8859-1"> </head>     <!---show results to user, using user's specified font face and color  preferences---> <cfoutput> <body bgcolor="#client.bgcolor#"> <h2><font face="#client.fontface#"  color="#client.fontcolor#">Customization Complete</font></h2>     <p><font face="#client.fontface#"  color="#client.fontcolor#">Your  settings have been saved and will be preserved when you next visit our  site.</font></p>     </body> </cfoutput> </html>

These variables persist the next time the user visits your site. Note that you could extend the user's preferences throughout an application by inserting the client.bgcolor, client. fontface, and client.fontcolor variables anywhere you'd normally use a static bgcolor, font face, or font color value. One possible result of this action page is shown in Figure 52-2.

click to expand
Figure 52-2: The result of a preference change; note that a user's preferences are saved between visits.

Tip

When you use client variables, ColdFusion saves the user's cfide/cftoken identifier as a cookie on the user's system. But the contents of the users "drawer" — the client variables created by your templates — are stored in the ColdFusion server's registry by default. ColdFusion also enables you to store this information in a database, which is the preferable method if your application makes extensive use of client variables. See your ColdFusion documentation for more on this subject.

< Day Day Up >