Chapter 16. Scripting Cookies The Document object contains a property named cookie that was not discussed in Chapter 14. On the surface, this property appears to be a simple string value; however, the cookie property controls a very important feature of the web browser and is important enough to warrant a complete chapter of its own. 16.1 An Overview of Cookies A cookie is a small amount of named data stored by the web browser and associated with a particular web page or web site. [1] Cookies serve to give the web browser a memory, so that scripts and server-side programs can use data that was input on one page in another page, or so the browser can recall user preferences or other state variables when the user leaves a page and then returns. Cookies were originally designed for CGI programming, and at the lowest level, they are implemented as an extension to the HTTP protocol. Cookie data is automatically transmitted between the web browser and web server, so CGI scripts on the server can read and write cookie values that are stored on the client. As we'll see, JavaScript can also manipulate cookies using the cookie property of the Document object. [1] The name "cookie" does not have a lot of significance, but it is not used without precedent. In the obscure annals of computing history, the term "cookie" or "magic cookie" has been used to refer to a small chunk of data, particularly a chunk of privileged or secret data, akin to a password, that proves identity or permits access. In JavaScript, cookies are used to save state and can serve to establish a kind of identity for a web browser. Cookies in JavaScript do not use any kind of cryptography, however, and are not secure in any way. e ent. You create, modify, or delete a cookie by setting the value of the cookie property. Later sections of this chapter explain in detail how this works. To er, you need to know more about cookies and cookie's lifetime. Cookies are transient by default -- the values they store last for the ie to last beyond a single browsing session, you use its expires attribute to a local e a coo . By default, a cookie is associated with, and accessible to, the web directories cookie is a string property that allows you to read, create, modify, and delete the cookie or cookies that apply to the current web page. Although cookie appears at first to be a normal read/write string property, its behavior is actually more complex. When you read the value of cooki , you get a string that contains the names and values of all the cookies that apply to the docum use the cookie property effectively, howev how they work. In addition to a name and a value, each cookie has four optional attributes that control its lifetime, visibility, and security. The first attribute is expires, which specifies the duration of the web-browser session but are lost when the user exits the browser. If you want a cook specify an expiration date -- this attribute causes the browser to save the cookie in file so that it can read it back in the next time the user visits the web page. Once th expiration date has passed, the cookie is automatically deleted from the cookie file. The second attribute of a cookie is path, which specifies the web pages with which kie is associated page that created it and any other web pages in the same directory or any sub of that directory. If the web page http://www.acme.com/catalog/index.html creates a index.html, but it is not visible to http://www.acme.com/about.html. ugh, you'll page ters his mailing address in a form on one e he returns to ere he is ookie. en, any web page from the same web server that contains that path in its URL can s its path set to "/catalog", that et to ver at order.acme.com may need to read cookie values set ere the third cookie attribute, domain, comes in. If a in , ibute is ult is the hostname of the web server that serves the page. Note that you cannot set the domain of a cookie to a domain other than the domain of ies which means that they are transmitted over a normal, insecure HTTP connection. If a en the browser and server are not Java- Script object properties. We'll see later in the chapter how you set these cookie atributes. spec.html cookie, for example, that cookie is also visible to http://www.acme.com/catalog/order.html and http://www.acme.com/catalog/widgets/ This default visibility behavior is often exactly what you want. Sometimes, tho want to use cookie values throughout a multipage web site, regardless of which creates the cookie. For instance, if the user en page, you may want to save that address to use as the default the next tim the page and also as the default in an entirely unrelated form on another page wh ed to enter a billing address. To allow this usage, you specify a path for the cask hT share the cookies. For example, if a cookie set by http://www.acme.com/catalog/widgets/index.html ha cookie is also visible to http://www.acme.com/catalog/order.html. Or, if the path is s "/", the cookie is visible to any page on the www.acme.com web server. By default, cookies are accessible only to pages on the same web server from which they were set. Large web sites may want cookies to be shared across multiple web servers, however. For example, the ser from catalog.acme.com. This is wh cookie created by a page on catalog.acme.com sets its path attribute to "/" and its doma attribute to ".acme.com", that cookie is available to all web pages on catalog.acme.com orders.acme.com, and any other server in the acme.com domain. If the domain attr not set for a cookie, the defa your server. The fourth and final cookie attribute is a boolean attribute named secure that specif how cookie values are transmitted over the network. By default, cookies are insecure, cookie is marked secure, however, it is transmitted only wh connected via HTTPS or another secure protocol. Note that the expires, path, domain, and secure attributes of a cookie are If you are interested in the complete technical details of how cookies work, see http://www.netscape.com/newsref/std/cookie_ . This document is the original cification for HTTP cookies; it contains low-level details that are more suitable to CGI programming than to JavaScript programming. The following sections discuss how and how you can specify the expires, spe you can set and query cookie values in JavaScript path, domain, and secure attributes of a cookie. 16.2 Storing Cookies To associate a transient cookie value with the current document, simply set the cookie The next time you read the property, the name/value pair you stored is includ e( ) ost s, ng the create a cookie that persists e code like this: var nextyear = new Date( ); nextyear.setFullYear(nextyear.getFullYear( ) + 1); document.lastModified + ); ie by appending e is written to the kie property: ; domain=domain To change the value of a cookie, set its value again, using the same name and the new n property to a string of the form: name=value For example: document.cookie = "version=" + escape(document.lastModified); cookie ed ent. Cookie values may not include semicolons, in the list of cookies for the docum commas, or whitespace. For this reason, you may want to use the JavaScript escap function to encode the value before storing it in the cookie. If you do this, you'll have to use the corresponding function when you read the cookie value.unescape( ) A cookie written as described above lasts for the current web-browsing session but is l when the user exits the browser. To create a cookie that can last across browser session include an expiration date by setting the expires attribute. You can do this by setti cookie property to a string of the form: name=value; expires=date When setting an expiration date like this, date should be a date specification in the e.toGMTString( ). For example, toformat written by Dat a year, you can usfor document.cookie = "version=" + "; expires=" + nextyear.toGMTString( Similarly, you can set the path, domain, and secure attributes of a cook strings of the following format to the cookie value before that valu coo ; path=path ; secure value. Use whatever values are appropriate for expires, path, and the other attributes. To delete a cookie, set it again using the same name, an arbitrary value, and an expiratio xpireddate that has already passed. Note that the browser is not required to delete e cookies immediately, so a cookie may remain in the browser's cookie file past its ons int uld e them in moderation. Web browsers are not required to retain more than 300 cookies te on the oward this 4- k trictive of these is the 20 cookies per server limit. In order to expiration date. 16.2.1 Cookie Limitati Cookies are intended for infrequent storage of small amounts of data. They are not ended as a general-purpose communication or data-transfer mechanism, so you sho us total, 20 cookies per web server (for the entire server, not just for your page or si server), or 4 kilobytes of data per cookie (both name and value count t ilobyte limit). The most res avoid reaching that limit, you may want to avoid using a separate cookie for each state variable you want to save. Instead, you can encode several related state variables into a single named cookie. Example 16-1, later in this chapter, shows one way that this can be alue it returns is a that apply to the current document. [2] done. 16.3 Reading Cookies When you use the cookie property in a JavaScript expression, the v string that contains all the cookies The string is a list of name=value pairs separated by semicolons, where name is the name of a cookie and tring value. This value does not include any of the attributes that may have he cookie. To determine the value of a particular named cookie, you can use the Strin and methods, or you can use okies. plorer 3, the cookie property works only for Document objects that were retrieved using the HTTP protocol. Documents retrieved from the local filesystem or via other protocols, such as FTP, cannot have cookies associated with them. Once you have extracted the value of a cookie from the cookie property, you must terpret that value based on whatever format or encoding was used by the cookie's creator. For example, the cookie might store multiple pieces of information in colon- parated fields. In this case, you would have to use appropriate string methods to extract the various fields of information. Don't forget to use the unescape( ) function on the ookie value if it was encoded using the escape( ) function. The following code shows how you might read the cookie property, extract a single cookie from it, and use the value of that cookie: // Read the cookie property. This returns all cookies for this document. var allcookies = document.cookie; // Look for the start of the cookie named "version" var pos = allcookies.indexOf("version="); // If we find a cookie by that name, extract and use its value if (pos != -1) { var start = pos + 8; // Start of cookie value value is its s een set for tb g.indexOf( ) String.substring( ) String.split( ) to break the string into individual co [2] In Internet Ex in se c var end = allcookies.indexOf(";", start); // End of cookie value if (end == -1) end = allcookies.length; var value = allcookies.substring(start, end); // Extract the value value = unescape(value); // Decode it // Now that we have the cookie value, we can use it. // In this case, the cookie was previously set to the modification // date of the document, so we can use it to see if the document has // changed since the user last visited. if (value != document.lastModified) alert("This document has changed since you were last here"); } Note that the string returned when you read the value of the cookie property does not contain any information about the various cookie attributes. The cookie property allows you to set those attributes, but it does not allow you to read them. 16.4 Cookie Example Example 16-1 brings together all the aspects of cookies we have discussed so far. First, the example defines a Cookie class. When you create a Cookie object, you specify a lly, an expiration time, a path, a e cookie should be secure. After three methods. The store( ) method loops through all of the user-defined properties of the Cookie object and concatenates their names and values into a single string that serves as the value of the cookie. The load( ) method of a Cookie object reads the cookie property of the Document object to obtain the values of all the cookies for the document. It searches this string to find the value of the named cookie and then parses this value into individual names and values, which it stores as properties of the Cookie object. Finally, the remove( ) method of the Cookie object deletes the specified cookie from the document. After defining the Cookie class, Example 16-1 Document object, a name for the cookie, and, optiona domain, and a boolean value that indicates whether th creating a Cookie object, you can set arbitrary string properties on this object; the values of these properties are the values stored in the cookie. The Cookie class defines demonstrates a useful and elegant way to use cookies. The code is somewhat complicated but is worth studying carefully. You may want to start with the test program at the end of the example; it shows a typical usage of the Cookie class. 16-1. A utility class for working with cookies a Cookie object for the specified , with a specified name and optional attributes. // Arguments: ch the cookie is stored. Example <script language="JavaScript1.1"> structor function: creates// The con nt// docume // document: The Document object for whi Required. // name: A string that specifies a name for the cookie. Required. s: An optional number that specifies the number of hours from now // after which the cookie should expire. h // domain: An optional string that specifies the cookie domain attribute. // secure: An optional boolean value that, if true, requests a secure cookie. // function Cookie(document, name, hours, path, domain, secure) { // All the predefined properties of this object begin with '$' // to distinguish them from other properties, which are the values to // be stored in the cookie this.$document = document; this.$name = name; if (hours) this.$expiration = new Date((new Date()).getTime( ) + hours*3600000); else this.$expiration = null; if (path) this.$path = path; else this.$path = null; if (domain) this.$domain = domain; else this.$domain = null; if (secure) this.$secure = true; else this.$secure = false; } of each state variable, in case it contains punctuation or other illegal characters. var cookieval = ""; for(var prop in this) { // Ignore properties with names that begin with '$' and also methods if ((prop.charAt(0) == '$') || ((typeof this[prop]) == 'function')) continue; if (cookieval != "") cookieval += '&'; cookieval += prop + ':' + escape(this[prop]); } // Now that we have the value of the cookie, put together the // complete cookie string, which includes the name and the various // attributes specified when the Cookie object was created cookie += '; expires=' + this.$expiration.toGMTString( ); if (this.$path) cookie += '; path=' + this.$path; if (this.$domain) cookie += '; domain=' + this.$domain; if (this.$secure) cookie += '; secure'; // hour // path: An optional string that specifies the cookie pat attribute. // This function is the store( ) method of the Cookie object Cookie.prototype.store = function ( ) { // First, loop through the properties of the Cookie object and // put together the value of the cookie. Since cookies use the // equals sign and semicolons as separators, we'll use colons // and ampersands for the individual state variables we store // within a single cookie value. Note that we escape the value // // var cookie = this.$name + '=' + cookieval; if (this.$expiration) // Now store the cookie by setting the magic Document.cookie property this.$document.cookie = cookie; } // This function is the load( ) method of the Cookie object Cookie.prototype.load = function( ) { // First, get a list of all cookies that pertain to this document // We do this by reading the magic Document.cookie property var allcookies = if (allcookies == "") return false; // Now extract just the named cookie from that list start = allco $name + '='); start == -1) eturn false; // Cookie not defi for this page tart += this.$na // Skip name and e ls sign ar end = allcook es.indexOf(';', start); if (end == -1) end = allcookies.length; okieval = a start, end); // Now that we've extracted the value of the named cookie, we st break tha ndividual state riable // other by ampersands, and the individual names and values are from the t( ) method // to parse everything. var a = cookieval.split('&'); // Break it into an array of value pairs for(var i=0; i < a.length; i++) // Break each pair into an array a[i] = a[i].split(':'); } // This function is the remove( ) method of the Cookie object ookie.prototype.remove = function( ) { var cookie; cookie = this.$name + '='; if (this.$path) cookie += '; path=' + this.$path; if (this.$domain) cookie += '; domain=' + this.$domain; cookie += '; expires=Fri, 02-Jan-1970 00:00:00 GMT'; this.$document.cookie = cookie; } this.$document.cookie; var if ( okies.indexOf(this. r ned s v me.length + 1; qua i var co llcookies.substring( // mu // names and values. The name/value pairs are separated from each t value down into i va // separated each other by colons. We use spli name/ // Now that we've parsed the cookie value, set all the names and values // of the state variables in this Cookie object. Note that we unescape( ) // the property value, because we called escape( ) when we stored it. for(var i = 0; i < a.length; i++) { this[a[i][0]] = unescape(a[i][1]); } // We're done, so return the success code return true; C //=================================================================== // The previous code is the definition of the Cookie class. // The following code is a sample use of that class. //=================================================================== // Create the cookie we'll use to save state for this web page. // Since we're using the default path, this cookie will be accessible // to all web pages in the same directory as this file or "below" it. // Therefore, it should have a name that is unique among those pages. // Note that we set the expiration to 10 days in the future. var visitordata = new Cookie(document, "name_color_count_state", 240); // First, try to read data stored in the cookie. If the cookie is not // defined, or if it doesn't contain the data we need, then query the // user for that data. if (!visitordata.load( ) || !visitordata.name || !visitordata.color) { visitordata.name = prompt("What is your name:", ""); visitordata.color = prompt("What is your favorite color:", ""); } // Keep track of how many times this user has visited the page: if (visitordata.visits == null) visitordata.visits = 0; visitordata.visits++; // Store the cookie values, even if they were already stored, so that the // expiration date will be reset to 10 days from this most recent visit. // Also, store them again to save the updated visits state variable. visitordata.store( ); // Now we can use the state variables we read: document.write('<font size="7" color="' + visitordata.color + '">' + <input type="button" value="Forget My Name" onclick="visitordata.remove( );"> </form> 'Welcome, ' + visitordata.name + '!' + '</font>' + '<p>You have visited ' + visitordata.visits + ' times.'); </script> <form> . than 300 cookies te on the oward this 4- k trictive of these is the 20 cookies per server limit. In order to expiration date. 16.2.1 Cookie Limitati Cookies. returns all cookies for this document. var allcookies = document.cookie; // Look for the start of the cookie named "version" var pos = allcookies.indexOf("version=");