Docs/Utilities/Cookie.md

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