Tutorials: Cookies with JavaScript

What are Cookies?

The short answer is that cookies are a way of saving data in a web page that will last even after the viewer has moved to another page. This information is stored in the web browser, in such a way that your scripts will be able to read and write to it afterwards. It's like storing things to a local file on the user's computer, but only in a limited way, to prevent malicious web page designers from harming your computer. Because variables in Javascript cease to exist once you leave the page they are created on, Cookies provide you with a way to pass information from one page to another, as well as the ability to save information to determine whether or not a user has visited your site before, and information about what their preferences for viewing your site may be.

Cookies can be used by both Client Side scripting (JavaScript) and Server Side scripting (such as PHP). In both situations, the cookie is a piece of information which is stored by the web browser, locally on the viewer's computer - once the viewer has moved on to a different web site, the server no longer has access to the cookie, and JavaScript scripts run in the browser are also cut off from it. Regardless of whether it was set by a Server Side script, or a Client Side script, your cookie will only be accessible while viewing the website where it was created. (Thus, you can not use a cookie to pass information from your website on electron.cs.uwindsor.ca to another site on geocities.com.)

What can you put into a Cookie?

Cookies are designed to hold information as strings, so you can put any information that you are able to convert into a string into your cookie, with one exception. The value of your cookie can not contain the ';' character - the reason for this will be explained a bit more in the section about actually creating cookies, as well as the best way around the problem.

You can store up to 20 cookies for any individual web site. The combination of the domain in the URL (ie: electron.cs.uwindsor.ca), and the path in the URL (ie: /60-270/03W/userid/) is used to decide what can be considered as a single web site. Thus, your project can store up to 20 cookies, and the cookie set by the other projects in the class will not be counted against you, because they have a different path, and if you made a copy of your website on SOCR's web server, those cookies would also be stored separately due to having a different domain.

Inside of each cookie, you are allowed 4 KB of space. This means 4096 letters per cookie, which are divided up between the name of your cookie, the value of your cookie, and two special characters that separate the cookie from others that are being stored. Since you have 20 Cookies, and around 4Kb for each of them, this means that your website can store up to 80Kb of data - more than enough space to store a good sized essay in. (The largest file used in the class website is only 32Kb.)

How do I use a Cookie?

There are two ways to access a Cookie - from the server side, or a client side script - since this section of the class is about Client Side scripting, we will only be discussing how to access a cookie from inside JavaScript here. The Cookie itself is stored through the Document Object Model in a property called document.cookie - this special property holds all of the cookies assigned to your web site, with their names, and semi-colons between them. Thus, if you had three cookies, "c01","c02", and "that", and they each contained the word "boo", document.cookie would contain the following:

In each case, the cookie starts with it's name, which ends at the '=', and then the cookie's value begins, and ends at a ';' - thus, you can not put '=' in the name of your cookie, and you can not put ';' in it's value.

When you want to actually set a cookie however, you do not set all of the cookies at once - instead, you should set them one at a time, like this:

After running this set of statements, the contents of document.cookie will be changed to this:

The reason this works is because document.cookie is a special property which takes the values placed into it in a different manner than the data that is output. In each of these cases, we were creating new cookies, but you can also change the value in an old cookie, just by setting it again with the same name, but a different value, like this:

The altered document.cookie will now contain:

Since the ; character (and also the newline character) is not allowed in the value of a cookie, you must find some way around this problem - the solution is provided as a pair of builtin functions in JavaScript, called escape(), and unescape(). When you submit a form via the form tag, the data which is passed along is encoded so that all special characters are converted into a % and a hexidecimal number representing the ascii value of that character. The escape() function does the exact same thing, and unescape() will convert information back. If you run escape() on your cookie value before saving it, and unescape() on it when you read it back in, you'll have no problems with accidental illegal characters crashing your scripts.

The above will make document.cookie contain this:

Note that the spaces were all converted to %20 (20 is the Hex code for the space character in ascii), and the ; was converted to %3B. The only difficulty with this method is that it will result in your cookie becoming much longer if it contains a lot of space characters, since each one is converted into three characters instead of just one. Fortunately, you still have 4K to use, so most cookie values will not be affected by this.

Expiration Dates:

In the above examples, the only parts of the cookie that were set were the name and value - they are the only parts of a cookie which are absolutely required, but there are additional things about cookies which can also be set.

The cookies set above will exist only until the browser shuts down - if someone closes the program itself, and starts it up again, they will not be there anymore. The reason for this is because they were set only with their name and value - to make a cookie last past the next time you shut down the browser, you must also set what is called an expiry property on it, to tell the browser how long to keep the cookie. (This is much like the expiry date on a carton of milk - once it has gone by, the browser throws the cookie out.) To set an expiry date of November 15th, 2005 at 10:11 pm, you would use this command:

Reading back the contents of document.cookie will not include the expiry date however, as the browser considers the cookie's expiry date private, and will not share it with your script.

Obviously, this method is not optimal if you wish to make your cookie's expiration date dynamic, (ie: expire one year from the time it is set,) mainly because of the complexity of formatting the date string, and deciding which day of the week you should put it on. Fortunately, JavaScript provides an easy way around that - the Date object. To create a properly formated string with the date for one year from now, you merely need to create a Date object in JavaScript, set the date/time to the one you want, and convert it back into a string. In the following example, we do this to set the date to exactly one year from the current date:

The cookie stored with the name "name" will now last for exactly one year from the time when it was set. By the same method, we can force the browser to delete a cookie right now for us, by setting the cookie again, with an expiration date that is in the past:

The new 'old' expiry date will result in the browser throwing out the cookie.

Sharing your Cookie - PATH and DOMAIN:

Earlier, it was mentioned that your cookie would only be visible to web pages with the same domain and path as the page which created it, however it is possible to get around this limitation to some extent. When creating your cookie, much like the expiry property, you can also set a domain and/or path property, which can be used to share your cookie across other web sites. Remember when you do this however, that it is then very important to name your cookie something unique, as if some other website uses the same name as your cookie, there will be a chance of your data (or theirs) being lost, and harming the way your website works.

First, it is important to understand what the path and domain of a URL are. In the URL http://electron.cs.uwindsor.ca/60-270/03W/userid/myFile.html, the domain would be electron.cs.uwindsor.ca, and the path would be /60-270/03W/userid/. The domain is the name of the machine the web page is located on, and the path is the list of directory names in the URL. (Remember that the path does not include the filename, however.) Any time you create a cookie, and do not specify a path or a domain, they will default to the most specific possible value, which means the whole thing gets used, and only web pages with a domain and path which contains the entire domain and path on the cookie will be allowed to see the cookie.

Using the PATH property:

To share your cookie with pages in other directories on the machine it is on, you must force the path of the cookie to be less specific than it started out. If you set your path to just /60-270/03W/, instead of /60-270/03W/userid/, then all of the other projects in the class would also have access to it, and setting it to / would allow access to your cookie from all HTML files on the server electron.cs.uwindsor.ca. In small websites, this is rarely necesary, but as websites get larger, sometimes it is necesary to split your files up into separate directories, depending on what the content of those files may be. In those cases, if your cookie is being set from a page with the path /site/settings/, and you wanted all of the pages in /site/ to be able to see the cookie, you would need to add a path setting to your cookie to allow it, like this:

Note that the expiry date was left out of this setting - that is because it is optional for a cookie to have any of these parameters. Leaving out the expiry simply means that this cookie will expire when the browser next exits. The path setting in this case will allow your cookie to be viewed by any page in the /site/ directory, but not from the /other directory - to share with both of those, you would have to set your path to be just /. Remember when shortening your path, that it always starts comparing from the left side.

Using the DOMAIN property:

As web sites get larger and harder to manage, sometimes they get split up among multiple servers. One example would be the University of Windsor's web site, which forwards from www.uwindsor.ca to one of athena.uwindsor.ca, zeus.uwindsor.ca, venus.uwindsor.ca, and cronos.uwindsor.ca, to spread out the load among multiple servers. Also, sometimes a web site will decide to host content on one machine, forums on a different machine, and images on another, creating names like "www.cnn.com", "forums.cnn.com", and "images.cnn.com" to handle each - if they wish to be able to apply a cookie to be used by all three machines, they will have to force the domain property to be less specific - otherwise a cookie set on www.cnn.com would not be available on forums.cnn.com - to fix this, they would need to shorten their domain to just cnn.com. (The domain compares starting on the right side, because of the way domain names are built, with the general part at the end, and the specifics at the start.)

Again, only parameters that are needed are included here. The shortened domain cnn.com will match all of www.cnn.com, forums.cnn.com, and images.cnn.com, and any of those machines would then be able to use the cookie, as long as they had the right path. To allow any file on any of the machines to use the cookie, they would have to set bot the path and the domain, like this:

