← Back to branch summary

~ubuntu-branches/ubuntu/raring/maas/raring-updates

« back to all changes in this revision

Viewing changes to src/maasserver/static/jslibs/yui/3.4.1/docs/cookie/index.html

  • Committer: Package Import Robot
  • Author(s): Andres Rodriguez
  • Date: 2012-07-03 17:42:37 UTC
  • mfrom: (1.1.13)
  • Revision ID: package-import@ubuntu.com-20120703174237-p8l0keuuznfg721k
Tags: 0.1+bzr709+dfsg-0ubuntu1
* New Upstream release
* debian/control:
  - Depends on python-celery, python-tempita, libjs-yui3-{full,min},
    libjs-raphael
* debian/maas.install:
  - Install apiclient, celeryconfig.py, maas-import-pxe-files, preseeds_v2.
  - Update to install various files from chroot, rather tha manually copy
    them from the source.
* debian/maas.links: symlink celeryconfig.py
* debian/maas.maas-celery.upstart: Add job.
* debian/rules:
  - Install celery upstart job.
  - Do not install jslibs as packages are now used.
  - Drop copying of maas_local_settings_sample.py as source now ships
    a maas_local_settings.py
* debian/patches:
  - 04-maas-http-fix.patch: Drop. Merged upstream.
  - 01-fix-database-settings.patch: Refreshed.
  - 99_enums_js.patch: Added until creation of enum.js / build process
    is fixed.
* debian/maas.postinst: Update bzr version to correctly handle upgrades.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/maasserver/static/jslibs/yui/3.4.1/docs/cookie/index.html
1
 
<!DOCTYPE html>
2
 
<html lang="en">
3
 
<head>
4
 
    <meta charset="utf-8">
5
 
    <title>Cookie Utility</title>
6
 
    <link rel="stylesheet" href="http://yui.yahooapis.com/3.4.0pr3/build/cssgrids/grids-min.css">
7
 
    <link rel="stylesheet" href="../assets/css/main.css">
8
 
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
9
 
    <script src="../../build/yui/yui-min.js"></script>
10
 
</head>
11
 
<body>
12
 
 
13
 
<div id="doc">
14
 
    <h1>Cookie Utility</h1>
15
 
 
16
 
    
17
 
        <a href="#toc" class="jump">Jump to Table of Contents</a>
18
 
    
19
 
 
20
 
    <div class="yui3-g">
21
 
        <div id="main" class="yui3-u">
22
 
            <div class="content"><div class="intro">
23
 
    <p>The YUI Cookie utility provides a simple API for interacting with cookies, including the creation and manipulation of subcookies.</p>
24
 
 
25
 
    <p><strong>Note about HTTPOnly Cookies:</strong> HTTPOnly cookies are cookies that may be set either by JavaScript or by the server but cannot be read from JavaScript. The YUI Cookie utility does not provide support for setting HTTPOnly cookies because browser support is not well-established and there is no fallback mechanism. Setting an HTTPOnly cookie on a browser that doesn't support it is the same as setting any other cookie (no error is thrown). When all A-grade browsers support setting HTTPOnly cookies by JavaScript, we will revisit adding support for it in the Cookie utility.</p>
26
 
</div>
27
 
 
28
 
<h2 id="getting-started">Getting Started</h2>
29
 
 
30
 
<p>
31
 
To include the source files for Cookie Utility and its dependencies, first load
32
 
the YUI seed file if you haven't already loaded it.
33
 
</p>
34
 
 
35
 
<pre class="code prettyprint">&lt;script src=&quot;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;3.4.1&#x2F;build&#x2F;yui&#x2F;yui-min.js&quot;&gt;&lt;&#x2F;script&gt;</pre>
36
 
 
37
 
 
38
 
<p>
39
 
Next, create a new YUI instance for your application and populate it with the
40
 
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
41
 
YUI will automatically load any dependencies required by the modules you
42
 
specify.
43
 
</p>
44
 
 
45
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a new YUI instance and populate it with the required modules.
46
 
YUI().use(&#x27;cookie&#x27;, function (Y) {
47
 
    &#x2F;&#x2F; Cookie Utility is available and ready for use. Add implementation
48
 
    &#x2F;&#x2F; code here.
49
 
});</pre>
50
 
 
51
 
 
52
 
<p>
53
 
For more information on creating YUI instances and on the
54
 
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
55
 
documentation for the <a href="../yui/index.html">YUI Global object</a>.
56
 
</p>
57
 
 
58
 
 
59
 
<h2 id="using">Using the Cookie Utility</h2>
60
 
 
61
 
<h3 id="create">Creating Cookies</h3>
62
 
 
63
 
<p>The simplest way to create a cookie is to provide a name and a value to the <code>set()</code> method:</p>
64
 
 
65
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
66
 
YUI().use(&#x27;cookie&#x27;, function(Y) {
67
 
    Y.Cookie.set(&quot;name&quot;, &quot;value&quot;);
68
 
});</pre>
69
 
 
70
 
 
71
 
<p>This example creates a cookie called &quot;name&quot; that has a value of &quot;value&quot;. Since
72
 
this cookie is created with all of the default settings, it becomes a session cookie.</p>
73
 
 
74
 
<p>There is a third argument for <code>set()</code>, which is an object containing additional settings for the cookie. To create a persistent cookie, you can specify an expiration date by supplying a <code>Date</code> object:</p>
75
 
 
76
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
77
 
YUI().use(&#x27;cookie&#x27;, function(Y) {
78
 
    Y.Cookie.set(&quot;name&quot;, &quot;value&quot;, { expires: new Date(&quot;January 12, 2025&quot;) });
79
 
});</pre>
80
 
 
81
 
 
82
 
<p>By providing an &quot;expires&quot; option in the third argument, the cookie persists until the given date. In this example,
83
 
the cookie will remain until January 12, 2025. The value for &quot;expires&quot; must be a <code>Date</code> object, otherwise
84
 
it is ignored.</p>
85
 
 
86
 
<p>It's possible to restrict access to a cookie by setting path and/or domain information. Setting a path on the cookie restricts access to pages that match that path; setting a domain restricts access to pages on a given domain (typically used to allow cookie access across subdomains). Both options can be easily set using the &quot;path&quot; and &quot;domain&quot; options:</p>
87
 
 
88
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
89
 
YUI().use(&#x27;cookie&#x27;, function(Y) {
90
 
    Y.Cookie.set(&quot;name&quot;, &quot;value&quot;, {
91
 
        path: &quot;&#x2F;&quot;,           &#x2F;&#x2F;all pages
92
 
        domain: &quot;yahoo.com&quot;   &#x2F;&#x2F;any subdomain of yahoo.com, including www.yahoo.com
93
 
    });
94
 
});</pre>
95
 
 
96
 
 
97
 
<p>In this example, a cookie is created that can be accessed from all pages on a yahoo.com subdomain. This cookie would
98
 
then be accessible from pages on <a href="http://sports.yahoo.com">sports.yahoo.com</a> as well as <a href="http://www.yahoo.com">www.yahoo.com</a>.
99
 
The &quot;path&quot; and &quot;domain&quot; options need not be used together; they may be used independently as well.</p>
100
 
 
101
 
<p>The last option is &quot;secure&quot;, which indicates that the cookie should only be accessible via SSL on a page
102
 
using the HTTPS protocol. All other aspects of the cookie remain the same based on the other options provided. To set a
103
 
secure cookie, use the &quot;secure&quot; option:</p>
104
 
 
105
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
106
 
YUI().use(&#x27;cookie&#x27;, function(Y){
107
 
    Y.Cookie.set(&quot;name&quot;, &quot;value&quot;, { secure: true });
108
 
});</pre>
109
 
 
110
 
 
111
 
<p>This code creates a secure cookie by setting the &quot;secure&quot; option to <code>true</code>. Note that this will only work if the page calling this code uses the HTTPS protocol, otherwise the cookie will be created with default options.</p>
112
 
 
113
 
<p>There is one more option called &quot;raw&quot;. When this option is specified, the cookie will not be URL-encoded before being set. Setting a &quot;raw&quot; cookie typically means that you have specialized server-side logic to deal with cookies that aren't URL-encoded. This is considered an advanced option that should only be used when necessary. Example usage:</p>
114
 
 
115
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
116
 
YUI().use(&#x27;cookie&#x27;, function(Y){
117
 
    Y.Cookie.set(&quot;name&quot;, &quot;value&quot;, { raw: true });
118
 
});</pre>
119
 
 
120
 
 
121
 
<h3 id="read">Reading Cookies</h3>
122
 
 
123
 
<p>The <code>get()</code> method retrieves cookies that are accessible by the current page. If a cookie doesn't exist, <code>get()</code> returns <code>null</code>.</p>
124
 
 
125
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
126
 
YUI().use(&#x27;cookie&#x27;, function(Y){
127
 
    var value = Y.Cookie.get(&quot;name&quot;);
128
 
});</pre>
129
 
 
130
 
 
131
 
