Jim's JavaScript Cookie Library

This page demonstrates and documents the JavaScript Cookie Libary, cookies.js, written by Jim Auldridge.
This page and all code within, either directly or by reference, is copyright © Jim Auldridge 2005-2008. All rights reserved.

This component, known as "Jim's JavaScript Cookie Library", has been released as open source under a BSD license and is free for all uses personal, commercial, for-profit, not-for-profit, or any other purpose you can think of.

Version
Change Log
How To
Demo
Code

Version 1.3

Change Log:

02 NOV 2005 - Version 1 written
20 APR 2006 - Version 1.1
- Added to jimAuld namespace
- Added method to test browser for cookie acceptance
09 Jul 2006 - Version 1.2
- Fixed bug in cookie expiration (changed expire to expires) Thanks to Dustin Diaz (http://www.dustindiaz.com) for discovering it.
- Shortened object and method names to ease development and remove redundancy
29 AUG 2006 - Placed under BSD license
06 SEP 2006 - Clarified commenting in reference to the hoursToLive argument
24 Nov 2007 - Version 1.3
- Cleaned up some syntax and variable use, and adjusted ternary structures.

How To:

Basics and Name Spacing

After following the instructions below to insert the cookie handling library into your page, four methods will be available to you: get(), set(), del(), and test(). These methods do exactly what you expect they would do: get a cookie, write/overwrite a cookie, delete a cookie, and test if the browser accepts cookies (respectively). The library exists under a namespace I have created in order to help you avoid conflicts in the global namespace. My namespace is jimAuld and within that namespace is a namespace name utils This is where the cookie library resides as cookies. So all of the 4 methods belong to jimAuld.utils.cookies making the methods accessible as: jimAuld.utils.cookies.get()
jimAuld.utils.cookies.set()
jimAuld.utils.cookies.del()
jimAuld.utils.cookies.test()
You could shorten this up by assigning a shortcut to the library:
var c = jimAuld.utils.cookies;
c.get();
However, you should use this carefully as it does somewhat defeat the purpose of name-spacing.

Methods

get()

The get() method takes one parameter, cookieName, which is a string and the name of the cookie whose value is desired. It will return null if the cookie is not set or has an empty value.
var myVar = jimAuld.utils.cookies.get('myCookie');

set()

The set() method takes up to six parameters. The first parameter, cookieName, is a string and names the cookie to be written. The second parameter, value is also a string and is the value to be written to the named cookie. The third parameter, hoursToLive, is the first of the optional parameters and should be a numeric value stating how long the cookie should be good for (used in calculating the expiration date). Passing 0 or leaving this value empty results in the cookie only being good ntil the user closes their browser. A negative value relt in the cookie being deleted, thouh it is preferable to use the del() method for deleting cookies.
...To Be Continued...

Demo:

The purpose of this page is to demonstrate the uses and functionality of the cookie library. Below these paragraphs you will see a set of buttons. By clicking on these buttons, you manipulate a cookie by the name of 'test'. This is all done with the methods of the cookies object that is created in cookies.js.

Suggested flow of testing is as follows:

Click "Test Cookie Acceptance" to test the browsers ability to accept cookies.

Click "Show cookie value" To show the cookie is currently not available.

Click "Set the cookie"

Click "Show cookie value" To show the cookie is now set.

Click "Delete the cookie"

Click "Show cookie value" To show the cookie is, again, not available.

(Step 1)

(Steps 2,4,6)

(Step 3) (Step 5)

Code

Below is the code that builds the object and its methods. The code sample is heavily commented for your learning purposes.

To use this code, place it in the HEAD element of your web page. Or download cookies.js (or the minimal version or the highly commented version) and place it on your server, then reference it from the HEAD element of your page as so:
<script type="text/javascript" src="cookies.js"></script>
(with the src attribute modified to match the version you downloaded)

Contents of cookies.js

/* Copyright (c) 2005, James Auldridge All rights reserved. Code licensed under the BSD License: http://www.jaaulde.com/license.php Version 1.3 Change Log: * 02 NOV 2005 - Version 1 written * 20 APR 2006 - Version 1.1 o Added to jimAuld namespace o Added method to test browser for cookie acceptance * 09 JUL 2006 - Version 1.2 o Fixed bug in cookie expiration (changed expire to expires) Thanks to Dustin Diaz (http://www.dustindiaz.com) for discovering it. o Shortened object and method names to ease development and remove redundancy * 29 AUG 2006 - Placed under BSD license * 06 SEP 2006 - Clarified commenting in reference to the hoursToLive argument * 24 Nov 2007 - Cleaned up some syntax, etc */ //Preparing namespace var jimAuld = window.jimAuld || {}; jimAuld.utils = jimAuld.utils || {}; /* * This library is a member of the jimAuld.utils namespace * The libary is useful for cookie interaction with JavaScript * There are 4 methods in the cookies library, each of which is documented separately below * */ jimAuld.utils.cookies = { /* METHOD: get(); * PURPOSE: Get the value of a cookie * ARGUMENTS: STRING - cookieName - The name of the cookie value you wish to retrieve * RETURN: If cookie exists - STRING - the cookie value * If cookie does not exist - null */ get: function(cookieName) { var cookieNameStart,valueStart,valueEnd,cookieValue,returnValue; cookieNameStart = document.cookie.indexOf(cookieName+'='); if (cookieNameStart < 0) { returnValue = null; } else { valueStart = document.cookie.indexOf(cookieName+'=') + cookieName.length + 1; valueEnd = document.cookie.indexOf(";",valueStart); if (valueEnd == -1) { valueEnd = document.cookie.length; } cookieValue = document.cookie.substring(valueStart,valueEnd ); returnValue = (cookieValue == '') ? null : unescape(cookieValue); } return returnValue; }, /* METHOD: set(); * PURPOSE: Write (or overwrite) a cookie (with supplemental information such as expiration, path, domain) * ARGUMENTS: cookieName - STRING - The name of the cookie value you wish to write * value - STRING - The string you wish to write as the value of the cookie * hoursToLive - INT/FLOAT - The number of hours until the cookie will expire. If you do not provide * this argument, or provide anything that can evaluate to false, or provide * anything that can not be interpreted as a number, the expiration field for * the cookie will not be set causing it to be deleted the next time the * browser is closed (IE referes to this sort of cookie as a 'session' cookie). * path - STRING - (Optional) The path for which the cookie is valid. Defaults to "/" if not * passed, or passed empty. * domain - STRING - (Optional) The domain for which the cookie is valid. Defaults to * window.location.hostname if not passed, or passed empty. * secure - BOOL - (Optional) This is used to instruct the browser to use SSL when sending the * cookie to a server. It is almost never used, and will thus be assumed false * unless you explicitly pass true. * RETURN: VOID */ set: function(cookieName,value,hoursToLive,path,domain,secure) { var expireString,timerObj,expireAt,pathString,domainString,secureString; //If no hoursToLive argument, or it is not numeric, do not set expiration if (!hoursToLive || typeof hoursToLive != 'number') { expireString = ''; } else { timerObj = new Date(); timerObj.setTime(timerObj.getTime()+(hoursToLive*60*60*1000)); expireAt = timerObj.toGMTString(); expireString = '; expires='+expireAt; } //If no path argument, or argument is empty string, set path to default of / path = (!path || path=='' || path==null) ? '/' : path; pathString = '; path='+path; //If no domain argument, or argument is empty string, set domain to default of window.location.hostname domain = (!domain || domain=='' || domain==null) ? window.location.hostname : domain; domainString = '; domain='+domain; //If secure argument is the BOOL true, set SSL string accordingly. Otherwise, do not set it. secureString = (secure === true) ? '; secure' : ''; //escape the value for HTTP transport to server value = escape(value); //Write the value to the document.cookie string document.cookie = cookieName+'='+value+expireString+pathString+domainString; }, /* METHOD: del(); * PURPOSE: Delete a cookie * ARGUMENTS: STRING - cookieName - The name of the cookie value you wish to delete * path - STRING - (Optional) The path for which the cookie was set. This is necessary if * the cookie was set with a particular path--you need to delete it with the * same. Defaults to "/" if not passed, or passed empty. * domain - STRING - (Optional) The domain for which the cookie was set. This is necessary if * the cookie was set with a particular domain--you need to delete it with the * same. Defaults to window.location.hostname if not passed, or passed empty. * RETURN: VOID */ del: function(cookieName,path,domain) { path = (!path || !path.length) ? '' : path; domain = (!domain || !domain.length) ? '' : domain; jimAuld.utils.cookies.set(cookieName,'',-8760,path,domain); }, /* METHOD: test(); * PURPOSE: Test for cookie acceptance * ARGUMENTS: VOID * RETURN: If cookies accepted: BOOL - True * If cookies not accepted: BOOL - False */ test: function() { var returnValue; jimAuld.utils.cookies.set('cT','acc'); var runTest = jimAuld.utils.cookies.get('cT'); if (runTest == 'acc') { jimAuld.utils.cookies.del('cT'); returnValue = true; } else { returnValue = false; } return returnValue; } };

Jim's JavaScript Cookie Library

Content Menu:

Version 1.3

Change Log:

How To:

Basics and Name Spacing

Methods

get()

set()

Demo:

Code

Contents of cookies.js