Cookie (Advice)

A means of maintaining state in the client machine by storing information in a cookie that is associated with the document.

A cookie is a small fragment of textual data that is associated with the current page. It is not modeled particularly well for access by JavaScript and you will need to use some scripting to disassemble and reassemble the name-value pairs that are concatenated together to make the cookie.

The cookie property for a document returns a string containing ALL the cookies that apply to the document. You will need to split them into individual cookies by separating them at semicolon boundaries. From there you will need to obtain for each cookie a name=value construct that you can further dismantle and process.

Note that you will not get any of the special attributes of the cookie since they are write only. The only thing you can get back is its value property.

When you read the cookie property from a document, you get a list of cookie values, one for each cookie. When you assign to the cookie property of a document, you define only a single cookie whose name is the first name-value pair in the string. Other attributes are appended by concatenation and delimited from one another by a semicolon. The other attributes are optional and all that is required is the new cookie name and value pair.

You must make sure the cookie value you assign is properly URL escaped so that it can be sent back to the server when necessary.

Cookie values should be defined as a series of name=value pairs. As well as the fundamental cookie value, you can define the following name=value pairs:

Cookies can be redefined whenever you want. To delete a cookie, set it to some value with an expiry date defined to be prior to the current date and time.

Cookies are useful but you should not rely on them 100%. It is possible that the user may have disabled cookie support in their browser. You should also avoid storing sensitive information in a cookie and it is intended that the value you store there is small. Storing huge amounts of data in a cookie is somewhat bad etiquette.

The example code demonstrates how two functions (setCookie and getCookie) can be created to simplify the creation and parsing of cookies. The comments in the example explain how they work.

Warnings:

Example code:

   // Example provided by Martin Honnen
   // A function that sets cookie values properly
   // The cookieName and cookieValue arguments are mandatory
   // but all other arguments are optional.
   // The expires argument is a Date object.
   // The path defines the part of the document tree on the server
   // that the cookie is valid for.
   // The domain argument allows multiple server hosts to be used.
   // The secure value is boolean and only applicable for use
   // with HTTPS: connections.
   function setCookie(cookieName, cookieValue, expires, path, domain, secure)
   {
      document.cookie = escape(cookieName) + '=' + escape(cookieValue)
         + (expires ? '; EXPIRES=' + expires.toGMTString() : '')
         + (path ? '; PATH=' + path : '')
         + (domain ? '; DOMAIN=' + domain : '')
         + (secure ? '; SECURE' : '');
   }
   
   // A complementary function to unwrap a cookie.
   function getCookie(cookieName)
   {
      var cookieValue = null;
      var posName = document.cookie.indexOf(escape(cookieName) + '=');
   
      if (posName != -1)
      {
         var posValue = posName + (escape(cookieName) + '=').length;
         var endPos = document.cookie.indexOf(';', posValue)&;
         if (endPos != -1)
         {
            cookieValue = unescape(document.cookie.substring(posValue, endPos));
         }
         else
         {
            cookieValue = unescape(document.cookie.substring(posValue));
         }
      }
      return cookieValue;
   }
   
   // Tryout 1: Set a session cookie which expires after
   //           the browser is closed
   setCookie ('TRYOUT', '1');
   
   // Tryout 2: Set a cookie which expires after 24 hours
   var now = new Date();
   var tomorrow = new Date(now.getTime() + 1000 * 60 * 60 * 24);
   setCookie ('TRYOUT', '2', tomorrow);
   
   // Tryout 3: Set a cookie with a path
   setCookie ('TRYOUT', '3', null, '/');
   
   // Tryout 4: Delete a cookie by setting its expiry date to
   //           be sometime in the past
   var now = new Date();
   var yesterday = new Date(now.getTime() - 1000 * 60 * 60 * 24);
   setCookie('TRYOUT', '4', yesterday);

See also:Document.cookie

Web-references:

http://www.netscape.com/newsref/std/cookie_spec.html