<p>This example retrieves the cookie called &quot;name&quot; and stores its value in the variable <code>value</code>. By default, values returned by <code>get()</code> are strings (if the cookie exists) or <code>null</code> (if the cookie doesn't exist). You can change the return value by providing a conversion function as the second argument. For example, to return a number, you can pass in the native <code>Number()</code> function:</p>
132
 
 
133
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
134
 
YUI().use(&#x27;cookie&#x27;, function(Y){
135
 
    var value = Y.Cookie.get(&quot;age&quot;, Number);
136
 
});</pre>
137
 
 
138
 
 
139
 
<p>In this code, the returned cookie value will be a number if the cookie exists (it will still be <code>null</code> if the cookie doesn't exist). Other native functions that convert values are <code>Boolean()</code> and <code>Date</code>, or you can define your own conversion function:</p>
140
 
 
141
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
142
 
YUI().use(&#x27;cookie&#x27;, function(Y){
143
 
    var value = Y.Cookie.get(&quot;code&quot;, function(stringValue){
144
 
        return parseInt(stringValue, 16);   &#x2F;&#x2F; Create a number from a hexadecimal code
145
 
    });
146
 
});</pre>
147
 
 
148
 
 
149
 
<p>Conversion functions accept a single argument, the string value of the cookie, and must return a value. In this example, the conversion function expects a hexadecimal code to be returned and passes it into <code>parseInt()</code> to convert the value into a number. Note that the conversion function is never called if the cookie doesn't exist (<code>get()</code> always returns <code>null</code> when the cookie doesn't exist).</p>
150
 
                    
151
 
<p>The second argument can optionally be an object if you'd like to read a raw cookie. As with, writing cookies, it's possible to read a cookie without URL-decoding the value. To specify this, the second argument should be an object, such as:</p>
152
 
 
153
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
154
 
YUI().use(&#x27;cookie&#x27;, function(Y){
155
 
    var value = Y.Cookie.get(&quot;code&quot;, { raw: true });
156
 
});</pre>
157
 
 
158
 
                    
159
 
<p>If you'd like to use a converter on a raw cookie, you can specify this using the &quot;converter&quot; option:</p>
160
 
 
161
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
162
 
YUI().use(&#x27;cookie&#x27;, function(Y){
163
 
    var value = Y.Cookie.get(&quot;code&quot;, {
164
 
        raw: true,
165
 
        converter: function(stringValue){
166
 
            return parseInt(stringValue, 16);   &#x2F;&#x2F; Create a number from a hexadecimal code
167
 
        }
168
 
    });
169
 
});</pre>
170
 
 
171
 
 
172
 
<h3 id="delete">Deleting Cookies</h3>
173
 
 
174
 
<p>When a cookie is no longer need, it can be removed from the browser by calling the <code>remove()</code> method. This method takes two arguments: the name of the cookie to remove and an optional cookie options object. A cookie created with specific options can only be deleted by specifying the same options. For instance, a cookie created with a <code>domain</code> property of &quot;yahoo.com&quot; can only be deleted by also specifying the <code>domain</code> property as &quot;yahoo.com&quot;. Examples:</p>
175
 
 
176
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
177
 
YUI().use(&#x27;cookie&#x27;, function(Y){
178
 
    &#x2F;&#x2F;delete the cookie named &quot;code&quot;
179
 
    Y.Cookie.remove(&quot;code&quot;);
180
 
 
181
 
    &#x2F;&#x2F;delete the cookie named &quot;info&quot; on the &quot;yahoo.com&quot; domain
182
 
    Y.Cookie.remove(&quot;info&quot;, { domain: &quot;yahoo.com&quot; });
183
 
 
184
 
    &#x2F;&#x2F;delete a secure cookie named &quot;username&quot;
185
 
    Y.Cookie.remove(&quot;username&quot;, { secure: true });                    
186
 
});</pre>
187
 
 
188
 
 
189
 
<h3 id="sub">Subcookies</h3>
190
 
 
191
 
<p>Each browser has a limit to the number of cookies that can be set per domain. These limits can be problematic for domains with different sites under different subdomains. Since cookie name-value pairs are rarely large enough to reach the byte limit for an individual cookie, it represents an opportunity to store multiple name-value pairs in a single cookie; these are called subcookies.</p>
192
 
 
193
 
<p>A subcookie string looks similar to a URL and takes the following form:</p>
194
 
 
195
 
<p><code>cookiename=name1=value1&amp;name2=value2&amp;name3=value3</code></p>
196
 
 
197
 
