Dateigrösse: 5.17 kb
1 # IMPORTANT! 2 3 This project was moved to https://github.com/js-cookie/js-cookie, check [the discussion](https://github.com/carhartl/jquery-cookie/issues/349). 4 5 New issues should be opened at https://github.com/js-cookie/js-cookie/issues 6 7 # jquery.cookie [](https://travis-ci.org/carhartl/jquery-cookie) [](https://codeclimate.com/github/carhartl/jquery-cookie) 8 9 A simple, lightweight jQuery plugin for reading, writing and deleting cookies. 10 11 **If you're viewing this, you're reading the documentation for the old repository. 12 [View documentation for the latest backwards compatible release (1.5.1).](https://github.com/js-cookie/js-cookie/tree/v1.5.1)** 13 14 ## Build Status Matrix 15 16 [](https://saucelabs.com/u/jquery-cookie) 17 18 ## Installation 19 20 Include script *after* the jQuery library (unless you are packaging scripts somehow else): 21 22 ```html 23 <script src="/path/to/jquery.cookie.js"></script> 24 ``` 25 26 **Do not include the script directly from GitHub (http://raw.github.com/...).** The file is being served as text/plain and as such being blocked 27 in Internet Explorer on Windows 7 for instance (because of the wrong MIME type). Bottom line: GitHub is not a CDN. 28 29 The plugin can also be loaded as AMD or CommonJS module. 30 31 ## Usage 32 33 Create session cookie: 34 35 ```javascript 36 $.cookie('name', 'value'); 37 ``` 38 39 Create expiring cookie, 7 days from then: 40 41 ```javascript 42 $.cookie('name', 'value', { expires: 7 }); 43 ``` 44 45 Create expiring cookie, valid across entire site: 46 47 ```javascript 48 $.cookie('name', 'value', { expires: 7, path: '/' }); 49 ``` 50 51 Read cookie: 52 53 ```javascript 54 $.cookie('name'); // => "value" 55 $.cookie('nothing'); // => undefined 56 ``` 57 58 Read all available cookies: 59 60 ```javascript 61 $.cookie(); // => { "name": "value" } 62 ``` 63 64 Delete cookie: 65 66 ```javascript 67 // Returns true when cookie was successfully deleted, otherwise false 68 $.removeCookie('name'); // => true 69 $.removeCookie('nothing'); // => false 70 71 // Need to use the same attributes (path, domain) as what the cookie was written with 72 $.cookie('name', 'value', { path: '/' }); 73 // This won't work! 74 $.removeCookie('name'); // => false 75 // This will work! 76 $.removeCookie('name', { path: '/' }); // => true 77 ``` 78 79 *Note: when deleting a cookie, you must pass the exact same path, domain and secure options that were used to set the cookie, unless you're relying on the default options that is.* 80 81 ## Configuration 82 83 ### raw 84 85 By default the cookie value is encoded/decoded when writing/reading, using `encodeURIComponent`/`decodeURIComponent`. Bypass this by setting raw to true: 86 87 ```javascript 88 $.cookie.raw = true; 89 ``` 90 91 ### json 92 93 Turn on automatic storage of JSON objects passed as the cookie value. Assumes `JSON.stringify` and `JSON.parse`: 94 95 ```javascript 96 $.cookie.json = true; 97 ``` 98 99 ## Cookie Options 100 101 Cookie attributes can be set globally by setting properties of the `$.cookie.defaults` object or individually for each call to `$.cookie()` by passing a plain object to the options argument. Per-call options override the default options. 102 103 ### expires 104 105 expires: 365 106 107 Define lifetime of the cookie. Value can be a `Number` which will be interpreted as days from time of creation or a `Date` object. If omitted, the cookie becomes a session cookie. 108 109 ### path 110 111 path: '/' 112 113 Define the path where the cookie is valid. *By default the path of the cookie is the path of the page where the cookie was created (standard browser behavior).* If you want to make it available for instance across the entire domain use `path: '/'`. Default: path of page where the cookie was created. 114 115 **Note regarding Internet Explorer:** 116 117 > Due to an obscure bug in the underlying WinINET InternetGetCookie implementation, IE’s document.cookie will not return a cookie if it was set with a path attribute containing a filename. 118 119 (From [Internet Explorer Cookie Internals (FAQ)](http://blogs.msdn.com/b/ieinternals/archive/2009/08/20/wininet-ie-cookie-internals-faq.aspx)) 120 121 This means one cannot set a path using `path: window.location.pathname` in case such pathname contains a filename like so: `/check.html` (or at least, such cookie cannot be read correctly). 122 123 ### domain 124 125 domain: 'example.com' 126 127 Define the domain where the cookie is valid. Default: domain of page where the cookie was created. 128 129 ### secure 130 131 secure: true 132 133 If true, the cookie transmission requires a secure protocol (https). Default: `false`. 134 135 ## Converters 136 137 Provide a conversion function as optional last argument for reading, in order to change the cookie's value 138 to a different representation on the fly. 139 140 Example for parsing a value into a number: 141 142 ```javascript 143 $.cookie('foo', '42'); 144 $.cookie('foo', Number); // => 42 145 ``` 146 147 Dealing with cookies that have been encoded using `escape` (3rd party cookies): 148 149 ```javascript 150 $.cookie.raw = true; 151 $.cookie('foo', unescape); 152 ``` 153 154 You can pass an arbitrary conversion function. 155 156 ## Contributing 157 158 Check out the [Contributing Guidelines](CONTRIBUTING.md) 159 160 ## Authors 161 162 [Klaus Hartl](https://github.com/carhartl) 163