scratch – Blame information for rev 58
?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 | |||
97 | ## Namespace conflicts |
||
98 | |||
99 | 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. |
||
100 | |||
101 | ```javascript |
||
102 | // Assign the js-cookie api to a different variable and restore the original "window.Cookies" |
||
103 | var Cookies2 = Cookies.noConflict(); |
||
104 | Cookies2.set('name', 'value'); |
||
105 | ``` |
||
106 | |||
107 | *Note: The `.noConflict` method is not necessary when using AMD or CommonJS, thus it is not exposed in those environments.* |
||
108 | |||
109 | ## JSON |
||
110 | |||
111 | js-cookie provides unobtrusive JSON storage for cookies. |
||
112 | |||
113 | 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`: |
||
114 | |||
115 | ```javascript |
||
116 | Cookies.set('name', { foo: 'bar' }); |
||
117 | ``` |
||
118 | |||
119 | When reading a cookie with the default `Cookies.get` api, you receive the string representation stored in the cookie: |
||
120 | |||
121 | ```javascript |
||
122 | Cookies.get('name'); // => '{"foo":"bar"}' |
||
123 | ``` |
||
124 | |||
125 | ```javascript |
||
126 | Cookies.get(); // => { name: '{"foo":"bar"}' } |
||
127 | ``` |
||
128 | |||
129 | 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`: |
||
130 | |||
131 | ```javascript |
||
132 | Cookies.getJSON('name'); // => { foo: 'bar' } |
||
133 | ``` |
||
134 | |||
135 | ```javascript |
||
136 | Cookies.getJSON(); // => { name: { foo: 'bar' } } |
||
137 | ``` |
||
138 | |||
139 | *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* |
||
140 | |||
141 | ## Encoding |
||
142 | |||
143 | 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). |
||
144 | 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. |
||
145 | 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](#converter). |
||
146 | |||
147 | ## Cookie Attributes |
||
148 | |||
149 | 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. |
||
150 | |||
151 | ### expires |
||
152 | |||
153 | 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. |
||
154 | |||
155 | 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). |
||
156 | |||
157 | **Default:** Cookie is removed when the user closes the browser. |
||
158 | |||
159 | **Examples:** |
||
160 | |||
161 | ```javascript |
||
162 | Cookies.set('name', 'value', { expires: 365 }); |
||
163 | Cookies.get('name'); // => 'value' |
||
164 | Cookies.remove('name'); |
||
165 | ``` |
||
166 | |||
167 | ### path |
||
168 | |||
169 | A [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) indicating the path where the cookie is visible. |
||
170 | |||
171 | **Default:** `/` |
||
172 | |||
173 | **Examples:** |
||
174 | |||
175 | ```javascript |
||
176 | Cookies.set('name', 'value', { path: '' }); |
||
177 | Cookies.get('name'); // => 'value' |
||
178 | Cookies.remove('name', { path: '' }); |
||
179 | ``` |
||
180 | |||
181 | **Note regarding Internet Explorer:** |
||
182 | |||
183 | > 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. |
||
184 | |||
185 | (From [Internet Explorer Cookie Internals (FAQ)](http://blogs.msdn.com/b/ieinternals/archive/2009/08/20/wininet-ie-cookie-internals-faq.aspx)) |
||
186 | |||
187 | 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). |
||
188 | |||
189 | ### domain |
||
190 | |||
191 | 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. |
||
192 | |||
193 | **Default:** Cookie is visible only to the domain or subdomain of the page where the cookie was created, except for Internet Explorer (see below). |
||
194 | |||
195 | **Examples:** |
||
196 | |||
197 | Assuming a cookie that is being created on `site.com`: |
||
198 | |||
199 | ```javascript |
||
200 | Cookies.set('name', 'value', { domain: 'subdomain.site.com' }); |
||
201 | Cookies.get('name'); // => undefined (need to read at 'subdomain.site.com') |
||
202 | ``` |
||
203 | |||
204 | **Note regarding Internet Explorer default behavior:** |
||
205 | |||
206 | > Q3: If I don’t specify a DOMAIN attribute (for) a cookie, IE sends it to all nested subdomains anyway? |
||
207 | > A: Yes, a cookie set on example.com will be sent to sub2.sub1.example.com. |
||
208 | > Internet Explorer differs from other browsers in this regard. |
||
209 | |||
210 | (From [Internet Explorer Cookie Internals (FAQ)](http://blogs.msdn.com/b/ieinternals/archive/2009/08/20/wininet-ie-cookie-internals-faq.aspx)) |
||
211 | |||
212 | This means that if you omit the `domain` attribute, it will be visible for a subdomain in IE. |
||
213 | |||
214 | ### secure |
||
215 | |||
216 | Either `true` or `false`, indicating if the cookie transmission requires a secure protocol (https). |
||
217 | |||
218 | **Default:** No secure protocol requirement. |
||
219 | |||
220 | **Examples:** |
||
221 | |||
222 | ```javascript |
||
223 | Cookies.set('name', 'value', { secure: true }); |
||
224 | Cookies.get('name'); // => 'value' |
||
225 | Cookies.remove('name', { secure: true }); |
||
226 | ``` |
||
227 | |||
228 | ## Converters |
||
229 | |||
230 | ### Read |
||
231 | |||
232 | Create a new instance of the api that overrides the default decoding implementation. |
||
233 | 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. |
||
234 | The returning String will be used as the cookie value. |
||
235 | |||
236 | Example from reading one of the cookies that can only be decoded using the `escape` function: |
||
237 | |||
238 | ```javascript |
||
239 | document.cookie = 'escaped=%u5317'; |
||
240 | document.cookie = 'default=%E5%8C%97'; |
||
241 | var cookies = Cookies.withConverter(function (value, name) { |
||
242 | if ( name === 'escaped' ) { |
||
243 | return unescape(value); |
||
244 | } |
||
245 | }); |
||
246 | cookies.get('escaped'); // 北 |
||
247 | cookies.get('default'); // 北 |
||
248 | cookies.get(); // { escaped: '北', default: '北' } |
||
249 | ``` |
||
250 | |||
251 | ### Write |
||
252 | |||
253 | Create a new instance of the api that overrides the default encoding implementation: |
||
254 | |||
255 | ```javascript |
||
256 | Cookies.withConverter({ |
||
257 | read: function (value, name) { |
||
258 | // Read converter |
||
259 | }, |
||
260 | write: function (value, name) { |
||
261 | // Write converter |
||
262 | } |
||
263 | }); |
||
264 | ``` |
||
265 | |||
266 | ## Server-side integration |
||
267 | |||
268 | Check out the [Servers Docs](SERVER_SIDE.md) |
||
269 | |||
270 | ## Contributing |
||
271 | |||
272 | Check out the [Contributing Guidelines](CONTRIBUTING.md) |
||
273 | |||
274 | ## Manual release steps |
||
275 | |||
276 | * Increment the "version" attribute of `package.json` |
||
277 | * Increment the version number in the `src/js.cookie.js` file |
||
278 | * Commit with the message "Release version x.x.x" |
||
279 | * Create version tag in git |
||
280 | * Create a github release and upload the minified file |
||
281 | * Change the `latest` tag pointer to the latest commit |
||
282 | * `git tag -fa latest` |
||
283 | * `git push <remote> :refs/tags/latest` |
||
284 | * Commit with the message "Prepare for the next development iteration" |
||
285 | * Release on npm |
||
286 | |||
287 | ## Authors |
||
288 | |||
289 | * [Klaus Hartl](https://github.com/carhartl) |
||
290 | * [Fagner Brack](https://github.com/FagnerMartinsBrack) |
||
291 | * And awesome [contributors](https://github.com/js-cookie/js-cookie/graphs/contributors) |