<p>The Cookie utility supports this style of subcookies to allow multiple values to be stored in a single cookie. To set a subcookie value, use the <code>setSub()</code> method. This method accepts four arguments: the cookie name, the subcookie name, the subcookie value, and an optional options object. Note that the options object works on the entire cookie, it is not specific to the subcookie.</p>
198
 
 
199
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
200
 
YUI().use(&#x27;cookie&#x27;, function(Y){
201
 
 
202
 
    &#x2F;&#x2F;set a cookie named &quot;name&quot; with a subcookie named &quot;subname&quot; whose value is &quot;value&quot;
203
 
    Y.Cookie.setSub(&quot;name&quot;, &quot;subname&quot;, &quot;value&quot;);
204
 
 
205
 
    &#x2F;&#x2F;set a second subcookie on &quot;name&quot;, with a name of &quot;subname2&quot; and a value of &quot;value2&quot;
206
 
    Y.Cookie.setSub(&quot;name&quot;, &quot;subname2&quot;, &quot;value2&quot;);
207
 
 
208
 
    &#x2F;&#x2F;set subcookie on the &quot;yahoo.com&quot; domain
209
 
    Y.Cookie.setSub(&quot;info&quot;, &quot;age&quot;, 22, { domain: &quot;yahoo.com&quot; });
210
 
 
211
 
    &#x2F;&#x2F;set subcookie to a secure cookie named &quot;user&quot;
212
 
    Y.Cookie.setSub(&quot;user&quot;, &quot;name&quot;, &quot;ace123&quot;, { secure:true });                        
213
 
});</pre>
214
 
 
215
 
 
216
 
<p>It's possible to set the entire contents of a subcookie by using the <code>setSubs()</code> method, which accepts three arguments:
217
 
the name of the cookie, and object containing name-value pairs, and an optional cookie options object. For instance, this code
218
 
sets three subcookies at once:</p>
219
 
 
220
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
221
 
YUI().use(&#x27;cookie&#x27;, function(Y){
222
 
 
223
 
    var data = {
224
 
        name: &quot;ace123&quot;,
225
 
        age: 22,
226
 
        track: true
227
 
    };                    
228
 
 
229
 
    &#x2F;&#x2F;set a cookie named &quot;user&quot; with subcookies
230
 
    Y.Cookie.setSubs(&quot;user&quot;, data);
231
 
 
232
 
});</pre>
233
 
 
234
 
 
235
 
<p>Note that calls to <code>setSubs()</code> will always completely overwrite the cookie.</p>
236
 
 
237
 
<p>To retrieve subcookie values, there are two methods. The first is <code>getSub()</code>, which retrieves a single subcookie value.
238
 
This method accepts three arguments: the cookie name, the subcookie name, and an optional converter function. As with <code>get()</code>,
239
 
the converter function changes the data or type of data retrieved from the cookie before it's returned (and isn't called at all
240
 
if the cookie or subcookie doesn't exist):</p>
241
 
 
242
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
243
 
YUI().use(&#x27;cookie&#x27;, function(Y){
244
 
 
245
 
    &#x2F;&#x2F;get subcookie
246
 
    var stringValue = Y.Cookie.getSub(&quot;name&quot;, &quot;subname&quot;);
247
 
 
248
 
    &#x2F;&#x2F;get subcookie and convert to number
249
 
    var numberValue = Y.Cookie.getSub(&quot;user&quot;, &quot;age&quot;, Number);
250
 
 
251
 
    &#x2F;&#x2F;get subcookie and convert from hex code to decimal number
252
 
    var integerValue = Y.Cookie.getSub(&quot;settings&quot;, &quot;bgcolor&quot;, function(stringValue){
253
 
        return parseInt(stringValue, 16);   &#x2F;&#x2F; Create a number from a hexadecimal code
254
 
    });
255
 
    
256
 
});</pre>
257
 
 
258
 
 
259
 
<p>The second method to retrieve subcookies is <code>getSubs()</code>, which retrieves all subcookies and returns an object
260
 
with name-value pairs for each subcookie. The <code>getSubs()</code> method takes a single argument, the name of the cookie
261
 
containing subcookies to retrieve. The returned value is either an object or <code>null</code> if the cookie doesn't exist.</p>
262
 
 
263
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
264
 
YUI().use(&#x27;cookie&#x27;, function(Y){
265
 
 
266
 
    &#x2F;&#x2F;get all subcookies
267
 
    var data = Y.Cookie.getSubs(&quot;name&quot;);
268
 
    var subValue = data.subname;
269
 
 
270
 
    &#x2F;&#x2F;get all subcookies
271
 
    var user = Y.Cookie.getSubs(&quot;user&quot;);
272
 
    var userName = user.name;
273
 
    
274
 
});</pre>
275
 
 
276
 
 
277
 
