DP_Cookies

The DP_Cookies script creates a global object which provides the developer with simple, abstracted client-side management of browser cookies.

  • The script supports the original cookie specification which is in common use.
  • The object provides methods to get, set and erase (delete) cookies by name.
  • The object provides methods to erase or return (as a JavaScript object) all available cookies as a set.

The extension is self-contained and presents an extremely small footprint. Only a single global object, “DP_Cookies”, is created.

This component requires a JavaScript (ECMAScript) 1.3 (or better) environment and has been tested successfully on Internet Explorer 6+, Firefox 1+ and Opera 9+.

Download

The component is available from GitHub:

All downloads and code are covered by our Source Code Policy.

Usage

The script consists of a single JavaScript file with a .JS extension.

Importing the Library

The library must be imported before it is used. To import the library use the <script> tag. For example:

<script type="text/javascript" src="DP_Cookies.js"></script>

Your path may vary depending on the location of the script on your server.

Accessing the Object

Importing the script automatically creates a new, global JavaScript object called “DP_Cookies“. To use a method of the object call it directly:

var myCookies = DP_Cookies.getAll();

See the Examples section for some sample code.

Properties and Methods

The DP_Cookies object contains no properties.

DP_Cookies methods available:

Note that in method/function signatures a pipe (“|”) indicates “OR” while arguments in square brackets are optional.

enabled()

A convienence method which determines, using the navigator.cookieEnabled property, whether or not cookies are enabled in the environment. This method will fail in environments which do not support the navigator object.

Method Signature

enabled()

Arguments

This method has no arguments.

Return

Boolean. True if cookies are enabled, false if not.

erase()

Eliminates (erases/deletes) a cookie by setting its expiration date to a past date.

Method Signature

erase(Name)

Arguments

This method has one argument:

  • Name: String, Required. The name of the cookie to erase.

Return

Boolean. True.

eraseAll()

Eliminates (erases/deletes) all cookies (only currently accessible cookies, determined by the security rules of the environment, will be erased).

Method Signature

eraseAll()

Arguments

This method has no arguments.

Return

Boolean. True.

get()

Gets the value of a specific cookie by name.

Method Signature

get(Name)

Arguments

This method has one argument:

  • Name: String, Required. The name of the cookie to get.

Return

String or null. The text content (value) of the specified cookie or, if the cookie is empty, the empty string. If the cookie does not exist null will be returned.

getAll()

Gets all available cookies. Can be used to examine or iterate over cookies and is useful for debugging purposes.

Method Signature

getAll()

Arguments

This method has no arguments.

Return

Object. An object where each property=value corresponds to the name=value of available cookies. An empty object will be returned if there are no cookies available.

set()

Sets the value of a cookie, creating it if neccessary.

Method Signature

set(Name[, Value][, Timespan][, TimespanUnit][, Domain][, Path][, Secure])

Arguments

This method has seven arguments:

  • Name: String, required. The name of the cookie to set.
  • Value: String or null, optional. The text content to be stored in the cookie. If null or excluded the cookie will be set to an empty string.
  • Timespan: Numeric or null, optional. The number of time units (determined by the TimespanUnit argument) after which the cookie will expire (be automatically deleted). If null or excluded no expiration date will be set: the cookie will then be a session cookie and be automatically deleted at the end of the browser session.
  • TimespanUnit: String, optional. Acceptable values are “days”, “hours, “minutes”, “seconds”. Defaults to “days”. The time unit to apply to the Timespan argument. Ignored if Timespan is null.
  • Domain: String, optional. The domain for which the cookie is valid. See the Netscape cookie specification for more detailed information.
  • Path: String, optional. The path for which the cookie is valid assuming it passed domain matching. See the Netscape cookie specification for more detailed information.
  • Secure: Boolean. Defaults to “false”. If true the cookie will only be transmitted when the communication channel is considered “secure” (on the web this generally means an HTTPS channel). If false the cookie will always be transmitted.

Return

String. The text representation of the cookie as defined.

Examples

As noted the script must be imported (<script type=”text/javascript” src=”DP_Cookies.js”></script>). Once the script has been imported the DP_Cookies object is ready for use.

Determining if Cookies are Enabled

Use the enabled() method to determine if cookies are currently enabled. The method returns a boolean and so can be used as an expression:

	if ( DP_Cookies.enabled() ) {
		DP_Cookies.set("MyCookie", "MyValue", 30);
	} else {
		... Code to handle case where cookies are not enabled ...
	};
	

Setting Session Cookies

Session Cookies are cookies which lack an expiration date. They will be erased automatically at the end of the current browser session (or, in other environments, when the application closes).

To create a cookie or change its value use the set() method. To set a simple cookie with no value do this:

DP_Cookies.set("MyCookie");

To include a value add it as a second argument:

DP_Cookies.set("MyCookie", "MyValue");

Setting Persistent Cookies

To create cookies which can persist past the current session include the Timespan and (optionally) the TimespanUnit arguments. TimespanUnit defaults to “days” so to set a cookie which will last 30 days simply do:

DP_Cookies.set("MyCookie", "MyValue", 30);

To set a persistent cookie with no value either make the value null or an empty string:

DP_Cookies.set("MyCookie", "", 30);

The TimespanUnit argument allows you to decide whether the timespan is represented in days (the default), hours, minutes or seconds. To set the cookie for 30 minutes do:

DP_Cookies.set("MyCookie", "MyValue", 30, "minutes");

Getting the Value of Cookies

Cookies can be retrieved using the get() method:

var MyCookieValue = DP_Cookies.get("MyCookie");

The new variable “MyCookieValue” would then contain the value of the “MyCookie” cookie. If the cookie requested doesn’t exist the value returned would be null.

In addition you may retrieve all currently available cookies using the getAll() method:

var AllCookies = DP_Cookies.getAll();

The new variable “AllCookies” would then contain an object whose properties corresponded to the available cookies and their values. You might then write the name and value of the available cookies like so:

	for ( var Cookie in AllCookies ) {
		document.writeln("name = " + Cookie + "; value = " + CookieAllCookies[Cookie]);
	};
	

It’s important to remember that the getAll() method is a “snapshot” view. The object returned is a copy of the cookies available at that moment and will not be automatically updated with subsequent changes.

Erasing Cookies

Cookies are easily erased using the erase() method. To erase the cookie we set above just specify the name like so:

DP_Cookies.erase("MyCookie");

To erase all cookies currently available use the eraseAll() method:

DP_Cookies.eraseAll();

Revision History

June 8, 2013

  • Initial GITHUB release.

July 01, 2006

  • Initial Release
Advertisements
%d bloggers like this: