Skip to content

HTTPS clone URL

Subversion checkout URL

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