<p>Removing subcookies is accomplished using the <code>removeSub()</code> method. This method accepts three arguments: the cookie name, the subcookie name, and an optional cookie options object. The options object, if specified, must have the same options
278
 
as when the cookie was originally created. Example:</p>
279
 
 
280
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
281
 
YUI().use(&#x27;cookie&#x27;, function(Y){
282
 
 
283
 
    &#x2F;&#x2F;set subcookie on the &quot;yahoo.com&quot; domain
284
 
    Y.Cookie.setSub(&quot;info&quot;, &quot;age&quot;, 22, { domain: &quot;yahoo.com&quot; });
285
 
 
286
 
    &#x2F;&#x2F;remove the subcookie
287
 
    Y.Cookie.removeSub(&quot;info&quot;, &quot;age&quot;, { domain: &quot;yahoo.com&quot; });                        
288
 
});</pre>
289
 
 
290
 
 
291
 
<p>Removing a subcookie keeps all other subcookies for that cookie intact. If you want to remove all subcookies, it's easiest to use <code>remove()</code> to remove the entire cookie.</p>
292
 
 
293
 
<p>When the last subcookie is removed, the overall cookie still remains. If you'd like to remove the cookie when the last subcookie is removed, then specify the "removeIfEmpty" option:</p>
294
 
 
295
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a YUI instance and use the cookie module.
296
 
YUI().use(&#x27;cookie&#x27;, function(Y){
297
 
 
298
 
    &#x2F;&#x2F;remove the subcookie
299
 
    Y.Cookie.removeSub(&quot;info&quot;, &quot;age&quot;, { removeIfEmpty: true });                        
300
 
});</pre>
301
 
 
302
 
</div>
303
 
        </div>
304
 
 
305
 
        <div id="sidebar" class="yui3-u">
306
 
            
307
 
                <div id="toc" class="sidebox">
308
 
                    <div class="hd">
309
 
                        <h2 class="no-toc">Table of Contents</h2>
310
 
                    </div>
311
 
 
312
 
                    <div class="bd">
313
 
                        <ul class="toc">
314
 
<li>
315
 
<a href="#getting-started">Getting Started</a>
316
 
</li>
317
 
<li>
318
 
<a href="#using">Using the Cookie Utility</a>
319
 
<ul class="toc">
320
 
<li>
321
 
<a href="#create">Creating Cookies</a>
322
 
</li>
323
 
<li>
324
 
<a href="#read">Reading Cookies</a>
325
 
</li>
326
 
<li>
327
 
<a href="#delete">Deleting Cookies</a>
328
 
</li>
329
 
<li>
330
 
<a href="#sub">Subcookies</a>
331
 
</li>
332
 
</ul>
333
 
</li>
334
 
</ul>
335
 
                    </div>
336
 
                </div>
337
 
            
338
 
 
339
 
            
340
 
                <div class="sidebox">
341
 
                    <div class="hd">
342
 
                        <h2 class="no-toc">Examples</h2>
343
 
                    </div>
344
 
 
345
 
                    <div class="bd">
346
 
                        <ul class="examples">
347
 
                            
348
 
                                
349
 
                                    <li data-description="Demonstrates basic usage of the Cookie utility for reading and writing cookies.">
350
 
                                        <a href="cookie-simple-example.html">Simple Cookie Example</a>
351
 
                                    </li>
352
 
                                
353
 
                            
354
 
                                
355
 
                                    <li data-description="Demonstrates using the Cookie utility to get, set and remove cookies.">
356
 
                                        <a href="cookie-advanced-example.html">Advanced Cookie Example</a>
357
 
                                    </li>
358
 
                                
359
 
                            
360
 
                                
361
 
                                    <li data-description="Demonstrates using the Cookie utility to get and set subcookies.">
362
 
                                        <a href="cookie-subcookie-example.html">Subcookie Example</a>
363
 
                                    </li>
364
 
                                
365
 
                            
366
 
                        </ul>
367
 
                    </div>
368
 
                </div>
369
 
            
370
 
 
371
 
            
372
 
        </div>
373
 
    </div>
374
 
</div>
375
 
 
376
 
<script src="../assets/vendor/prettify/prettify-min.js"></script>
377
 
<script>prettyPrint();</script>
378
 
 
379
 
</body>
380
 
</html>