- HTTP.Cookies-1.11
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; } /* */