- HTTP.Cookies-1.11

Documentation | Source

NAME

HTTP.Cookies - JavaScript class for reading, writing and deleting cookies

SYNOPSIS

   var cookie    = new HTTP.Cookies;
   var password  = cookie.read('password');
   var lastvisit = cookie.read('lastvisit');
   cookie.write( 'lastvisit', 1079383075, '+1y' );
   cookie.remove( 'password' );

DESCRIPTION

HTTP.Cookies is a class for http cookies manipulation. It defines three object methods to read, write and remove cookies. Implementation is somehow similar to the Perl module CGI.pm' s cookie() method.

There is an internal cache system for fast access. But the cache will be reset if you alter (write() or remove()) cookies. So, you can use the same HTTP.Cookies object anywhere in the page.

METHODS

read NAME

Reads the cookie named name and returns it's value or an empty string upon failure.

write NAME, VALUE [, EXPIRES, PATH, DOMAIN, SECURE]

Creates a new cookie with NAME and VALUE. NAME can include non-alphanumeric characters, but you are discouraged to use such cookie names.

Optional EXPIRES value sets the cookie lifetime.

Expire date format: you can use negative or positive numbers combined with s, m, h, d, w, M, y or you can use now to expire as soon as possible. Meanings:

    s   = second
    m   = minute
    h   = hour
    d   = day
    w   = week
    M   = month
    y   = year
    now = immediately

For a session cookie; pass "-1" as the expires value.

Example:

   cookie.write('mycookie', 'testing', '+1h');

mycookie will expire in one hour.

Optional parameter PATH can be used to define the path for which the HTTP cookie is valid.

Optional parameter DOMAIN can be used to define the domain for which the HTTP cookie is valid.

Optional parameter SECURE can be used to make it a secure cookie. Secure cookies can only be used with HTTPS protocol. They'll be invisible under HTTP protocol.

remove NAME [, PATH, DOMAIN, SECURE]

Deletes/removes the named cookie from the client. See write for the meaning of the parameters.

obliterate

Will remove/delete any accessible cookie.

names

Returns an array consisting of available cookies' names:

   document.write( "Available Cookie names are ", cookie.names().join(', ') );

ERROR HANDLING

Methods will return null if an error occurs. But the error can also be diplayed in a message box if the error level is not altered.

HTTP.Cookies.ERRORLEVEL

If set to 1 (default value), then fatal errors will be displayed in a message box. Any other value will silence the errors.

CAVEATS

Under NS 4.x and MSIE, when you delete the cookies, their names may not be deleted. The value of the cookie will be erased (will return undefined), but you may need to close the browser window to erase the cookie completely. I'm not sure if there is a workaround for IE. And I haven't tested this with IE7 yet.

BUGS

Contact the author if you find any.

This library is tested under Windows XP Professional SP2 with:

  • Opera 9.10
  • Microsoft Internet Explorer 6.0
  • Netscape Communicator 4.77
  • Mozilla 1.7.8
  • Mozilla FireFox 2.0.0.1

AUTHOR

Burak Gürsoy, <burak@cpan.org>

COPYRIGHT

Copyright 2005-2007 Burak Gürsoy. All rights reserved.

LICENSE

This library is free software; you can redistribute it and/or modify it under the terms of the "Artistic License": http://dev.perl.org/licenses/artistic.html.

// HTTP.Cookies by Burak G�rsoy <burak[at]cpan[dot]org>
if (!HTTP) var HTTP = {};

HTTP.Cookies = function () {
   this._reset();
}

// expire time calculation
HTTP.Cookies.Date = function () {
   this._init();
}

HTTP.Cookies.VERSION     = '1.11';
HTTP.Cookies.ERRORLEVEL  = 1;
HTTP.Cookies.Date.FORMAT = {
   's' :  1,
   'm' : 60,
   'h' : 60 * 60,
   'd' : 60 * 60 * 24,
   'M' : 60 * 60 * 24 * 30,
   'y' : 60 * 60 * 24 * 365
};

HTTP.Cookies.prototype._reset = function () {
   this['JAR']     = ''; // data cache
   this['CHANGED'] =  0; // cookies altered?
}

// Get the value of the named cookie. Usage: password = cookie.read('password');
HTTP.Cookies.prototype.read = function (name) {
	if(!name) return this._fatal('read', 'Cookie name is missing');
   if(this.CHANGED) this._reset();
   // first populate the internal cache, then return the named cookie
   var value = '';
   this._parse();
   for ( var cookie in this.JAR ) {
      if ( cookie == name ) {
         value = this.JAR[cookie];
         break;
      }
	}
   return value ? value : '';
}

