gitweb/static/js/lib/cookies.js

   1 /**
   2  * @fileOverview Accessing cookies from JavaScript
   3  * @license GPLv2 or later
   4  */
   5
   6 /*
   7  * Based on subsection "Cookies in JavaScript" of "Professional
   8  * JavaScript for Web Developers" by Nicholas C. Zakas and cookie
   9  * plugin from jQuery (dual licensed under the MIT and GPL licenses)
  10  */
  11
  12
  13 /**
  14  * Create a cookie with the given name and value,
  15  * and other optional parameters.
  16  *
  17  * @example
  18  *   setCookie('foo', 'bar'); // will be deleted when browser exits
  19  *   setCookie('foo', 'bar', { expires: new Date(Date.parse('Jan 1, 2012')) });
  20  *   setCookie('foo', 'bar', { expires: 7 }); // 7 days = 1 week
  21  *   setCookie('foo', 'bar', { expires: 14, path: '/' });
  22  *
  23  * @param {String} sName:    Unique name of a cookie (letters, numbers, underscores).
  24  * @param {String} sValue:   The string value stored in a cookie.
  25  * @param {Object} [options] An object literal containing key/value pairs
  26  *                           to provide optional cookie attributes.
  27  * @param {String|Number|Date} [options.expires] Either literal string to be used as cookie expires,
  28  *                            or an integer specifying the expiration date from now on in days,
  29  *                            or a Date object to be used as cookie expiration date.
  30  *                            If a negative value is specified or a date in the past),
  31  *                            the cookie will be deleted.
  32  *                            If set to null or omitted, the cookie will be a session cookie
  33  *                            and will not be retained when the the browser exits.
  34  * @param {String} [options.path] Restrict access of a cookie to particular directory
  35  *                               (default: path of page that created the cookie).
  36  * @param {String} [options.domain] Override what web sites are allowed to access cookie
  37  *                                  (default: domain of page that created the cookie).
  38  * @param {Boolean} [options.secure] If true, the secure attribute of the cookie will be set
  39  *                                   and the cookie would be accessible only from secure sites
  40  *                                   (cookie transmission will require secure protocol like HTTPS).
  41  */
  42 function setCookie(sName, sValue, options) {
  43         options = options || {};
  44         if (sValue === null) {
  45                 sValue = '';
  46                 option.expires = 'delete';
  47         }
  48
  49         var sCookie = sName + '=' + encodeURIComponent(sValue);
  50
  51         if (options.expires) {
  52                 var oExpires = options.expires, sDate;
  53                 if (oExpires === 'delete') {
  54                         sDate = 'Thu, 01 Jan 1970 00:00:00 GMT';
  55                 } else if (typeof oExpires === 'string') {
  56                         sDate = oExpires;
  57                 } else {
  58                         var oDate;
  59                         if (typeof oExpires === 'number') {
  60                                 oDate = new Date();
  61                                 oDate.setTime(oDate.getTime() + (oExpires * 24 * 60 * 60 * 1000)); // days to ms
  62                         } else {
  63                                 oDate = oExpires;
  64                         }
  65                         sDate = oDate.toGMTString();
  66                 }
  67                 sCookie += '; expires=' + sDate;
  68         }
  69
  70         if (options.path) {
  71                 sCookie += '; path=' + (options.path);
  72         }
  73         if (options.domain) {
  74                 sCookie += '; domain=' + (options.domain);
  75         }
  76         if (options.secure) {
  77                 sCookie += '; secure';
  78         }
  79         document.cookie = sCookie;
  80 }
  81
  82 /**
  83  * Get the value of a cookie with the given name.
  84  *
  85  * @param {String} sName: Unique name of a cookie (letters, numbers, underscores)
  86  * @returns {String|null} The string value stored in a cookie
  87  */
  88 function getCookie(sName) {
  89         var sRE = '(?:; )?' + sName + '=([^;]*);?';
  90         var oRE = new RegExp(sRE);
  91         if (oRE.test(document.cookie)) {
  92                 return decodeURIComponent(RegExp['$1']);
  93         } else {
  94                 return null;
  95         }
  96 }
  97
  98 /**
  99  * Delete cookie with given name
 100  *
 101  * @param {String} sName:    Unique name of a cookie (letters, numbers, underscores)
 102  * @param {Object} [options] An object literal containing key/value pairs
 103  *                           to provide optional cookie attributes.
 104  * @param {String} [options.path]   Must be the same as when setting a cookie
 105  * @param {String} [options.domain] Must be the same as when setting a cookie
 106  */
 107 function deleteCookie(sName, options) {
 108         options = options || {};
 109         options.expires = 'delete';
 110
 111         setCookie(sName, '', options);
 112 }
 113
 114 /* end of cookies.js */