The last parameter: secure

There is one last parameter which can be set on a cookie - and it's one that you will rarely use, if ever, as it is designed to tell the cookie whether it is being used on a secure web server connection or not. (Secure connections are encrypted, and use https:// at the start of the URL instead of just http://.) If you set this property, it means that your cookie will only be viewed by pages from secure connections. If you do not set it, your cookie will only be viewed from pages without secure connections. Unlike all of the other properties, the secure property has no value assigned to it - if you include it at all, it would be done like this:

And after that, your cookie would only be avaliable if you're reading the web page through an https connection.

Properties on the cookie:

Here is a listing of all of the properties available to be set on a cookie, and how they would be set:

Note that this should be all in one string, on one line. Each of the sections of the cookie is separated by a semi-colon, and their purpose is as follows:

• cookieName: this is the name assigned to the cookie, and can allow you to pick out which specific cookie you are looking for, when you store more than one cookie for a web site. You can name your cookie anything that you can name a variable.
• cookieValue: this is the value assigned to the cookie. You can use this to store information in the cookie, to be used by other pages, or even by the same page on subsequent loadings. Between the name and value, you can use up to 4094 letters.
• expires: this is the date/time at which the cookie will expire. The formatting of the date string is very important, however, fortunately for us the Date() Object in JavaScript's output format is exactly what is needed. If the expires field is not set, the cookie will not be stored once the web browser shuts down. If it is set, then the cookie will be stored until the date it specifies.
• path: this is used to limit the directories on the host machine that can look at your cookie. Thus, you could set your cookie's path on a personal site to ~userid/ (assuming that was the path for your site), and then other people with sites on the same machine would not be able to see your cookie. The path will default to '/' (the root directory) if it is not set.
• domain: this allows you to specify how specific the domain requirement for the cookie being visible is - if it is set to uwindsor.ca, then a page on any machine who's domain ends with uwindsor.ca would be able to load your cookie. If you used something more specific, then you can limit it right down to a single machine. The domain defaults to the exact domain name in the browser's location bar if it is not set.
• secure: Generally, you would not include this parameter - it is only used to specify that a site must be secure to recieve the cookie. That means it would have to be encrypted through an ssl server, and loaded with the https protocol, instead of just plain old http.

Making things easier:

Since setting and reading cookies is a very complex task, a few functions have been made available to you which will deal with these parts for you. To include these functions in your website, all you need to do is include the following tag in the start of your web page's head area:

This will give you access to these three pre-made JavaScript functions: setCookie(), getCookie(), and delCookie(). Here are instructions on how to use each of them:

setCookie()

• Return value: This function does not return anything.
• Required parameters: a name and value for your cookie, like this:
  setCookie("food","potatoe");

  The setCookie function already runs the escape() function on your cookie's value, so you don't need to worry about stray ;'s in the value.

• Optional parameter: an expiry date for your cookie, as a JavaScript Date object, like this:
  var exp = new Date(); exp.setTime(exp.getTime() + 3600000); setCookie("keepme","for an hour", exp);

  The expiry date can be any valid date/time, but remember that if it's in the past, your cookie will be deleted immediately.

getCookie()

• Return value: The contents of your cookie, if it exists.
• Required Parameter: the name of the cookie you wish to read, like this:
  var whatever = getCookie("myCookie");

  The getCookie() function will then find the cookie you are looking for, and return it's value. If the cookie does not exist, it returns the null value.

delCookie()

• Return value: This function does not return anything.
• Required Parameter: the name of the cookie you wish to delete, like this:
  delCookie("myCookie");

  The delCookie() function will then set the expiry date of your cookie to a time in the past, which will cause the browser to delete it right away.

For those who wish to know, the source code for the above functions is as follows:

Examples of a cookie in use:

One example of a cookie in use would be the one used on the class website, which uses a cookie to store the viewer's prefered colour settings. To set the cookie, the viewer must go to the settings page, and select a theme from the box there. When they do, the setCookie function is run, to store their preference, and an expiry of one year from then is set, like this:

Now that the cookie has been set (or not), we can read the cookie in at the top of each page, and decide which stylesheet to apply to the page based on what it contains, like this:

This code has to be run in the head area of the document, because the tag output by the document.writeln statement belongs in the head area as well.