Docs/Utilities/Cookie.md

   1 Object: Cookie {#Cookie}
   2 ========================
   3
   4 Sets and accesses cookies.
   5
   6 ### Credits:
   7
   8 - Based on the functions by Peter-Paul Koch [QuirksMode][].
   9
  10 ### Options: {#Cookie-options}
  11
  12 * domain   - (*string*: defaults to false) The domain the Cookie belongs to.
  13 * path     - (*string*: defaults to false) The path the Cookie belongs to.
  14 * duration - (*number*: defaults to false) The duration of the Cookie before it expires, in days. If set to false or 0, the cookie will be a session cookie that expires when the browser is closed.
  15 * secure   - (*boolean*: defaults to false) Stored cookie information can be accessed only from a secure environment.
  16
  17 ### Notes:
  18
  19 - In order to share the Cookie with pages located in a different path, the [Cookie.options.domain][] value must be set.
  20
  21
  22
  23 Cookie Method: write {#Cookie:write}
  24 --------------------------------
  25
  26 Writes a cookie in the browser.
  27
  28 ### Syntax:
  29
  30         var myCookie = Cookie.write(key, value[, options]);
  31
  32 ### Arguments:
  33
  34 1. key     - (*string*) The key (or name) of the cookie.
  35 2. value   - (*string*) The value to set. Cannot contain semicolons.
  36 3. options - (*mixed*, optional) See [Cookie][].
  37
  38 ### Returns:
  39
  40 * (*object*) An object with the options, the key and the value. You can give it as first parameter to Cookie.remove.
  41
  42 ### Examples:
  43
  44 Saves the Cookie for the Duration of the Session:
  45
  46         var myCookie = Cookie.write('username', 'Harald');
  47
  48 Saves the Cookie for a Day:
  49
  50         var myCookie  = Cookie.write('username', 'JackBauer', {duration: 1});
  51
  52
  53
  54 Cookie Method: read {#Cookie:read}
  55 --------------------------------
  56
  57 Reads the value of a Cookie.
  58
  59 ### Syntax:
  60
  61         var myCookie = Cookie.read(name);
  62
  63 ### Arguments:
  64
  65 1. name - (*string*) The name of the Cookie to retrieve.
  66
  67 ### Returns:
  68
  69 * (*mixed*) The cookie string value, or null if not found.
  70
  71 ### Examples:
  72
  73         Cookie.read("username");
  74
  75
  76
  77 Cookie Method: dispose {#Cookie:dispose}
  78 --------------------------------------
  79
  80 Removes a cookie from the browser.
  81
  82 ### Syntax:
  83
  84         var oldCookie = Cookie.dispose(cookie[, options]);
  85
  86 ### Arguments:
  87
  88 1. name  - (*string*) The name of the cookie to remove or a previously saved Cookie instance.
  89 2. options - (*object*, optional) See [Cookie][].
  90
  91 ### Examples:
  92
  93 Remove a Cookie:
  94
  95         Cookie.dispose('username'); //Bye-bye JackBauer! Seeya in 24 Hours.
  96
  97 Creating a Cookie and Removing it Right Away:
  98
  99         var myCookie = Cookie.write('username', 'Aaron', {domain: 'mootools.net'});
 100         if (Cookie.read('username') == 'Aaron') { Cookie.dispose(myCookie); }
 101
 102
 103
 104 [Cookie]: #Cookie
 105 [Cookie.options]: #Cookie-options
 106 [Cookie.options.domain]: #Cookie-options
 107 [QuirksMode]: http://www.quirksmode.org