scratch – Diff between revs 58 and 125
?pathlinks?
Rev 58 | Rev 125 | |||
---|---|---|---|---|
1 | <p align="center"> |
1 | <p align="center"> |
|
2 | <img src="https://cloud.githubusercontent.com/assets/835857/14581711/ba623018-0436-11e6-8fce-d2ccd4d379c9.gif"> |
2 | <img src="https://cloud.githubusercontent.com/assets/835857/14581711/ba623018-0436-11e6-8fce-d2ccd4d379c9.gif"> |
|
3 | </p> |
3 | </p> |
|
4 | |
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) |
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 | |
6 | |
|
7 | A simple, lightweight JavaScript API for handling cookies |
7 | A simple, lightweight JavaScript API for handling cookies |
|
8 | |
8 | |
|
9 | * Works in [all](https://saucelabs.com/u/js-cookie) browsers |
9 | * Works in [all](https://saucelabs.com/u/js-cookie) browsers |
|
10 | * Accepts [any](#encoding) character |
10 | * Accepts [any](#encoding) character |
|
11 | * [Heavily](test) tested |
11 | * [Heavily](test) tested |
|
12 | * No dependency |
12 | * No dependency |
|
13 | * [Unobtrusive](#json) JSON support |
13 | * [Unobtrusive](#json) JSON support |
|
14 | * Supports AMD/CommonJS |
14 | * Supports AMD/CommonJS |
|
15 | * [RFC 6265](https://tools.ietf.org/html/rfc6265) compliant |
15 | * [RFC 6265](https://tools.ietf.org/html/rfc6265) compliant |
|
16 | * Useful [Wiki](https://github.com/js-cookie/js-cookie/wiki) |
16 | * Useful [Wiki](https://github.com/js-cookie/js-cookie/wiki) |
|
17 | * Enable [custom encoding/decoding](#converters) |
17 | * Enable [custom encoding/decoding](#converters) |
|
18 | * **~900 bytes** gzipped! |
18 | * **~900 bytes** gzipped! |
|
19 | |
19 | |
|
20 | **If you're viewing this at https://github.com/js-cookie/js-cookie, you're reading the documentation for the master branch. |
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)** |
21 | [View documentation for the latest release.](https://github.com/js-cookie/js-cookie/tree/latest#readme)** |
|
22 | |
22 | |
|
23 | ## Build Status Matrix |
23 | ## Build Status Matrix |
|
24 | |
24 | |
|
25 | [![Selenium Test Status](https://saucelabs.com/browser-matrix/js-cookie.svg)](https://saucelabs.com/u/js-cookie) |
25 | [![Selenium Test Status](https://saucelabs.com/browser-matrix/js-cookie.svg)](https://saucelabs.com/u/js-cookie) |
|
26 | |
26 | |
|
27 | ## Installation |
27 | ## Installation |
|
28 | |
28 | |
|
29 | ### Direct download |
29 | ### Direct download |
|
30 | |
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): |
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 | |
32 | |
|
33 | ```html |
33 | ```html |
|
34 | <script src="/path/to/js.cookie.js"></script> |
34 | <script src="/path/to/js.cookie.js"></script> |
|
35 | ``` |
35 | ``` |
|
36 | |
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 |
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. |
38 | in Internet Explorer on Windows 7 for instance (because of the wrong MIME type). Bottom line: GitHub is not a CDN. |
|
39 | |
39 | |
|
40 | ### Package Managers |
40 | ### Package Managers |
|
41 | |
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`. |
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 | |
43 | |
|
44 | ### Module Loaders |
44 | ### Module Loaders |
|
45 | |
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. |
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 | |
47 | |
|
48 | ## Basic Usage |
48 | ## Basic Usage |
|
49 | |
49 | |
|
50 | Create a cookie, valid across the entire site: |
50 | Create a cookie, valid across the entire site: |
|
51 | |
51 | |
|
52 | ```javascript |
52 | ```javascript |
|
53 | Cookies.set('name', 'value'); |
53 | Cookies.set('name', 'value'); |
|
54 | ``` |
54 | ``` |
|
55 | |
55 | |
|
56 | Create a cookie that expires 7 days from now, valid across the entire site: |
56 | Create a cookie that expires 7 days from now, valid across the entire site: |
|
57 | |
57 | |
|
58 | ```javascript |
58 | ```javascript |
|
59 | Cookies.set('name', 'value', { expires: 7 }); |
59 | Cookies.set('name', 'value', { expires: 7 }); |
|
60 | ``` |
60 | ``` |
|
61 | |
61 | |
|
62 | Create an expiring cookie, valid to the path of the current page: |
62 | Create an expiring cookie, valid to the path of the current page: |
|
63 | |
63 | |
|
64 | ```javascript |
64 | ```javascript |
|
65 | Cookies.set('name', 'value', { expires: 7, path: '' }); |
65 | Cookies.set('name', 'value', { expires: 7, path: '' }); |
|
66 | ``` |
66 | ``` |
|
67 | |
67 | |
|
68 | Read cookie: |
68 | Read cookie: |
|
69 | |
69 | |
|
70 | ```javascript |
70 | ```javascript |
|
71 | Cookies.get('name'); // => 'value' |
71 | Cookies.get('name'); // => 'value' |
|
72 | Cookies.get('nothing'); // => undefined |
72 | Cookies.get('nothing'); // => undefined |
|
73 | ``` |
73 | ``` |
|
74 | |
74 | |
|
75 | Read all visible cookies: |
75 | Read all visible cookies: |
|
76 | |
76 | |
|
77 | ```javascript |
77 | ```javascript |
|
78 | Cookies.get(); // => { name: 'value' } |
78 | Cookies.get(); // => { name: 'value' } |
|
79 | ``` |
79 | ``` |
|
80 | |
80 | |
|
81 | Delete cookie: |
81 | Delete cookie: |
|
82 | |
82 | |
|
83 | ```javascript |
83 | ```javascript |
|
84 | Cookies.remove('name'); |
84 | Cookies.remove('name'); |
|
85 | ``` |
85 | ``` |
|
86 | |
86 | |
|
87 | Delete a cookie valid to the path of the current page: |
87 | Delete a cookie valid to the path of the current page: |
|
88 | |
88 | |
|
89 | ```javascript |
89 | ```javascript |
|
90 | Cookies.set('name', 'value', { path: '' }); |
90 | Cookies.set('name', 'value', { path: '' }); |
|
91 | Cookies.remove('name'); // fail! |
91 | Cookies.remove('name'); // fail! |
|
92 | Cookies.remove('name', { path: '' }); // removed! |
92 | Cookies.remove('name', { path: '' }); // removed! |
|
93 | ``` |
93 | ``` |
|
94 | |
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).* |
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 | *Note: Removing unexisting cookie does not raise any exception nor return any value* |
||
96 | |
98 | |
|
97 | ## Namespace conflicts |
99 | ## Namespace conflicts |
|
98 | |
100 | |
|
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. |
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. |
|
100 | |
102 | |
|
101 | ```javascript |
103 | ```javascript |
|
102 | // Assign the js-cookie api to a different variable and restore the original "window.Cookies" |
104 | // Assign the js-cookie api to a different variable and restore the original "window.Cookies" |
|
103 | var Cookies2 = Cookies.noConflict(); |
105 | var Cookies2 = Cookies.noConflict(); |
|
104 | Cookies2.set('name', 'value'); |
106 | Cookies2.set('name', 'value'); |
|
105 | ``` |
107 | ``` |
|
106 | |
108 | |
|
107 | *Note: The `.noConflict` method is not necessary when using AMD or CommonJS, thus it is not exposed in those environments.* |
109 | *Note: The `.noConflict` method is not necessary when using AMD or CommonJS, thus it is not exposed in those environments.* |
|
108 | |
110 | |
|
109 | ## JSON |
111 | ## JSON |
|
110 | |
112 | |
|
111 | js-cookie provides unobtrusive JSON storage for cookies. |
113 | js-cookie provides unobtrusive JSON storage for cookies. |
|
112 | |
114 | |
|
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`: |
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`: |
|
114 | |
116 | |
|
115 | ```javascript |
117 | ```javascript |
|
116 | Cookies.set('name', { foo: 'bar' }); |
118 | Cookies.set('name', { foo: 'bar' }); |
|
117 | ``` |
119 | ``` |
|
118 | |
120 | |
|
119 | When reading a cookie with the default `Cookies.get` api, you receive the string representation stored in the cookie: |
121 | When reading a cookie with the default `Cookies.get` api, you receive the string representation stored in the cookie: |
|
120 | |
122 | |
|
121 | ```javascript |
123 | ```javascript |
|
122 | Cookies.get('name'); // => '{"foo":"bar"}' |
124 | Cookies.get('name'); // => '{"foo":"bar"}' |
|
123 | ``` |
125 | ``` |
|
124 | |
126 | |
|
125 | ```javascript |
127 | ```javascript |
|
126 | Cookies.get(); // => { name: '{"foo":"bar"}' } |
128 | Cookies.get(); // => { name: '{"foo":"bar"}' } |
|
127 | ``` |
129 | ``` |
|
128 | |
130 | |
|
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`: |
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`: |
|
130 | |
132 | |
|
131 | ```javascript |
133 | ```javascript |
|
132 | Cookies.getJSON('name'); // => { foo: 'bar' } |
134 | Cookies.getJSON('name'); // => { foo: 'bar' } |
|
133 | ``` |
135 | ``` |
|
134 | |
136 | |
|
135 | ```javascript |
137 | ```javascript |
|
136 | Cookies.getJSON(); // => { name: { foo: 'bar' } } |
138 | Cookies.getJSON(); // => { name: { foo: 'bar' } } |
|
137 | ``` |
139 | ``` |
|
138 | |
140 | |
|
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* |
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* |
|
140 | |
142 | |
|
141 | ## Encoding |
143 | ## Encoding |
|
142 | |
144 | |
|
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). |
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). |
|
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. |
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. |
|
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). |
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). |
|
146 | |
148 | |
|
147 | ## Cookie Attributes |
149 | ## Cookie Attributes |
|
148 | |
150 | |
|
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. |
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. |
|
150 | |
152 | |
|
151 | ### expires |
153 | ### expires |
|
152 | |
154 | |
|
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. |
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. |
|
154 | |
156 | |
|
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). |
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). |
|
156 | |
158 | |
|
157 | **Default:** Cookie is removed when the user closes the browser. |
159 | **Default:** Cookie is removed when the user closes the browser. |
|
158 | |
160 | |
|
159 | **Examples:** |
161 | **Examples:** |
|
160 | |
162 | |
|
161 | ```javascript |
163 | ```javascript |
|
162 | Cookies.set('name', 'value', { expires: 365 }); |
164 | Cookies.set('name', 'value', { expires: 365 }); |
|
163 | Cookies.get('name'); // => 'value' |
165 | Cookies.get('name'); // => 'value' |
|
164 | Cookies.remove('name'); |
166 | Cookies.remove('name'); |
|
165 | ``` |
167 | ``` |
|
166 | |
168 | |
|
167 | ### path |
169 | ### path |
|
168 | |
170 | |
|
169 | A [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) indicating the path where the cookie is visible. |
171 | A [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) indicating the path where the cookie is visible. |
|
170 | |
172 | |
|
171 | **Default:** `/` |
173 | **Default:** `/` |
|
172 | |
174 | |
|
173 | **Examples:** |
175 | **Examples:** |
|
174 | |
176 | |
|
175 | ```javascript |
177 | ```javascript |
|
176 | Cookies.set('name', 'value', { path: '' }); |
178 | Cookies.set('name', 'value', { path: '' }); |
|
177 | Cookies.get('name'); // => 'value' |
179 | Cookies.get('name'); // => 'value' |
|
178 | Cookies.remove('name', { path: '' }); |
180 | Cookies.remove('name', { path: '' }); |
|
179 | ``` |
181 | ``` |
|
180 | |
182 | |
|
181 | **Note regarding Internet Explorer:** |
183 | **Note regarding Internet Explorer:** |
|
182 | |
184 | |
|
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. |
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. |
|
184 | |
186 | |
|
185 | (From [Internet Explorer Cookie Internals (FAQ)](http://blogs.msdn.com/b/ieinternals/archive/2009/08/20/wininet-ie-cookie-internals-faq.aspx)) |
187 | (From [Internet Explorer Cookie Internals (FAQ)](http://blogs.msdn.com/b/ieinternals/archive/2009/08/20/wininet-ie-cookie-internals-faq.aspx)) |
|
186 | |
188 | |
|
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). |
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). |
|
188 | |
190 | |
|
189 | ### domain |
191 | ### domain |
|
190 | |
192 | |
|
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. |
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. |
|
192 | |
194 | |
|
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). |
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). |
|
194 | |
196 | |
|
195 | **Examples:** |
197 | **Examples:** |
|
196 | |
198 | |
|
197 | Assuming a cookie that is being created on `site.com`: |
199 | Assuming a cookie that is being created on `site.com`: |
|
198 | |
200 | |
|
199 | ```javascript |
201 | ```javascript |
|
200 | Cookies.set('name', 'value', { domain: 'subdomain.site.com' }); |
202 | Cookies.set('name', 'value', { domain: 'subdomain.site.com' }); |
|
201 | Cookies.get('name'); // => undefined (need to read at 'subdomain.site.com') |
203 | Cookies.get('name'); // => undefined (need to read at 'subdomain.site.com') |
|
202 | ``` |
204 | ``` |
|
203 | |
205 | |
|
204 | **Note regarding Internet Explorer default behavior:** |
206 | **Note regarding Internet Explorer default behavior:** |
|
205 | |
207 | |
|
206 | > Q3: If I don’t specify a DOMAIN attribute (for) a cookie, IE sends it to all nested subdomains anyway? |
208 | > 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. |
209 | > 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. |
210 | > Internet Explorer differs from other browsers in this regard. |
|
209 | |
211 | |
|
210 | (From [Internet Explorer Cookie Internals (FAQ)](http://blogs.msdn.com/b/ieinternals/archive/2009/08/20/wininet-ie-cookie-internals-faq.aspx)) |
212 | (From [Internet Explorer Cookie Internals (FAQ)](http://blogs.msdn.com/b/ieinternals/archive/2009/08/20/wininet-ie-cookie-internals-faq.aspx)) |
|
211 | |
213 | |
|
212 | This means that if you omit the `domain` attribute, it will be visible for a subdomain in IE. |
214 | This means that if you omit the `domain` attribute, it will be visible for a subdomain in IE. |
|
213 | |
215 | |
|
214 | ### secure |
216 | ### secure |
|
215 | |
217 | |
|
216 | Either `true` or `false`, indicating if the cookie transmission requires a secure protocol (https). |
218 | Either `true` or `false`, indicating if the cookie transmission requires a secure protocol (https). |
|
217 | |
219 | |
|
218 | **Default:** No secure protocol requirement. |
220 | **Default:** No secure protocol requirement. |
|
219 | |
221 | |
|
220 | **Examples:** |
222 | **Examples:** |
|
221 | |
223 | |
|
222 | ```javascript |
224 | ```javascript |
|
223 | Cookies.set('name', 'value', { secure: true }); |
225 | Cookies.set('name', 'value', { secure: true }); |
|
224 | Cookies.get('name'); // => 'value' |
226 | Cookies.get('name'); // => 'value' |
|
225 | Cookies.remove('name', { secure: true }); |
227 | Cookies.remove('name', { secure: true }); |
|
226 | ``` |
228 | ``` |
|
227 | |
229 | |
|
228 | ## Converters |
230 | ## Converters |
|
229 | |
231 | |
|
230 | ### Read |
232 | ### Read |
|
231 | |
233 | |
|
232 | Create a new instance of the api that overrides the default decoding implementation. |
234 | 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. |
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. |
|
234 | The returning String will be used as the cookie value. |
236 | The returning String will be used as the cookie value. |
|
235 | |
237 | |
|
236 | Example from reading one of the cookies that can only be decoded using the `escape` function: |
238 | Example from reading one of the cookies that can only be decoded using the `escape` function: |
|
237 | |
239 | |
|
238 | ```javascript |
240 | ```javascript |
|
239 | document.cookie = 'escaped=%u5317'; |
241 | document.cookie = 'escaped=%u5317'; |
|
240 | document.cookie = 'default=%E5%8C%97'; |
242 | document.cookie = 'default=%E5%8C%97'; |
|
241 | var cookies = Cookies.withConverter(function (value, name) { |
243 | var cookies = Cookies.withConverter(function (value, name) { |
|
242 | if ( name === 'escaped' ) { |
244 | if ( name === 'escaped' ) { |
|
243 | return unescape(value); |
245 | return unescape(value); |
|
244 | } |
246 | } |
|
245 | }); |
247 | }); |
|
246 | cookies.get('escaped'); // 北 |
248 | cookies.get('escaped'); // 北 |
|
247 | cookies.get('default'); // 北 |
249 | cookies.get('default'); // 北 |
|
248 | cookies.get(); // { escaped: '北', default: '北' } |
250 | cookies.get(); // { escaped: '北', default: '北' } |
|
249 | ``` |
251 | ``` |
|
250 | |
252 | |
|
251 | ### Write |
253 | ### Write |
|
252 | |
254 | |
|
253 | Create a new instance of the api that overrides the default encoding implementation: |
255 | Create a new instance of the api that overrides the default encoding implementation: |
|
254 | |
256 | |
|
255 | ```javascript |
257 | ```javascript |
|
256 | Cookies.withConverter({ |
258 | Cookies.withConverter({ |
|
257 | read: function (value, name) { |
259 | read: function (value, name) { |
|
258 | // Read converter |
260 | // Read converter |
|
259 | }, |
261 | }, |
|
260 | write: function (value, name) { |
262 | write: function (value, name) { |
|
261 | // Write converter |
263 | // Write converter |
|
262 | } |
264 | } |
|
263 | }); |
265 | }); |
|
264 | ``` |
266 | ``` |
|
265 | |
267 | |
|
266 | ## Server-side integration |
268 | ## Server-side integration |
|
267 | |
269 | |
|
268 | Check out the [Servers Docs](SERVER_SIDE.md) |
270 | Check out the [Servers Docs](SERVER_SIDE.md) |
|
269 | |
271 | |
|
270 | ## Contributing |
272 | ## Contributing |
|
271 | |
273 | |
|
272 | Check out the [Contributing Guidelines](CONTRIBUTING.md) |
274 | Check out the [Contributing Guidelines](CONTRIBUTING.md) |
|
- | 275 | |
||
- | 276 | ## Security |
||
- | 277 | |
||
- | 278 | For vulnerability reports, send an e-mail to `jscookie at gmail dot com` |
||
273 | |
279 | |
|
274 | ## Manual release steps |
280 | ## Manual release steps |
|
275 | |
281 | |
|
276 | * Increment the "version" attribute of `package.json` |
282 | * Increment the "version" attribute of `package.json` |
|
277 | * Increment the version number in the `src/js.cookie.js` file |
283 | * Increment the version number in the `src/js.cookie.js` file |
|
278 | * Commit with the message "Release version x.x.x" |
284 | * Commit with the message "Release version x.x.x" |
|
279 | * Create version tag in git |
285 | * Create version tag in git |
|
280 | * Create a github release and upload the minified file |
286 | * Create a github release and upload the minified file |
|
281 | * Change the `latest` tag pointer to the latest commit |
287 | * Change the `latest` tag pointer to the latest commit |
|
282 | * `git tag -fa latest` |
288 | * `git tag -f latest` |
|
283 | * `git push <remote> :refs/tags/latest` |
289 | * `git push <remote> :refs/tags/latest` |
|
284 | * Commit with the message "Prepare for the next development iteration" |
290 | * `git push origin master --tags` |
|
285 | * Release on npm |
291 | * Release on npm |
|
286 | |
292 | |
|
287 | ## Authors |
293 | ## Authors |
|
288 | |
294 | |
|
289 | * [Klaus Hartl](https://github.com/carhartl) |
295 | * [Klaus Hartl](https://github.com/carhartl) |
|
290 | * [Fagner Brack](https://github.com/FagnerMartinsBrack) |
296 | * [Fagner Brack](https://github.com/FagnerMartinsBrack) |
|
291 | * And awesome [contributors](https://github.com/js-cookie/js-cookie/graphs/contributors) |
297 | * And awesome [contributors](https://github.com/js-cookie/js-cookie/graphs/contributors) |
|
292 | |
298 | |