scratch – Blame information for rev 125

Subversion Repositories:
Rev:
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)