Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 161 lines (98 sloc) 5.095 kb
6d5b919 @FagnerMartinsBrack Add notice
FagnerMartinsBrack authored
1 # IMPORTANT!
2
636c27d @FagnerMartinsBrack Make the notice clearer and more direct
FagnerMartinsBrack authored
3 This project was moved to https://github.com/js-cookie/js-cookie, check [the discussion](https://github.com/carhartl/jquery-cookie/issues/349).
6d5b919 @FagnerMartinsBrack Add notice
FagnerMartinsBrack authored
4
7984c94 @carhartl Adding Code Climate badge.
authored
5 # jquery.cookie [![Build Status](https://travis-ci.org/carhartl/jquery-cookie.png?branch=master)](https://travis-ci.org/carhartl/jquery-cookie) [![Code Climate](https://codeclimate.com/github/carhartl/jquery-cookie.png)](https://codeclimate.com/github/carhartl/jquery-cookie)
5de116f @carhartl another rdoc fix
authored
6
35377d7 @carhartl README instead of inline documentation
authored
7 A simple, lightweight jQuery plugin for reading, writing and deleting cookies.
8
636c27d @FagnerMartinsBrack Make the notice clearer and more direct
FagnerMartinsBrack authored
9 **If you're viewing this, you're reading the documentation for the old repository.
10 [View documentation for the latest backwards compatible release (1.5.1).](https://github.com/js-cookie/js-cookie/tree/v1.5.1)**
433a106 @carhartl Adding note about the documentation in master vs latest release
authored
11
ac265dc @carhartl Moving build status matrix below description. [ci skip]
authored
12 ## Build Status Matrix
13
14 [![Selenium Test Status](https://saucelabs.com/browser-matrix/jquery-cookie.svg)](https://saucelabs.com/u/jquery-cookie)
15
280132f @carhartl using markdown
authored
16 ## Installation
b34aebd @carhartl some more tweaks for the readme
authored
17
18 Include script *after* the jQuery library (unless you are packaging scripts somehow else):
19
db77624 @carhartl Adding syntax highlighting for remaining code blocks in the README.
authored
20 ```html
21 <script src="/path/to/jquery.cookie.js"></script>
22 ```
b34aebd @carhartl some more tweaks for the readme
authored
23
b7edc7c @carhartl Fixing typo, more explanation
authored
24 **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
25 in Internet Explorer on Windows 7 for instance (because of the wrong MIME type). Bottom line: GitHub is not a CDN.
d176f57 @carhartl Adding note about not to include the plugin directly from GitHub, seems ...
authored
26
6e175cd @gaastonsr Add CommonJS support
gaastonsr authored
27 The plugin can also be loaded as AMD or CommonJS module.
a1456e1 @carhartl Mention AMD in installation section
authored
28
280132f @carhartl using markdown
authored
29 ## Usage
35377d7 @carhartl README instead of inline documentation
authored
30
b34aebd @carhartl some more tweaks for the readme
authored
31 Create session cookie:
32
db77624 @carhartl Adding syntax highlighting for remaining code blocks in the README.
authored
33 ```javascript
e3a19c3 @carhartl Improving Readme
authored
34 $.cookie('name', 'value');
db77624 @carhartl Adding syntax highlighting for remaining code blocks in the README.
authored
35 ```
35377d7 @carhartl README instead of inline documentation
authored
36
b34aebd @carhartl some more tweaks for the readme
authored
37 Create expiring cookie, 7 days from then:
38
db77624 @carhartl Adding syntax highlighting for remaining code blocks in the README.
authored
39 ```javascript
e3a19c3 @carhartl Improving Readme
authored
40 $.cookie('name', 'value', { expires: 7 });
db77624 @carhartl Adding syntax highlighting for remaining code blocks in the README.
authored
41 ```
35377d7 @carhartl README instead of inline documentation
authored
42
e60f7e8 @carhartl some more documentation tweaking
authored
43 Create expiring cookie, valid across entire site:
b34aebd @carhartl some more tweaks for the readme
authored
44
db77624 @carhartl Adding syntax highlighting for remaining code blocks in the README.
authored
45 ```javascript
e3a19c3 @carhartl Improving Readme
authored
46 $.cookie('name', 'value', { expires: 7, path: '/' });
db77624 @carhartl Adding syntax highlighting for remaining code blocks in the README.
authored
47 ```
35377d7 @carhartl README instead of inline documentation
authored
48
b34aebd @carhartl some more tweaks for the readme
authored
49 Read cookie:
50
db77624 @carhartl Adding syntax highlighting for remaining code blocks in the README.
authored
51 ```javascript
e3a19c3 @carhartl Improving Readme
authored
52 $.cookie('name'); // => "value"
53 $.cookie('nothing'); // => undefined
db77624 @carhartl Adding syntax highlighting for remaining code blocks in the README.
authored
54 ```
47c76f8 @carhartl Adding lint task, adding default, so a simple Running "lint:files" (...
authored
55
c32ed09 @carhartl Calling $.cookie without arguments returns all available cookies as obje...
authored
56 Read all available cookies:
57
db77624 @carhartl Adding syntax highlighting for remaining code blocks in the README.
authored
58 ```javascript
e3a19c3 @carhartl Improving Readme
authored
59 $.cookie(); // => { "name": "value" }
db77624 @carhartl Adding syntax highlighting for remaining code blocks in the README.
authored
60 ```
35377d7 @carhartl README instead of inline documentation
authored
61
e39cf51 @carhartl Some formatting fixes and cleanup, adding to changelog
authored
62 Delete cookie:
84a7de2 @FagnerMartinsBrack $.removeCookie
FagnerMartinsBrack authored
63
db77624 @carhartl Adding syntax highlighting for remaining code blocks in the README.
authored
64 ```javascript
e3a19c3 @carhartl Improving Readme
authored
65 // Returns true when cookie was successfully deleted, otherwise false
66 $.removeCookie('name'); // => true
67 $.removeCookie('nothing'); // => false
68
69 // Need to use the same attributes (path, domain) as what the cookie was written with
70 $.cookie('name', 'value', { path: '/' });
71 // This won't work!
72 $.removeCookie('name'); // => false
73 // This will work!
74 $.removeCookie('name', { path: '/' }); // => true
db77624 @carhartl Adding syntax highlighting for remaining code blocks in the README.
authored
75 ```
84a7de2 @FagnerMartinsBrack $.removeCookie
FagnerMartinsBrack authored
76
e60f7e8 @carhartl some more documentation tweaking
authored
77 *Note: when deleting a cookie, you must pass the exact same path, domain and secure options that were used to set the cookie, unless you're relying on the default options that is.*
6fb0191 @coryschires Add a note about gotcha when clearing cookies
coryschires authored
78
796abd6 @carhartl Adding raw and json configuration (replacing former option), closes #89
authored
79 ## Configuration
80
4b14333 @carhartl Adding a note about a potential path + filename issue in Internet Explor...
authored
81 ### raw
82
c2b8055 @carhartl Seems better the other way round
authored
83 By default the cookie value is encoded/decoded when writing/reading, using `encodeURIComponent`/`decodeURIComponent`. Bypass this by setting raw to true:
84
db77624 @carhartl Adding syntax highlighting for remaining code blocks in the README.
authored
85 ```javascript
86 $.cookie.raw = true;
87 ```
ee1d298 @carhartl Improving documentation, closes #109, closes #112
authored
88
4b14333 @carhartl Adding a note about a potential path + filename issue in Internet Explor...
authored
89 ### json
90
c2b8055 @carhartl Seems better the other way round
authored
91 Turn on automatic storage of JSON objects passed as the cookie value. Assumes `JSON.stringify` and `JSON.parse`:
ee1d298 @carhartl Improving documentation, closes #109, closes #112
authored
92
db77624 @carhartl Adding syntax highlighting for remaining code blocks in the README.
authored
93 ```javascript
94 $.cookie.json = true;
95 ```
ee1d298 @carhartl Improving documentation, closes #109, closes #112
authored
96
796abd6 @carhartl Adding raw and json configuration (replacing former option), closes #89
authored
97 ## Cookie Options
35377d7 @carhartl README instead of inline documentation
authored
98
ee1d298 @carhartl Improving documentation, closes #109, closes #112
authored
99 Cookie attributes can be set globally by setting properties of the `$.cookie.defaults` object or individually for each call to `$.cookie()` by passing a plain object to the options argument. Per-call options override the default options.
cd97d43 @kswedberg updated readme
kswedberg authored
100
0b9c6ca @carhartl Moving paragraph to the right place [ci skip]
authored
101 ### expires
102
35377d7 @carhartl README instead of inline documentation
authored
103 expires: 365
104
e60f7e8 @carhartl some more documentation tweaking
authored
105 Define lifetime of the cookie. Value can be a `Number` which will be interpreted as days from time of creation or a `Date` object. If omitted, the cookie becomes a session cookie.
35377d7 @carhartl README instead of inline documentation
authored
106
4b14333 @carhartl Adding a note about a potential path + filename issue in Internet Explor...
authored
107 ### path
108
b794fe7 @carhartl more rdoc fixes
authored
109 path: '/'
35377d7 @carhartl README instead of inline documentation
authored
110
72e8738 @carhartl Improving the documentation a bit, mostly by rearranging text.
authored
111 Define the path where the cookie is valid. *By default the path of the cookie is the path of the page where the cookie was created (standard browser behavior).* If you want to make it available for instance across the entire domain use `path: '/'`. Default: path of page where the cookie was created.
35377d7 @carhartl README instead of inline documentation
authored
112
4b14333 @carhartl Adding a note about a potential path + filename issue in Internet Explor...
authored
113 **Note regarding Internet Explorer:**
114
115 > 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.
116
117 (From [Internet Explorer Cookie Internals (FAQ)](http://blogs.msdn.com/b/ieinternals/archive/2009/08/20/wininet-ie-cookie-internals-faq.aspx))
118
119 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).
120
121 ### domain
122
35377d7 @carhartl README instead of inline documentation
authored
123 domain: 'example.com'
124
72e8738 @carhartl Improving the documentation a bit, mostly by rearranging text.
authored
125 Define the domain where the cookie is valid. Default: domain of page where the cookie was created.
35377d7 @carhartl README instead of inline documentation
authored
126
4b14333 @carhartl Adding a note about a potential path + filename issue in Internet Explor...
authored
127 ### secure
128
35377d7 @carhartl README instead of inline documentation
authored
129 secure: true
130
72e8738 @carhartl Improving the documentation a bit, mostly by rearranging text.
authored
131 If true, the cookie transmission requires a secure protocol (https). Default: `false`.
35377d7 @carhartl README instead of inline documentation
authored
132
64eb7b7 @carhartl Implemented conversion function as optional last argument for reading. A...
authored
133 ## Converters
134
3caf209 @carhartl Preparing for 1.4.0 release
authored
135 Provide a conversion function as optional last argument for reading, in order to change the cookie's value
64eb7b7 @carhartl Implemented conversion function as optional last argument for reading. A...
authored
136 to a different representation on the fly.
137
138 Example for parsing a value into a number:
139
140 ```javascript
141 $.cookie('foo', '42');
142 $.cookie('foo', Number); // => 42
143 ```
144
145 Dealing with cookies that have been encoded using `escape` (3rd party cookies):
146
147 ```javascript
148 $.cookie.raw = true;
149 $.cookie('foo', unescape);
150 ```
151
152 You can pass an arbitrary conversion function.
153
bd134a7 @carhartl Changing headline
authored
154 ## Contributing
155
9b5607e @FagnerMartinsBrack Contribution guidelines enhancement
FagnerMartinsBrack authored
156 Check out the [Contributing Guidelines](CONTRIBUTING.md)
35377d7 @carhartl README instead of inline documentation
authored
157
c388c26 @carhartl fixed last headline
authored
158 ## Authors
35377d7 @carhartl README instead of inline documentation
authored
159
280132f @carhartl using markdown
authored
160 [Klaus Hartl](https://github.com/carhartl)
Something went wrong with that request. Please try again.