// Create a new cookie or overwrite existing.
// Usage: cookie.write('password', 'secret', '1m');
HTTP.Cookies.prototype.write = function (name, value, expires, path, domain, secure) {
	if(!name) return this._fatal('write', 'Cookie name is missing');
	if(typeof value == 'undefined') value = ''; // workaround
   if (!expires) expires = '';
   if (expires == '_epoch') {
      expires = new Date(0);
   }
   else if (expires != -1) {
      var cdate = new HTTP.Cookies.Date;
      var Now   = new Date;
      Now.setTime(Now.getTime() + cdate.parse(expires));
      expires = Now.toGMTString();
   }
   var extra = '';
   if(expires) extra += '; expires=' + expires;
   if(path   ) extra += '; path='    + path;
   if(domain ) extra += '; domain='  + domain;
   if(secure ) extra += '; secure='  + secure;
   // name can be non-alphanumeric
   var new_cookie  = escape(name) + '=' + escape(value) + extra;
   document.cookie = new_cookie;
   this.CHANGED    = 1; // reset the object in the next call to read()
}

// Delete the named cookie. Usage: cookie.remove('password');
HTTP.Cookies.prototype.remove = function (name, path, domain, secure) {
	if(!name) return this._fatal('remove', 'Cookie name is missing');
   this.write(name, '', '_epoch', path, domain, secure);
}

// cookie.obliterate()
HTTP.Cookies.prototype.obliterate = function () {
   var names = this.names();
   for ( var i = 0; i < names.length; i++ ) {
		if ( !names[i] ) continue;
      this.remove( names[i] );
	}
}

// var cnames = cookie.names()
HTTP.Cookies.prototype.names = function () {
   this._parse();
   var names = [];
   for ( var cookie in this.JAR ) {
		if ( !cookie ) continue;
      names.push(cookie);
	}
	return names;
}

HTTP.Cookies.prototype._parse = function () {
   if(this.JAR) return;
	this.JAR  = {};
   var NAME  = 0; // field id
   var VALUE = 1; // field id
   var array = document.cookie.split(';');
   for ( var element = 0; element < array.length; element++ ) {
      var pair = array[element].split('=');
      pair[NAME] = pair[NAME].replace(/^\s+/, '');
      pair[NAME] = pair[NAME].replace(/\s+$/, '');
      // populate
      this.JAR[ unescape(pair[NAME]) ] = unescape( pair[VALUE] );
   }
}

HTTP.Cookies.prototype._fatal = function (caller, error) {
   var title = 'HTTP.Cookies fatal error';
   switch(HTTP.Cookies.ERRORLEVEL) {
      case 1:
         alert( title + "\n\n"  + caller + ': ' + error );
         break;
      default:
         break;
   }
}

HTTP.Cookies.Date.prototype._fatal = function (caller, error) {
   var title = "HTTP.Cookies.Date fatal error";
   switch(HTTP.Cookies.ERRORLEVEL) {
      case 1:
         alert( title + "\n\n"  + caller + ': ' + error );
         break;
      default:
         break;
   }
}

// HTTP.Cookies.Date Section begins here

HTTP.Cookies.Date.prototype._init = function () {
   this.FORMAT = HTTP.Cookies.Date.FORMAT;
}

HTTP.Cookies.Date.prototype.parse = function (x) {
   if(!x || x == 'now') return 0;
   var NUMBER = 1;
   var LETTER = 2;
   var date = x.match(/^(.+?)(\w)$/i);

   if ( !date ) {
		return this._fatal(
			       'parse',
			       'expires parameter (' + x + ') is not valid'
			    );
	}

   var is_num = this.is_num(  date[NUMBER] );
   var of     = this.is_date( date[NUMBER], date[LETTER] );
   return (is_num && of) ? of : 0;
}

HTTP.Cookies.Date.prototype.is_date = function (num, x) {
   if (!x || x.length != 1) return 0;
   var ar = [];
   return (ar = x.match(/^(s|m|h|d|w|M|y)$/) ) ? num * 1000 * this.FORMAT[ ar[0] ] : 0;
}

HTTP.Cookies.Date.prototype.is_num = function (x) {
   if (x.length == 0) return;
   var ok = 1;
   for (var i = 0; i < x.length; i++) {
      if ( "0123456789.-+".indexOf( x.charAt(i) ) == -1 ) {
         ok--;
         break;
      }
   }
   return ok;
}

/*

*/