Cookie Example: Part II -- Creating the Cookie

It takes two to tango, and similarly, it takes two scripts to set the cookie. We've seen how to retrieve the cookie data and incorporate its values into some HTML output. But how do we create this cookie in the first place?

Trouble is, a cookie must be set before any HTML is output to a page; this is because creating a cookie outputs a special header to the browser. Once that header has been output, only HTML can follow. When the user submits their request via the search form, the submission is sent to another CGI processing script, which we've called dosearch.cgi. Were this a real search engine, we can imagine that dosearch.cgi performs the database lookups required of the search and outputs the results to the browser.

That said, the beginning of dosearch.cgi provides the perfect opportunity to set the cookie -- the script knows the settings of the form fields, since that data is part of the submission. So, we can simply graft some code onto the beginning of dosearch.cgi which sets the cookie and then proceeds with its search engine duties.

Once again, you may wish to follow along with a pop-up window of the entire dosearch.cgi script. You can also view a live example of the entire set of cookie CGI scripts we've seen in action.

#set cookie for search
#/usr/local/bin/perl

use CGI;
$cgiobject=new CGI;
$cgiobject->use_named_parameters;

Once again, we begin by preparing the CGI environment for this Perl script.

&get_state_variables;
$cookie_data=&prepare_cookie;
&set_cookie($cookie_data);
&performSearch;

The main statements of dosearch.cgi call a sequence of subroutines. First, we'll retrieve the state of the form fields in get_state_variables; then, we'll pack that data into a cookie chunk in prepare_cookie, and finally set that cookie on the visitor's machine via set_cookie. Lastly, we branch off to the rest of the fictitious dosearch.cgi script triggered from performSearch.

sub get_state_variables()
 #retrieve from the CGI queries the keys and value 
 #we want to store in the cookie
 { $search_term=$cgiobject->param("search_term");
   $result_style=$cgiobject->param("result_style");
   $result_perpage=$cgiobject->param("result_perpage");
 }

When the visitor submits the search form, the chosen settings are supplied with the submission. In get_state_variables we capture these settings, using the param method of the CGI object, and assign the values to appropriately named variables. Next, we'll use the values of these variables to create the cookie data.

sub prepare_cookie()
 #packages the variables into one data string for storage in cookie
 { $cookie_data="search_term=$search_term|".
                "result_style=$result_style|".
                "result_perpage=$result_perpage";
   return $cookie_data;
 }

Here a string is built, $cookie_data, which contains the variables and values in the chosen format described earlier. Of course, the structure of this cookie data is entirely arbitrary -- we chose this format simply because it is easy to illustrate and easy for the crumble_cookie subroutine to parse. It would have also been possible, rather than pack three sets of variables and values into one cookie, to set three cookies, each named after the variable in question (in other words, cookies named "search_term", "result_style", and "result_perpage"). In turn, drawform.cgi would retrieve the values of the three cookies without having to parse their contents. However, we've chosen to use only one cookie to both illustrate a means to pack several pieces of data into one cookie chunk and because, in the realm of public perception, it is considered "nicer" to set fewer cookies rather than more.

sub set_cookie($cookie_data)
 #sets cookie on user's machine
 { $final_cookie=$cgiobject->cookie(-name=>'searchform',
                              -value=>$cookie_data,
                              -expires=>'+6M');
   print $cgiobject->header(-cookie=>$final_cookie);
 }

The heart of this script, set_cookie takes the string of data packed into $cookie_data and creates the cookie on the visitor's machine, in two steps. First, we use the cookie method of the CGI object to build the whole cookie, which is assigned to $final_cookie. This method takes several parameters: here, we've provided a name for the cookie ("searchform"), the cookie's data ($cookie_data), and an expiration period (6 months). You may set an expiration period to any length of time you wish, and setting an expiration date prior to the current date causes that cookie to automatically expire (effectively deleting the cookie immediately). Lastly, the cookie is sent to the page as an HTTP header via the header method of the CGI object. Note also that sending this header prepares the browser to start receiving HTML output, which we can do from this point on. The CGI.pm home page describes the format for setting an expiration date as well as additional information on setting cookies in general.

sub performSearch()
 { print $cgiobject->
   start_html(-title=>'Search results',-bgcolor=>'white');
   print "blah blah blah"
   # ... rest of dosearch Perl code ... #
 }

After the cookie has been created, we simply branch into the actual body of the fictitious dosearch.cgi script; the above example simply illustrates that we can begin outputting an HTML document followed by the search engine code, were it for real.

Cookie Example: Part I -- Retrieving the Cookie
The Perl You Need to Know
Final Cookie Thoughts