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