scratch – Blame information for rev 125
?pathlinks?
Rev | Author | Line No. | Line |
---|---|---|---|
58 | office | 1 | <p align="center"> |
2 | <img src="https://cloud.githubusercontent.com/assets/835857/14581711/ba623018-0436-11e6-8fce-d2ccd4d379c9.gif"> |
||
3 | </p> |
||
4 | |||
5 | # JavaScript Cookie [![Build Status](https://travis-ci.org/js-cookie/js-cookie.svg?branch=master)](https://travis-ci.org/js-cookie/js-cookie) [![Code Climate](https://codeclimate.com/github/js-cookie/js-cookie.svg)](https://codeclimate.com/github/js-cookie/js-cookie) |
||
6 | |||
7 | A simple, lightweight JavaScript API for handling cookies |
||
8 | |||
9 | * Works in [all](https://saucelabs.com/u/js-cookie) browsers |
||
10 | * Accepts [any](#encoding) character |
||
11 | * [Heavily](test) tested |
||
12 | * No dependency |
||
13 | * [Unobtrusive](#json) JSON support |
||
14 | * Supports AMD/CommonJS |
||
15 | * [RFC 6265](https://tools.ietf.org/html/rfc6265) compliant |
||
16 | * Useful [Wiki](https://github.com/js-cookie/js-cookie/wiki) |
||
17 | * Enable [custom encoding/decoding](#converters) |
||
18 | * **~900 bytes** gzipped! |
||
19 | |||
20 | **If you're viewing this at https://github.com/js-cookie/js-cookie, you're reading the documentation for the master branch. |
||
21 | [View documentation for the latest release.](https://github.com/js-cookie/js-cookie/tree/latest#readme)** |
||
22 | |||
23 | ## Build Status Matrix |
||
24 | |||
25 | [![Selenium Test Status](https://saucelabs.com/browser-matrix/js-cookie.svg)](https://saucelabs.com/u/js-cookie) |
||
26 | |||
27 | ## Installation |
||
28 | |||
29 | ### Direct download |
||
30 | |||
31 | Download the script [here](https://github.com/js-cookie/js-cookie/blob/latest/src/js.cookie.js) and include it (unless you are packaging scripts somehow else): |
||
32 | |||
33 | ```html |
||
34 | <script src="/path/to/js.cookie.js"></script> |
||
35 | ``` |
||
36 | |||
37 | **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 |
||
38 | in Internet Explorer on Windows 7 for instance (because of the wrong MIME type). Bottom line: GitHub is not a CDN. |
||
39 | |||
40 | ### Package Managers |
||
41 | |||
42 | JavaScript Cookie supports [npm](https://www.npmjs.com/package/js-cookie) and [Bower](http://bower.io/search/?q=js-cookie) under the name `js-cookie`. |
||
43 | |||
44 | ### Module Loaders |
||
45 | |||
46 | JavaScript Cookie can also be loaded as an AMD, CommonJS or [ES6](https://github.com/js-cookie/js-cookie/issues/233#issuecomment-233187386) module. |
||
47 | |||
48 | ## Basic Usage |
||
49 | |||
50 | Create a cookie, valid across the entire site: |
||
51 | |||
52 | ```javascript |
||
53 | Cookies.set('name', 'value'); |
||
54 | ``` |
||
55 | |||
56 | Create a cookie that expires 7 days from now, valid across the entire site: |
||
57 | |||
58 | ```javascript |
||
59 | Cookies.set('name', 'value', { expires: 7 }); |
||
60 | ``` |
||
61 | |||
62 | Create an expiring cookie, valid to the path of the current page: |
||
63 | |||
64 | ```javascript |
||
65 | Cookies.set('name', 'value', { expires: 7, path: '' }); |
||
66 | ``` |
||
67 | |||
68 | Read cookie: |
||
69 | |||
70 | ```javascript |
||
71 | Cookies.get('name'); // => 'value' |
||
72 | Cookies.get('nothing'); // => undefined |
||
73 | ``` |
||
74 | |||
75 | Read all visible cookies: |
||
76 | |||
77 | ```javascript |
||
78 | Cookies.get(); // => { name: 'value' } |
||
79 | ``` |
||
80 | |||
81 | Delete cookie: |
||
82 | |||
83 | ```javascript |
||
84 | Cookies.remove('name'); |
||
85 | ``` |
||
86 | |||
87 | Delete a cookie valid to the path of the current page: |
||
88 | |||
89 | ```javascript |
||
90 | Cookies.set('name', 'value', { path: '' }); |
||
91 | Cookies.remove('name'); // fail! |
||
92 | Cookies.remove('name', { path: '' }); // removed! |
||
93 | ``` |
||
94 | |||
95 | *IMPORTANT! when deleting a cookie, you must pass the exact same path and domain attributes that was used to set the cookie, unless you're relying on the [default attributes](#cookie-attributes).* |
||
96 | |||
125 | office | 97 | *Note: Removing unexisting cookie does not raise any exception nor return any value* |
98 | |||
58 | office | 99 | ## Namespace conflicts |
100 | |||
101 | If there is any danger of a conflict with the namespace `Cookies`, the `noConflict` method will allow you to define a new namespace and preserve the original one. This is especially useful when running the script on third party sites e.g. as part of a widget or SDK. |
||
102 | |||
103 | ```javascript |
||
104 | // Assign the js-cookie api to a different variable and restore the original "window.Cookies" |
||
105 | var Cookies2 = Cookies.noConflict(); |
||
106 | Cookies2.set('name', 'value'); |
||
107 | ``` |
||
108 | |||
109 | *Note: The `.noConflict` method is not necessary when using AMD or CommonJS, thus it is not exposed in those environments.* |
||
110 | |||
111 | ## JSON |
||
112 | |||
113 | js-cookie provides unobtrusive JSON storage for cookies. |
||
114 | |||
115 | When creating a cookie you can pass an Array or Object Literal instead of a string in the value. If you do so, js-cookie will store the string representation of the object according to `JSON.stringify`: |
||
116 | |||
117 | ```javascript |
||
118 | Cookies.set('name', { foo: 'bar' }); |
||
119 | ``` |
||
120 | |||
121 | When reading a cookie with the default `Cookies.get` api, you receive the string representation stored in the cookie: |
||
122 | |||
123 | ```javascript |
||
124 | Cookies.get('name'); // => '{"foo":"bar"}' |
||
125 | ``` |
||
126 | |||
127 | ```javascript |
||
128 | Cookies.get(); // => { name: '{"foo":"bar"}' } |
||
129 | ``` |
||
130 | |||
131 | When reading a cookie with the `Cookies.getJSON` api, you receive the parsed representation of the string stored in the cookie according to `JSON.parse`: |
||
132 | |||
133 | ```javascript |
||
134 | Cookies.getJSON('name'); // => { foo: 'bar' } |
||
135 | ``` |
||
136 | |||
137 | ```javascript |
||
138 | Cookies.getJSON(); // => { name: { foo: 'bar' } } |
||
139 | ``` |
||
140 | |||
141 | *Note: To support IE6-7 ([and IE 8 compatibility mode](http://stackoverflow.com/questions/4715373/json-object-undefined-in-internet-explorer-8)) you need to include the JSON-js polyfill: https://github.com/douglascrockford/JSON-js* |
||
142 | |||
143 | ## Encoding |
||
144 | |||
145 | This project is [RFC 6265](http://tools.ietf.org/html/rfc6265#section-4.1.1) compliant. All special characters that are not allowed in the cookie-name or cookie-value are encoded with each one's UTF-8 Hex equivalent using [percent-encoding](http://en.wikipedia.org/wiki/Percent-encoding). |
||
146 | The only character in cookie-name or cookie-value that is allowed and still encoded is the percent `%` character, it is escaped in order to interpret percent input as literal. |
||
125 | office | 147 | Please note that the default encoding/decoding strategy is meant to be interoperable [only between cookies that are read/written by js-cookie](https://github.com/js-cookie/js-cookie/pull/200#discussion_r63270778). To override the default encoding/decoding strategy you need to use a [converter](#converters). |
58 | office | 148 | |
149 | ## Cookie Attributes |
||
150 | |||
151 | Cookie attributes defaults can be set globally by setting properties of the `Cookies.defaults` object or individually for each call to `Cookies.set(...)` by passing a plain object in the last argument. Per-call attributes override the default attributes. |
||
152 | |||
153 | ### expires |
||
154 | |||
155 | Define when the cookie will be removed. Value can be a [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) which will be interpreted as days from time of creation or a [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) instance. If omitted, the cookie becomes a session cookie. |
||
156 | |||
157 | To create a cookie that expires in less than a day, you can check the [FAQ on the Wiki](https://github.com/js-cookie/js-cookie/wiki/Frequently-Asked-Questions#expire-cookies-in-less-than-a-day). |
||
158 | |||
159 | **Default:** Cookie is removed when the user closes the browser. |
||
160 | |||
161 | **Examples:** |
||
162 | |||
163 | ```javascript |
||
164 | Cookies.set('name', 'value', { expires: 365 }); |
||
165 | Cookies.get('name'); // => 'value' |
||
166 | Cookies.remove('name'); |
||
167 | ``` |
||
168 | |||
169 | ### path |
||
170 | |||
171 | A [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) indicating the path where the cookie is visible. |
||
172 | |||
173 | **Default:** `/` |
||
174 | |||
175 | **Examples:** |
||
176 | |||
177 | ```javascript |
||
178 | Cookies.set('name', 'value', { path: '' }); |
||
179 | Cookies.get('name'); // => 'value' |
||
180 | Cookies.remove('name', { path: '' }); |
||
181 | ``` |
||
182 | |||
183 | **Note regarding Internet Explorer:** |
||
184 | |||
185 | > 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. |
||
186 | |||
187 | (From [Internet Explorer Cookie Internals (FAQ)](http://blogs.msdn.com/b/ieinternals/archive/2009/08/20/wininet-ie-cookie-internals-faq.aspx)) |
||
188 | |||
189 | 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). |
||
190 | |||
191 | ### domain |
||
192 | |||
193 | A [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) indicating a valid domain where the cookie should be visible. The cookie will also be visible to all subdomains. |
||
194 | |||
195 | **Default:** Cookie is visible only to the domain or subdomain of the page where the cookie was created, except for Internet Explorer (see below). |
||
196 | |||
197 | **Examples:** |
||
198 | |||
199 | Assuming a cookie that is being created on `site.com`: |
||
200 | |||
201 | ```javascript |
||
202 | Cookies.set('name', 'value', { domain: 'subdomain.site.com' }); |
||
203 | Cookies.get('name'); // => undefined (need to read at 'subdomain.site.com') |
||
204 | ``` |
||
205 | |||
206 | **Note regarding Internet Explorer default behavior:** |
||
207 | |||
208 | > Q3: If I don’t specify a DOMAIN attribute (for) a cookie, IE sends it to all nested subdomains anyway? |
||
209 | > A: Yes, a cookie set on example.com will be sent to sub2.sub1.example.com. |
||
210 | > Internet Explorer differs from other browsers in this regard. |
||
211 | |||
212 | (From [Internet Explorer Cookie Internals (FAQ)](http://blogs.msdn.com/b/ieinternals/archive/2009/08/20/wininet-ie-cookie-internals-faq.aspx)) |
||
213 | |||
214 | This means that if you omit the `domain` attribute, it will be visible for a subdomain in IE. |
||
215 | |||
216 | ### secure |
||
217 | |||
218 | Either `true` or `false`, indicating if the cookie transmission requires a secure protocol (https). |
||
219 | |||
220 | **Default:** No secure protocol requirement. |
||
221 | |||
222 | **Examples:** |
||
223 | |||
224 | ```javascript |
||
225 | Cookies.set('name', 'value', { secure: true }); |
||
226 | Cookies.get('name'); // => 'value' |
||
227 | Cookies.remove('name', { secure: true }); |
||
228 | ``` |
||
229 | |||
230 | ## Converters |
||
231 | |||
232 | ### Read |
||
233 | |||
234 | Create a new instance of the api that overrides the default decoding implementation. |
||
235 | All get methods that rely in a proper decoding to work, such as `Cookies.get()` and `Cookies.get('name')`, will run the converter first for each cookie. |
||
236 | The returning String will be used as the cookie value. |
||
237 | |||
238 | Example from reading one of the cookies that can only be decoded using the `escape` function: |
||
239 | |||
240 | ```javascript |
||
241 | document.cookie = 'escaped=%u5317'; |
||
242 | document.cookie = 'default=%E5%8C%97'; |
||
243 | var cookies = Cookies.withConverter(function (value, name) { |
||
244 | if ( name === 'escaped' ) { |
||
245 | return unescape(value); |
||
246 | } |
||
247 | }); |
||
248 | cookies.get('escaped'); // 北 |
||
249 | cookies.get('default'); // 北 |
||
250 | cookies.get(); // { escaped: '北', default: '北' } |
||
251 | ``` |
||
252 | |||
253 | ### Write |
||
254 | |||
255 | Create a new instance of the api that overrides the default encoding implementation: |
||
256 | |||
257 | ```javascript |
||
258 | Cookies.withConverter({ |
||
259 | read: function (value, name) { |
||
260 | // Read converter |
||
261 | }, |
||
262 | write: function (value, name) { |
||
263 | // Write converter |
||
264 | } |
||
265 | }); |
||
266 | ``` |
||
267 | |||
268 | ## Server-side integration |
||
269 | |||
270 | Check out the [Servers Docs](SERVER_SIDE.md) |
||
271 | |||
272 | ## Contributing |
||
273 | |||
274 | Check out the [Contributing Guidelines](CONTRIBUTING.md) |
||
275 | |||
125 | office | 276 | ## Security |
277 | |||
278 | For vulnerability reports, send an e-mail to `jscookie at gmail dot com` |
||
279 | |||
58 | office | 280 | ## Manual release steps |
281 | |||
282 | * Increment the "version" attribute of `package.json` |
||
283 | * Increment the version number in the `src/js.cookie.js` file |
||
284 | * Commit with the message "Release version x.x.x" |
||
285 | * Create version tag in git |
||
286 | * Create a github release and upload the minified file |
||
287 | * Change the `latest` tag pointer to the latest commit |
||
125 | office | 288 | * `git tag -f latest` |
58 | office | 289 | * `git push <remote> :refs/tags/latest` |
125 | office | 290 | * `git push origin master --tags` |
58 | office | 291 | * Release on npm |
292 | |||
293 | ## Authors |
||
294 | |||
295 | * [Klaus Hartl](https://github.com/carhartl) |
||
296 | * [Fagner Brack](https://github.com/FagnerMartinsBrack) |
||
297 | * And awesome [contributors](https://github.com/js-cookie/js-cookie/graphs/contributors) |