src/util/Cookies.js

   1 /*
   2
   3 This file is part of Ext JS 4
   4
   5 Copyright (c) 2011 Sencha Inc
   6
   7 Contact:  http://www.sencha.com/contact
   8
   9 GNU General Public License Usage
  10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file.  Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
  11
  12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
  13
  14 */
  15 /**
  16  * @class Ext.util.Cookies
  17
  18 Utility class for setting/reading values from browser cookies.
  19 Values can be written using the {@link #set} method.
  20 Values can be read using the {@link #get} method.
  21 A cookie can be invalidated on the client machine using the {@link #clear} method.
  22
  23  * @markdown
  24  * @singleton
  25  */
  26 Ext.define('Ext.util.Cookies', {
  27     singleton: true,
  28
  29     /**
  30      * Create a cookie with the specified name and value. Additional settings
  31      * for the cookie may be optionally specified (for example: expiration,
  32      * access restriction, SSL).
  33      * @param {String} name The name of the cookie to set.
  34      * @param {Object} value The value to set for the cookie.
  35      * @param {Object} expires (Optional) Specify an expiration date the
  36      * cookie is to persist until.  Note that the specified Date object will
  37      * be converted to Greenwich Mean Time (GMT).
  38      * @param {String} path (Optional) Setting a path on the cookie restricts
  39      * access to pages that match that path. Defaults to all pages (<tt>'/'</tt>).
  40      * @param {String} domain (Optional) Setting a domain restricts access to
  41      * pages on a given domain (typically used to allow cookie access across
  42      * subdomains). For example, "sencha.com" will create a cookie that can be
  43      * accessed from any subdomain of sencha.com, including www.sencha.com,
  44      * support.sencha.com, etc.
  45      * @param {Boolean} secure (Optional) Specify true to indicate that the cookie
  46      * should only be accessible via SSL on a page using the HTTPS protocol.
  47      * Defaults to <tt>false</tt>. Note that this will only work if the page
  48      * calling this code uses the HTTPS protocol, otherwise the cookie will be
  49      * created with default options.
  50      */
  51     set : function(name, value){
  52         var argv = arguments,
  53             argc = arguments.length,
  54             expires = (argc > 2) ? argv[2] : null,
  55             path = (argc > 3) ? argv[3] : '/',
  56             domain = (argc > 4) ? argv[4] : null,
  57             secure = (argc > 5) ? argv[5] : false;
  58
  59         document.cookie = name + "=" + escape(value) + ((expires === null) ? "" : ("; expires=" + expires.toGMTString())) + ((path === null) ? "" : ("; path=" + path)) + ((domain === null) ? "" : ("; domain=" + domain)) + ((secure === true) ? "; secure" : "");
  60     },
  61
  62     /**
  63      * Retrieves cookies that are accessible by the current page. If a cookie
  64      * does not exist, <code>get()</code> returns <tt>null</tt>.  The following
  65      * example retrieves the cookie called "valid" and stores the String value
  66      * in the variable <tt>validStatus</tt>.
  67      * <pre><code>
  68      * var validStatus = Ext.util.Cookies.get("valid");
  69      * </code></pre>
  70      * @param {String} name The name of the cookie to get
  71      * @return {Object} Returns the cookie value for the specified name;
  72      * null if the cookie name does not exist.
  73      */
  74     get : function(name){
  75         var arg = name + "=",
  76             alen = arg.length,
  77             clen = document.cookie.length,
  78             i = 0,
  79             j = 0;
  80
  81         while(i < clen){
  82             j = i + alen;
  83             if(document.cookie.substring(i, j) == arg){
  84                 return this.getCookieVal(j);
  85             }
  86             i = document.cookie.indexOf(" ", i) + 1;
  87             if(i === 0){
  88                 break;
  89             }
  90         }
  91         return null;
  92     },
  93
  94     /**
  95      * Removes a cookie with the provided name from the browser
  96      * if found by setting its expiration date to sometime in the past.
  97      * @param {String} name The name of the cookie to remove
  98      * @param {String} path (optional) The path for the cookie. This must be included if you included a path while setting the cookie.
  99      */
 100     clear : function(name, path){
 101         if(this.get(name)){
 102             path = path || '/';
 103             document.cookie = name + '=' + '; expires=Thu, 01-Jan-70 00:00:01 GMT; path=' + path;
 104         }
 105     },
 106
 107     /**
 108      * @private
 109      */
 110     getCookieVal : function(offset){
 111         var endstr = document.cookie.indexOf(";", offset);
 112         if(endstr == -1){
 113             endstr = document.cookie.length;
 114         }
 115         return unescape(document.cookie.substring(offset, endstr));
 116     }
 117 });
 118