Class lw.Cookie

Object
   |
   +--lw.Cookie

class lw.Cookie

Some Cookie background information:

• Each cookie has a name.
  The name must obey the JavaScript name syntax.
• Each cookie has a value.
  The value may be empty, and must not include semicolons, commas, or whitespace.
  Consequence: the value must be encoded and decoded.
  Most applications (including the lw.Cookie library) use the JavaScript escape() function for this.
• When setting a cookie (name + value), there are optional attributes:
  • expires: An expiration date, that specifies the cookie's lifetime.
    Default (no expiration specified) is "transient": The cookie is not saved to disk, but is lost, when the user exits the browser.
    To delete a cookie: specify a date in the past.
  • path: Specifies the web pages with which the cookie is associated (the "visibility").
    Default (no path specified): The cookie is associated with and accessible to the web page that created it, and any other web pages in the same directory or any subdirectory.
    Visibility may be enlarged by setting a higher level subdirectory of this server, up to the root: "/".
  • domain: Specifies the visibility by other servers in the same domain.
    Default (no domain specified): The cookie is accessible only to pages on the same web server.
    Visibility may be enlarged to more servers by specifying the domain.
  • secure: If a cookie is marked "secure", it is transmitted only over HTTPS connections.
  Note: The browser will not show any of these attributes when retrieving the cookie(s).
• Retrieving a cookie is performed on a per document base. This means: You cannot directly retrieve just one cookie "by name"; the browser always returns all cookies allowed for the given document.
  Consequence: the cookies returned by the browser must be parsed into cookie name and cookie value.
• Cookie access may be disabled in the browser (for this site, or for all sites). For this situation there will be no explicit error indicators, but the browser will silently ignore the Cookie calls (Cookie retrieval will return an empty String, just as if no Cookie was avail).

• 300 cookies total.
  Consequence: the browser may remove (or even not store) the cookie without notice
• 20 cookies per web server (for the entire server, not just for one page or site).
  Consequence: do not use one cookie per value you want to save (i.e. per variable, state..), but save more than one value "packed" into a single cookie.
  Most applications (including the lw.Cookie library) use the "URL-form-encoding scheme" for this.
• 4 kB of data per cookie (including name and value)
  Consequence: Cookies are not suitable for high volume data storage.

• With lw.Cookie.load(), all cookies visible to the browser document are retrieved, and parsed into cookie names and values; each cookie value is "unpacked" into it's name/value pairs.
  The call returns an object that contains each cookie as a separate property (with the cookie's name).
  The value of each cookie name property is an object again, containing all the name/value pairs as properties that were packed into the cookie.
• With lw.Cookie.store(obj, name), the specified object is saved as a Cookie with the specified name. All it's properties (except functions) are converted to Strings and "packed" as name/value pairs into this Cookie.
• With lw.Cookie.remove(name), the Cookie with the specified name is removed.
• Optional arguments to these calls support the optional Cookie attributes.

// Load all cookies that are visible for this web page.
var cookies = lw.Cookie.load();		// may return an empty object: { }

// Since we're using the default path, our cookie will be accessible
// to all web pages in the same directory as this file or "below" it.
// Therefore, it choose a cookie name that is unique among those pages:
// "visitor_name_count".
var visitor = cookies.visitor_name_count;	// may be null

// First, try to read data stored in the cookie.
// If the cookie is not defined,
// or if it doesn't contain the data we need,
// then query the user for that data.
if (!visitor) { visitor = { }; }
if (!visitor.name) {
	visitor.name = prompt("What is your name:", "");
	visitor.visits = 0;
}

// Keep track of how many times this user has visited the page:
visitor.visits++;

// Store our cookie values, even if they were already stored:
// we want to reset the expiration date to 10 days from this most recent visit,
// and we want to save the updated visits state variable.
lw.Cookie.store(visitor, "visitor_name_count", 10 * 24)

// Now we can use the state variables of our cookie:
alert('Welcome, ' + visitor.name + '!' +
			   'You have visited this site ' + visitor.visits + ' times.');

// to remove the cookie on user's choice,
// you could define an event handler for a HTML button, such as
// onclick="lw.Cookie.remove('visitor_name_count')"
 

Constructor Detail

lw.Cookie

lw.Cookie()

Declares the lw.Cookie library. No initialization required.

get

<static> string get(<document> document)

Loads all cookie(s) for the specified document as a string.

Parameters:
document - optional: the document of the cookie; if missing: loads the cookie(s) for the default window.document.

Returns:
string containing all cookie(s) as specified by document.cookie or empty string if no Cookies are found, or if Cookie access is disabled in the browser.

load

<static> Object load(<document> document)

Loads all cookie(s) for the specified document into an object. The properties of the returned object are the cookie names. The value of each cookie is an object again, containing the name/values pairs of the cookie as properties.

Parameters:
document - optional: the document of the cookie; if missing: loads the cookie(s) for the default window.document.

Returns:
new Object containing all cookie(s), or empty Object if no Cookies are found, or if Cookie access is disabled in the browser. The properties of the returned Object are the Cookie names. The value of each Cookie is a sub-object, with the Cookie name/value pairs accessible via the sub-object properties.

remove

<static> void remove(<String> name, <Document> doc, <String> path, <String> domain)

Removes the Cookie from the browser. Note: If Cookie access is disabled in the browser, the Cookie will not be removed, without notice.

Parameters:
name - required: The cookie name; unique for the document.
doc - optional: The Document object containing the cookie; if misssing: the default window.document.
path - optional: The cookie path attribute; if missing: visible for all pages in the document's directory and all subdirectories.
domain - optional: The cookie domain attribute; if missing: visible for the current server only.

set

<static> void set(<String> name, <String> value, <int> hours, <Document> document, <String> path, <String> domain, <boolean> secure)

Stores a Cookie. Note: If Cookie access is disabled in the browser, the Cookie will not be stored, without notice.

Parameters:
name - required: The cookie name; unique for the document.
value - required: The cookie value
hours - optional: The number of hours from now that the cookie should expire; if missing: 0 (transient: the cookie will not be written to disk; it will be removed when the browser is closed).
document - optional: The Document object that the cookie is stored for; if misssing: the default window.document.
path - optional: The cookie path attribute; if missing: visible for all pages in the document's directory and all subdirectories.
domain - optional: The cookie domain attribute; if missing: visible for the current server only.
secure - optional: If true, requests a secure cookie; if missing: false (does not require HTTPS).

store

<static> void store(<Object> obj, <String> name, <int> hours, <Document> doc, <String> path, <String> domain, <boolean> secure)

Stores a property of an object as a Cookie. Note: If Cookie access is disabled in the browser, the Cookie will not be stored, without notice.
Note: 2008-04-24/jf Problem with Workbench-BuiltIn-Tomcat
1. we save a Cookie for URL "http://jf-xp:8084/ajax3/login/xxx" (no doc, path, domain specified) and FF shows Cookie path property "/" (we expected: "/ajax3/login/")
2. if we explicitly specify path="/ajax3/login/": FF shows Cookie path property as expected, but we cannot load it (!!)

Parameters:
obj - required: the object to be stored as cookie
name - required: The cookie name; unique for the document.
hours - optional: The number of hours from now that the cookie should expire; if missing: 0 (transient: the cookie will not be written to disk; it will be removed when the browser is closed).
doc - optional: The Document object that the cookie is stored for; if misssing: the default window.document.
path - optional: The cookie path attribute; if missing: visible for all pages in the document's directory and all subdirectories.
domain - optional: The cookie domain attribute; if missing: visible for the current server only.
secure - optional: If true, requests a secure cookie; if missing: false (does not require HTTPS).