[Summary view] [Print] [Text view]

   1  YUI.add('yui2-cookie', function(Y) {
   2      var YAHOO    = Y.YUI2;
   3      /*
   4  Copyright (c) 2011, Yahoo! Inc. All rights reserved.
   5  Code licensed under the BSD License:
   6  http://developer.yahoo.com/yui/license.html
   7  version: 2.9.0
   8  */
   9  /**
  10   * Utilities for cookie management
  11   * @namespace YAHOO.util
  12   * @module cookie
  13   */
  14  YAHOO.namespace("util");
  15  
  16  /**
  17   * Cookie utility.
  18   * @class Cookie
  19   * @static
  20   */
  21  YAHOO.util.Cookie = {
  22      
  23      //-------------------------------------------------------------------------
  24      // Private Methods
  25      //-------------------------------------------------------------------------
  26      
  27      /**
  28       * Creates a cookie string that can be assigned into document.cookie.
  29       * @param {String} name The name of the cookie.
  30       * @param {String} value The value of the cookie.
  31       * @param {Boolean} encodeValue True to encode the value, false to leave as-is.
  32       * @param {Object} options (Optional) Options for the cookie.
  33       * @return {String} The formatted cookie string.
  34       * @method _createCookieString
  35       * @private
  36       * @static
  37       */
  38      _createCookieString : function (name /*:String*/, value /*:Variant*/, encodeValue /*:Boolean*/, options /*:Object*/) /*:String*/ {
  39          
  40          //shortcut
  41          var lang = YAHOO.lang,
  42              text = encodeURIComponent(name) + "=" + (encodeValue ? encodeURIComponent(value) : value);
  43          
  44          
  45          if (lang.isObject(options)){
  46              //expiration date
  47              if (options.expires instanceof Date){
  48                  text += "; expires=" + options.expires.toUTCString();
  49              }
  50              
  51              //path
  52              if (lang.isString(options.path) && options.path !== ""){
  53                  text += "; path=" + options.path;
  54              }
  55              
  56              //domain
  57              if (lang.isString(options.domain) && options.domain !== ""){
  58                  text += "; domain=" + options.domain;
  59              }
  60              
  61              //secure
  62              if (options.secure === true){
  63                  text += "; secure";
  64              }
  65          }
  66          
  67          return text;
  68      },
  69      
  70      /**
  71       * Formats a cookie value for an object containing multiple values.
  72       * @param {Object} hash An object of key-value pairs to create a string for.
  73       * @return {String} A string suitable for use as a cookie value.
  74       * @method _createCookieHashString
  75       * @private
  76       * @static
  77       */
  78      _createCookieHashString : function (hash /*:Object*/) /*:String*/ {
  79          
  80          //shortcuts
  81          var lang = YAHOO.lang;
  82          
  83          if (!lang.isObject(hash)){
  84              throw new TypeError("Cookie._createCookieHashString(): Argument must be an object.");
  85          }
  86          
  87          var text /*:Array*/ = [];
  88          
  89          for (var key in hash){
  90              if (lang.hasOwnProperty(hash, key) && !lang.isFunction(hash[key]) && !lang.isUndefined(hash[key])){
  91                  text.push(encodeURIComponent(key) + "=" + encodeURIComponent(String(hash[key])));
  92              }
  93          }
  94          
  95          return text.join("&");
  96      },
  97      
  98      /**
  99       * Parses a cookie hash string into an object.
 100       * @param {String} text The cookie hash string to parse. The string should already be URL-decoded.
 101       * @return {Object} An object containing entries for each cookie value.
 102       * @method _parseCookieHash
 103       * @private
 104       * @static
 105       */
 106      _parseCookieHash : function (text /*:String*/) /*:Object*/ {
 107          
 108          var hashParts /*:Array*/ = text.split("&"),
 109              hashPart /*:Array*/ = null,
 110              hash /*:Object*/ = {};
 111          
 112          if (text.length > 0){
 113              for (var i=0, len=hashParts.length; i < len; i++){
 114                  hashPart = hashParts[i].split("=");
 115                  hash[decodeURIComponent(hashPart[0])] = decodeURIComponent(hashPart[1]);
 116              }
 117          }
 118          
 119          return hash;
 120      },
 121      
 122      /**
 123       * Parses a cookie string into an object representing all accessible cookies.
 124       * @param {String} text The cookie string to parse.
 125       * @param {Boolean} decode (Optional) Indicates if the cookie values should be decoded or not. Default is true.
 126       * @return {Object} An object containing entries for each accessible cookie.
 127       * @method _parseCookieString
 128       * @private
 129       * @static
 130       */
 131      _parseCookieString : function (text /*:String*/, decode /*:Boolean*/) /*:Object*/ {
 132          
 133          var cookies /*:Object*/ = {};
 134          
 135          if (YAHOO.lang.isString(text) && text.length > 0) {
 136              
 137              var decodeValue = (decode === false ? function(s){return s;} : decodeURIComponent);
 138              
 139              //if (/[^=]+=[^=;]?(?:; [^=]+=[^=]?)?/.test(text)){
 140                  var cookieParts /*:Array*/ = text.split(/;\s/g),
 141                      cookieName /*:String*/ = null,
 142                      cookieValue /*:String*/ = null,
 143                      cookieNameValue /*:Array*/ = null;
 144                  
 145                  for (var i=0, len=cookieParts.length; i < len; i++){
 146                      
 147                      //check for normally-formatted cookie (name-value)
 148                      cookieNameValue = cookieParts[i].match(/([^=]+)=/i);
 149                      if (cookieNameValue instanceof Array){
 150                          try {
 151                              cookieName = decodeURIComponent(cookieNameValue[1]);
 152                              cookieValue = decodeValue(cookieParts[i].substring(cookieNameValue[1].length+1));
 153                          } catch (ex){
 154                              //ignore the entire cookie - encoding is likely invalid
 155                          }
 156                      } else {
 157                          //means the cookie does not have an "=", so treat it as a boolean flag
 158                          cookieName = decodeURIComponent(cookieParts[i]);
 159                          cookieValue = "";
 160                      }
 161                      cookies[cookieName] = cookieValue;
 162                  }
 163              //}
 164          }
 165          
 166          return cookies;
 167      },
 168      
 169      //-------------------------------------------------------------------------
 170      // Public Methods
 171      //-------------------------------------------------------------------------
 172      
 173      /**
 174       * Determines if the cookie with the given name exists. This is useful for
 175       * Boolean cookies (those that do not follow the name=value convention).
 176       * @param {String} name The name of the cookie to check.
 177       * @return {Boolean} True if the cookie exists, false if not.
 178       * @method exists
 179       * @static
 180       */
 181      exists: function(name) {
 182  
 183          if (!YAHOO.lang.isString(name) || name === ""){
 184              throw new TypeError("Cookie.exists(): Cookie name must be a non-empty string.");
 185          }
 186  
 187          var cookies /*:Object*/ = this._parseCookieString(document.cookie, true);
 188          
 189          return cookies.hasOwnProperty(name);
 190      },
 191      
 192      /**
 193       * Returns the cookie value for the given name.
 194       * @param {String} name The name of the cookie to retrieve.
 195       * @param {Object|Function} options (Optional) An object containing one or more
 196       *      cookie options: raw (true/false) and converter (a function).
 197       *      The converter function is run on the value before returning it. The
 198       *      function is not used if the cookie doesn't exist. The function can be
 199       *      passed instead of the options object for backwards compatibility.
 200       * @return {Variant} If no converter is specified, returns a string or null if
 201       *      the cookie doesn't exist. If the converter is specified, returns the value
 202       *      returned from the converter or null if the cookie doesn't exist.
 203       * @method get
 204       * @static
 205       */
 206      get : function (name /*:String*/, options /*:Variant*/) /*:Variant*/{
 207          
 208          var lang = YAHOO.lang,
 209              converter;
 210          
 211          if (lang.isFunction(options)) {
 212              converter = options;
 213              options = {};
 214          } else if (lang.isObject(options)) {
 215              converter = options.converter;
 216          } else {
 217              options = {};
 218          }
 219          
 220          var cookies /*:Object*/ = this._parseCookieString(document.cookie, !options.raw);
 221          
 222          if (!lang.isString(name) || name === ""){
 223              throw new TypeError("Cookie.get(): Cookie name must be a non-empty string.");
 224          }
 225          
 226          if (lang.isUndefined(cookies[name])) {
 227              return null;
 228          }
 229          
 230          if (!lang.isFunction(converter)){
 231              return cookies[name];
 232          } else {
 233              return converter(cookies[name]);
 234          }
 235      },
 236      
 237      /**
 238       * Returns the value of a subcookie.
 239       * @param {String} name The name of the cookie to retrieve.
 240       * @param {String} subName The name of the subcookie to retrieve.
 241       * @param {Function} converter (Optional) A function to run on the value before returning
 242       *      it. The function is not used if the cookie doesn't exist.
 243       * @return {Variant} If the cookie doesn't exist, null is returned. If the subcookie
 244       *      doesn't exist, null if also returned. If no converter is specified and the
 245       *      subcookie exists, a string is returned. If a converter is specified and the
 246       *      subcookie exists, the value returned from the converter is returned.
 247       * @method getSub
 248       * @static
 249       */
 250      getSub : function (name, subName, converter) {
 251          
 252          var lang = YAHOO.lang,
 253              hash = this.getSubs(name);
 254          
 255          if (hash !== null) {
 256              
 257              if (!lang.isString(subName) || subName === ""){
 258                  throw new TypeError("Cookie.getSub(): Subcookie name must be a non-empty string.");
 259              }
 260              
 261              if (lang.isUndefined(hash[subName])){
 262                  return null;
 263              }
 264              
 265              if (!lang.isFunction(converter)){
 266                  return hash[subName];
 267              } else {
 268                  return converter(hash[subName]);
 269              }
 270          } else {
 271              return null;
 272          }
 273      
 274      },
 275      
 276      /**
 277       * Returns an object containing name-value pairs stored in the cookie with the given name.
 278       * @param {String} name The name of the cookie to retrieve.
 279       * @return {Object} An object of name-value pairs if the cookie with the given name
 280       *      exists, null if it does not.
 281       * @method getSubs
 282       * @static
 283       */
 284      getSubs : function (name /*:String*/) /*:Object*/ {
 285      
 286          var isString = YAHOO.lang.isString;
 287          
 288          //check cookie name
 289          if (!isString(name) || name === ""){
 290              throw new TypeError("Cookie.getSubs(): Cookie name must be a non-empty string.");
 291          }
 292          
 293          var cookies = this._parseCookieString(document.cookie, false);
 294          if (isString(cookies[name])){
 295              return this._parseCookieHash(cookies[name]);
 296          }
 297          return null;
 298      },
 299      
 300      /**
 301       * Removes a cookie from the machine by setting its expiration date to
 302       * sometime in the past.
 303       * @param {String} name The name of the cookie to remove.
 304       * @param {Object} options (Optional) An object containing one or more
 305       *      cookie options: path (a string), domain (a string),
 306       *      and secure (true/false). The expires option will be overwritten
 307       *      by the method.
 308       * @return {String} The created cookie string.
 309       * @method remove
 310       * @static
 311       */
 312      remove : function (name /*:String*/, options /*:Object*/) /*:String*/ {
 313          
 314          //check cookie name
 315          if (!YAHOO.lang.isString(name) || name === ""){
 316              throw new TypeError("Cookie.remove(): Cookie name must be a non-empty string.");
 317          }
 318          
 319          //set options - clone options so the original isn't affected
 320          options = YAHOO.lang.merge(options || {}, {
 321              expires: new Date(0)
 322          });
 323          
 324          //set cookie
 325          return this.set(name, "", options);
 326      },
 327      
 328      /**
 329       * Removes a subcookie with a given name. Removing the last subcookie
 330       *      won't remove the entire cookie unless options.removeIfEmpty is true.
 331       * @param {String} name The name of the cookie in which the subcookie exists.
 332       * @param {String} subName The name of the subcookie to remove.
 333       * @param {Object} options (Optional) An object containing one or more
 334       *      cookie options: path (a string), domain (a string), expires (a Date object),
 335       *      removeIfEmpty (true/false), and secure (true/false). This must be the same
 336       *      settings as the original subcookie.
 337       * @return {String} The created cookie string.
 338       * @method removeSub
 339       * @static
 340       */
 341      removeSub : function(name /*:String*/, subName /*:String*/, options /*:Object*/) /*:String*/ {
 342          
 343          var lang = YAHOO.lang;
 344          
 345          options = options || {};
 346          
 347          //check cookie name
 348          if (!lang.isString(name) || name === ""){
 349              throw new TypeError("Cookie.removeSub(): Cookie name must be a non-empty string.");
 350          }
 351          
 352          //check subcookie name
 353          if (!lang.isString(subName) || subName === ""){
 354              throw new TypeError("Cookie.removeSub(): Subcookie name must be a non-empty string.");
 355          }
 356          
 357          //get all subcookies for this cookie
 358          var subs = this.getSubs(name);
 359          
 360          //delete the indicated subcookie
 361          if (lang.isObject(subs) && lang.hasOwnProperty(subs, subName)){
 362              delete subs[subName];
 363  
 364              if (!options.removeIfEmpty) {
 365                  //reset the cookie
 366  
 367                  return this.setSubs(name, subs, options);
 368              } else {
 369                  //reset the cookie if there are subcookies left, else remove
 370                  for (var key in subs){
 371                      if (lang.hasOwnProperty(subs, key) && !lang.isFunction(subs[key]) && !lang.isUndefined(subs[key])){
 372                          return this.setSubs(name, subs, options);
 373                      }
 374                  }
 375                  
 376                  return this.remove(name, options);
 377              }
 378          } else {
 379              return "";
 380          }
 381          
 382      },
 383      
 384      /**
 385       * Sets a cookie with a given name and value.
 386       * @param {String} name The name of the cookie to set.
 387       * @param {Variant} value The value to set for the cookie.
 388       * @param {Object} options (Optional) An object containing one or more
 389       *      cookie options: path (a string), domain (a string), expires (a Date object),
 390       *      raw (true/false), and secure (true/false).
 391       * @return {String} The created cookie string.
 392       * @method set
 393       * @static
 394       */
 395      set : function (name /*:String*/, value /*:Variant*/, options /*:Object*/) /*:String*/ {
 396          
 397          var lang = YAHOO.lang;
 398          
 399          options = options || {};
 400          
 401          if (!lang.isString(name)){
 402              throw new TypeError("Cookie.set(): Cookie name must be a string.");
 403          }
 404          
 405          if (lang.isUndefined(value)){
 406              throw new TypeError("Cookie.set(): Value cannot be undefined.");
 407          }
 408          
 409          var text /*:String*/ = this._createCookieString(name, value, !options.raw, options);
 410          document.cookie = text;
 411          return text;
 412      },
 413      
 414      /**
 415       * Sets a sub cookie with a given name to a particular value.
 416       * @param {String} name The name of the cookie to set.
 417       * @param {String} subName The name of the subcookie to set.
 418       * @param {Variant} value The value to set.
 419       * @param {Object} options (Optional) An object containing one or more
 420       *      cookie options: path (a string), domain (a string), expires (a Date object),
 421       *      and secure (true/false).
 422       * @return {String} The created cookie string.
 423       * @method setSub
 424       * @static
 425       */
 426      setSub : function (name /*:String*/, subName /*:String*/, value /*:Variant*/, options /*:Object*/) /*:String*/ {
 427          
 428          var lang = YAHOO.lang;
 429          
 430          if (!lang.isString(name) || name === ""){
 431              throw new TypeError("Cookie.setSub(): Cookie name must be a non-empty string.");
 432          }
 433          
 434          if (!lang.isString(subName) || subName === ""){
 435              throw new TypeError("Cookie.setSub(): Subcookie name must be a non-empty string.");
 436          }
 437          
 438          if (lang.isUndefined(value)){
 439              throw new TypeError("Cookie.setSub(): Subcookie value cannot be undefined.");
 440          }
 441          
 442          var hash /*:Object*/ = this.getSubs(name);
 443          
 444          if (!lang.isObject(hash)){
 445              hash = {};
 446          }
 447          
 448          hash[subName] = value;
 449          
 450          return this.setSubs(name, hash, options);
 451          
 452      },
 453      
 454      /**
 455       * Sets a cookie with a given name to contain a hash of name-value pairs.
 456       * @param {String} name The name of the cookie to set.
 457       * @param {Object} value An object containing name-value pairs.
 458       * @param {Object} options (Optional) An object containing one or more
 459       *      cookie options: path (a string), domain (a string), expires (a Date object),
 460       *      and secure (true/false).
 461       * @return {String} The created cookie string.
 462       * @method setSubs
 463       * @static
 464       */
 465      setSubs : function (name /*:String*/, value /*:Object*/, options /*:Object*/) /*:String*/ {
 466          
 467          var lang = YAHOO.lang;
 468          
 469          if (!lang.isString(name)){
 470              throw new TypeError("Cookie.setSubs(): Cookie name must be a string.");
 471          }
 472          
 473          if (!lang.isObject(value)){
 474              throw new TypeError("Cookie.setSubs(): Cookie value must be an object.");
 475          }
 476          
 477          var text /*:String*/ = this._createCookieString(name, this._createCookieHashString(value), false, options);
 478          document.cookie = text;
 479          return text;
 480      }
 481  
 482  };
 483  
 484  YAHOO.register("cookie", YAHOO.util.Cookie, {version: "2.9.0", build: "2800"});
 485  
 486  }, '2.9.0' ,{"requires": ["yui2-yahoo"]});