Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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