scratch – Blame information for rev 58

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  
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)