[Summary view] [Print] [Text view]

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