Scripting Cookies

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 creates a
index.html, but it is not visible to
/>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
and
/>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

ha
cookie is also visible to 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
. 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.