← Back to branch summary

~ubuntu-branches/ubuntu/jaunty/moodle/jaunty

« back to all changes in this revision

Viewing changes to lib/yui/cookie/cookie.js

  • Committer: Bazaar Package Importer
  • Author(s): Jordan Mantha, Matt Oquist
  • Date: 2009-02-25 15:16:22 UTC
  • mfrom: (1.1.11 upstream)
  • Revision ID: james.westby@ubuntu.com-20090225151622-0ekt1liwhv2obfza
Tags: 1.9.4.dfsg-0ubuntu1
https://launchpad.net/bugs/322961
https://launchpad.net/bugs/239481
https://launchpad.net/bugs/334611
https://launchpad.net/bugs/225662
https://launchpad.net/bugs/325450
https://launchpad.net/bugs/327843
https://launchpad.net/bugs/303078
https://launchpad.net/bugs/234609
* Merge with Debian git (Closes LP: #322961, #239481, #334611):
  - use Ubuntu's smarty lib directory for linking
  - use internal yui library 
  - add update-notifier support back in

[Matt Oquist]
  * renamed prerm script
  * significantly rewrote postinst and other maintainer scripts to improve
    user experience and package maintainability
    (Closes LP: #225662, #325450, #327843, #303078, #234609)

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/yui/cookie/cookie.js
 
1
/*
 
2
Copyright (c) 2008, Yahoo! Inc. All rights reserved.
 
3
Code licensed under the BSD License:
 
4
http://developer.yahoo.net/yui/license.txt
 
5
version: 2.6.0
 
6
*/
 
7
/**
 
8
 * Utilities for cookie management
 
9
 * @namespace YAHOO.util
 
10
 * @module cookie
 
11
 */
 
12
YAHOO.namespace("util");
 
13
 
 
14
/**
 
15
 * Cookie utility.
 
16
 * @class Cookie
 
17
 * @static
 
18
 */
 
19
YAHOO.util.Cookie = {
 
20
    
 
21
    //-------------------------------------------------------------------------
 
22
    // Private Methods
 
23
    //-------------------------------------------------------------------------
 
24
    
 
25
    /**
 
26
     * Creates a cookie string that can be assigned into document.cookie.
 
27
     * @param {String} name The name of the cookie.
 
28
     * @param {String} value The value of the cookie.
 
29
     * @param {encodeValue} encodeValue True to encode the value, false to leave as-is.
 
30
     * @param {Object} options (Optional) Options for the cookie.
 
31
     * @return {String} The formatted cookie string.
 
32
     * @method _createCookieString
 
33
     * @private
 
34
     * @static
 
35
     */
 
36
    _createCookieString : function (name /*:String*/, value /*:Variant*/, encodeValue /*:Boolean*/, options /*:Object*/) /*:String*/ {
 
37
    
 
38
        //shortcut
 
39
        var lang = YAHOO.lang;
 
40
    
 
41
        var text /*:String*/ = encodeURIComponent(name) + "=" + (encodeValue ? encodeURIComponent(value) : value);
 
42
        
 
43
    
 
44
        if (lang.isObject(options)){
 
45
            //expiration date
 
46
            if (options.expires instanceof Date){
 
47
                text += "; expires=" + options.expires.toGMTString();
 
48
            }
 
49
        
 
50
            //path
 
51
            if (lang.isString(options.path) && options.path != ""){
 
52
                text += "; path=" + options.path;
 
53
            }
 
54
    
 
55
            //domain
 
56
            if (lang.isString(options.domain) && options.domain != ""){
 
57
                text += "; domain=" + options.domain;
 
58
            }
 
59
            
 
60
            //secure
 
61
            if (options.secure === true){
 
62
                text += "; secure";
 
63
            }
 
64
        }
 
65
        
 
66
        return text;
 
67
    },
 
68
    
 
69
    /**
 
70
     * Formats a cookie value for an object containing multiple values.
 
71
     * @param {Object} hash An object of key-value pairs to create a string for.
 
72
     * @return {String} A string suitable for use as a cookie value.
 
73
     * @method _createCookieHash
 
74
     * @private
 
75
     * @static
 
76
     */
 
77
    _createCookieHashString : function (hash /*:Object*/) /*:String*/ {
 
78
        
 
79
        //shortcuts
 
80
        var lang = YAHOO.lang;
 
81
        
 
82
        if (!lang.isObject(hash)){
 
83
            throw new TypeError("Cookie._createCookieHashString(): Argument must be an object.");
 
84
        }
 
85
        
 
86
        var text /*:Array*/ = new Array();
 
87
        
 
88
        for (var key in hash){
 
89
            if (lang.hasOwnProperty(hash, key) && !lang.isFunction(hash[key]) && !lang.isUndefined(hash[key])){
 
90
                text.push(encodeURIComponent(key) + "=" + encodeURIComponent(String(hash[key])));
 
91
            }
 
92
        }
 
93
        
 
94
        return text.join("&");
 
95
    },
 
96
    
 
97
    /**
 
98
     * Parses a cookie hash string into an object.
 
99
     * @param {String} text The cookie hash string to parse. The string should already be URL-decoded.
 
100
     * @return {Object} An object containing entries for each cookie value.
 
101
     * @method _parseCookieHash
 
102
     * @private
 
103
     * @static
 
104
     */
 
105
    _parseCookieHash : function (text /*:String*/) /*:Object*/ {
 
106
    
 
107
        var hashParts /*:Array*/ = text.split("&"),
 
108
            hashPart /*:Array*/ = null,
 
109
            hash /*:Object*/ = new Object();
 
110
        
 
111
        if (text.length > 0){
 
112
            for (var i=0, len=hashParts.length; i < len; i++){
 
113
                hashPart = hashParts[i].split("=");
 
114
                hash[decodeURIComponent(hashPart[0])] = decodeURIComponent(hashPart[1]);
 
115
            }
 
116
        }
 
117
        
 
118
        return hash;
 
119
    },    
 
120
    
 
121
    /**
 
122
     * Parses a cookie string into an object representing all accessible cookies.
 
123
     * @param {String} text The cookie string to parse.
 
124
     * @param {Boolean} decode (Optional) Indicates if the cookie values should be decoded or not. Default is true.
 
125
     * @return {Object} An object containing entries for each accessible cookie.
 
126
     * @method _parseCookieString
 
127
     * @private
 
128
     * @static
 
129
     */
 
130
    _parseCookieString : function (text /*:String*/, decode /*:Boolean*/) /*:Object*/ {
 
131
    
 
132
        var cookies /*:Object*/ = new Object();        
 
133
        
 
134
        if (YAHOO.lang.isString(text) && text.length > 0) {
 
135
        
 
136
            var decodeValue = (decode === false ? function(s){return s;} : decodeURIComponent);
 
137
        
 
138
            if (/[^=]+=[^=;]?(?:; [^=]+=[^=]?)?/.test(text)){            
 
139
                var cookieParts /*:Array*/ = text.split(/;\s/g);
 
140
                var cookieName /*:String*/ = null;
 
141
                var cookieValue /*:String*/ = null;
 
142
                var cookieNameValue /*:Array*/ = null;
 
143
                
 
144
                for (var i=0, len=cookieParts.length; i < len; i++){
 
145
                
 
146
                    //check for normally-formatted cookie (name-value)
 
147
                    cookieNameValue = cookieParts[i].match(/([^=]+)=/i);
 
148
                    if (cookieNameValue instanceof Array){
 
149
                        cookieName = decodeURIComponent(cookieNameValue[1]);
 
150
                        cookieValue = decodeValue(cookieParts[i].substring(cookieNameValue[1].length+1));
 
151
                    } else {
 
152
                        //means the cookie does not have an "=", so treat it as a boolean flag
 
153
                        cookieName = decodeURIComponent(cookieParts[i]);
 
154
                        cookieValue = cookieName;
 
155
                    }
 
156
                    cookies[cookieName] = cookieValue;
 
157
                }
 
158
            }
 
159
        }
 
160
        
 
161
        return cookies;
 
162
    },    
 
163
    
 
164
    //-------------------------------------------------------------------------
 
165
    // Public Methods
 
166
    //-------------------------------------------------------------------------
 
167
 
 
168
    /**
 
169
     * Returns the cookie value for the given name.
 
170
     * @param {String} name The name of the cookie to retrieve.
 
171
     * @param {Function} converter (Optional) A function to run on the value before returning
 
172
     *      it. The function is not used if the cookie doesn't exist.
 
173
     * @return {Variant} If no converter is specified, returns a string or null if
 
174
     *      the cookie doesn't exist. If the converter is specified, returns the value
 
175
     *      returned from the converter or null if the cookie doesn't exist.
 
176
     * @method get
 
177
     * @static
 
178
     */
 
179
    get : function (name /*:String*/, converter /*:Function*/) /*:Variant*/{
 
180
        
 
181
        var lang = YAHOO.lang;
 
182
        var cookies /*:Object*/ = this._parseCookieString(document.cookie);        
 
183
        
 
184
        if (!lang.isString(name) || name === ""){
 
185
            throw new TypeError("Cookie.get(): Cookie name must be a non-empty string.");
 
186
        }
 
187
        
 
188
        if (lang.isUndefined(cookies[name])) {
 
189
            return null;
 
190
        }
 
191
        
 
192
        if (!lang.isFunction(converter)){
 
193
            return cookies[name];
 
194
        } else {
 
195
            return converter(cookies[name]);
 
196
        }
 
197
    },
 
198
    
 
199
    /**
 
200
     * Returns the value of a subcookie.
 
201
     * @param {String} name The name of the cookie to retrieve.
 
202
     * @param {String} subName The name of the subcookie to retrieve.
 
203
     * @param {Function} converter (Optional) A function to run on the value before returning
 
204
     *      it. The function is not used if the cookie doesn't exist.
 
205
     * @return {Variant} If the cookie doesn't exist, null is returned. If the subcookie
 
206
     *      doesn't exist, null if also returned. If no converter is specified and the
 
207
     *      subcookie exists, a string is returned. If a converter is specified and the
 
208
     *      subcookie exists, the value returned from the converter is returned.
 
209
     * @method getSub
 
210
     * @static
 
211
     */
 
212
    getSub : function (name /*:String*/, subName /*:String*/, converter /*:Function*/) /*:Variant*/ {
 
213
    
 
214
        var lang = YAHOO.lang;    
 
215
        var hash /*:Variant*/ = this.getSubs(name);  
 
216
 
 
217
        if (hash !== null) {
 
218
            
 
219
            if (!lang.isString(subName) || subName === ""){
 
220
                throw new TypeError("Cookie.getSub(): Subcookie name must be a non-empty string.");
 
221
            }
 
222
            
 
223
            if (lang.isUndefined(hash[subName])){
 
224
                return null;
 
225
            }            
 
226
        
 
227
            if (!lang.isFunction(converter)){
 
228
                return hash[subName];
 
229
            } else {
 
230
                return converter(hash[subName]);
 
231
            }
 
232
        } else {
 
233
            return null;
 
234
        }
 
235
    
 
236
    },
 
237
    
 
238
    /**
 
239
     * Returns an object containing name-value pairs stored in the cookie with the given name.
 
240
     * @param {String} name The name of the cookie to retrieve.
 
241
     * @return {Object} An object of name-value pairs if the cookie with the given name
 
242
     *      exists, null if it does not.
 
243
     * @method getHash
 
244
     * @static
 
245
     */
 
246
    getSubs : function (name /*:String*/) /*:Object*/ {
 
247
        
 
248
        //check cookie name
 
249
        if (!YAHOO.lang.isString(name) || name === ""){
 
250
            throw new TypeError("Cookie.getSubs(): Cookie name must be a non-empty string.");
 
251
        }
 
252
        
 
253
        var cookies = this._parseCookieString(document.cookie, false);
 
254
        if (YAHOO.lang.isString(cookies[name])){
 
255
            return this._parseCookieHash(cookies[name]);
 
256
        }
 
257
        return null;
 
258
    },
 
259
    
 
260
    /**
 
261
     * Removes a cookie from the machine by setting its expiration date to
 
262
     * sometime in the past.
 
263
     * @param {String} name The name of the cookie to remove.
 
264
     * @param {Object} options (Optional) An object containing one or more
 
265
     *      cookie options: path (a string), domain (a string), 
 
266
     *      and secure (true/false). The expires option will be overwritten
 
267
     *      by the method.
 
268
     * @return {String} The created cookie string.
 
269
     * @method remove
 
270
     * @static
 
271
     */
 
272
    remove : function (name /*:String*/, options /*:Object*/) /*:String*/ {
 
273
        
 
274
        //check cookie name
 
275
        if (!YAHOO.lang.isString(name) || name === ""){
 
276
            throw new TypeError("Cookie.remove(): Cookie name must be a non-empty string.");
 
277
        }
 
278
        
 
279
        //set options
 
280
        options = options || {};
 
281
        options.expires = new Date(0);
 
282
        
 
283
        //set cookie
 
284
        return this.set(name, "", options);
 
285
    },
 
286
 
 
287
    /**
 
288
     * Removes a sub cookie with a given name.
 
289
     * @param {String} name The name of the cookie in which the subcookie exists.
 
290
     * @param {String} subName The name of the subcookie to remove.
 
291
     * @param {Object} options (Optional) An object containing one or more
 
292
     *      cookie options: path (a string), domain (a string), expires (a Date object),
 
293
     *      and secure (true/false). This must be the same settings as the original
 
294
     *      subcookie.
 
295
     * @return {String} The created cookie string.
 
296
     * @method removeSub
 
297
     * @static
 
298
     */
 
299
    removeSub : function(name /*:String*/, subName /*:String*/, options /*:Object*/) /*:String*/ {
 
300
    
 
301
        //check cookie name
 
302
        if (!YAHOO.lang.isString(name) || name === ""){
 
303
            throw new TypeError("Cookie.removeSub(): Cookie name must be a non-empty string.");
 
304
        }
 
305
        
 
306
        //check subcookie name
 
307
        if (!YAHOO.lang.isString(subName) || subName === ""){
 
308
            throw new TypeError("Cookie.removeSub(): Subcookie name must be a non-empty string.");
 
309
        }
 
310
        
 
311
        //get all subcookies for this cookie
 
312
        var subs = this.getSubs(name);
 
313
        
 
314
        //delete the indicated subcookie
 
315
        if (YAHOO.lang.isObject(subs) && YAHOO.lang.hasOwnProperty(subs, subName)){
 
316
            delete subs[subName];
 
317
            
 
318
            //reset the cookie
 
319
            return this.setSubs(name, subs, options);
 
320
        } else {
 
321
            return "";
 
322
        }
 
323
        
 
324
    },
 
325
 
 
326
    /**
 
327
     * Sets a cookie with a given name and value.
 
328
     * @param {String} name The name of the cookie to set.
 
329
     * @param {Variant} value The value to set for the cookie.
 
330
     * @param {Object} options (Optional) An object containing one or more
 
331
     *      cookie options: path (a string), domain (a string), expires (a Date object),
 
332
     *      and secure (true/false).
 
333
     * @return {String} The created cookie string.
 
334
     * @method set
 
335
     * @static
 
336
     */
 
337
    set : function (name /*:String*/, value /*:Variant*/, options /*:Object*/) /*:String*/ {
 
338
    
 
339
        var lang = YAHOO.lang;
 
340
    
 
341
        if (!lang.isString(name)){
 
342
            throw new TypeError("Cookie.set(): Cookie name must be a string.");
 
343
        }
 
344
        
 
345
        if (lang.isUndefined(value)){
 
346
            throw new TypeError("Cookie.set(): Value cannot be undefined.");
 
347
        }
 
348
        
 
349
    
 
350
        var text /*:String*/ = this._createCookieString(name, value, true, options);
 
351
        document.cookie = text;
 
352
        return text;
 
353
    },
 
354
        
 
355
    /**
 
356
     * Sets a sub cookie with a given name to a particular value.
 
357
     * @param {String} name The name of the cookie to set.
 
358
     * @param {String} subName The name of the subcookie to set.
 
359
     * @param {Variant} value The value to set.
 
360
     * @param {Object} options (Optional) An object containing one or more
 
361
     *      cookie options: path (a string), domain (a string), expires (a Date object),
 
362
     *      and secure (true/false).
 
363
     * @return {String} The created cookie string.
 
364
     * @method setSub
 
365
     * @static
 
366
     */
 
367
    setSub : function (name /*:String*/, subName /*:String*/, value /*:Variant*/, options /*:Object*/) /*:String*/ {
 
368
        
 
369
        var lang = YAHOO.lang;
 
370
 
 
371
        if (!lang.isString(name) || name === ""){
 
372
            throw new TypeError("Cookie.setSub(): Cookie name must be a non-empty string.");
 
373
        }
 
374
 
 
375
        if (!lang.isString(subName) || subName === ""){
 
376
            throw new TypeError("Cookie.setSub(): Subcookie name must be a non-empty string.");
 
377
        }
 
378
        
 
379
        if (lang.isUndefined(value)){
 
380
            throw new TypeError("Cookie.setSub(): Subcookie value cannot be undefined.");
 
381
        }
 
382
 
 
383
        var hash /*:Object*/ = this.getSubs(name);
 
384
        
 
385
        if (!lang.isObject(hash)){
 
386
            hash = new Object();
 
387
        }
 
388
        
 
389
        hash[subName] = value;        
 
390
        
 
391
        return this.setSubs(name, hash, options);
 
392
        
 
393
    },
 
394
    
 
395
    /**
 
396
     * Sets a cookie with a given name to contain a hash of name-value pairs.
 
397
     * @param {String} name The name of the cookie to set.
 
398
     * @param {Object} value An object containing name-value pairs.
 
399
     * @param {Object} options (Optional) An object containing one or more
 
400
     *      cookie options: path (a string), domain (a string), expires (a Date object),
 
401
     *      and secure (true/false).
 
402
     * @return {String} The created cookie string.
 
403
     * @method setSubs
 
404
     * @static
 
405
     */
 
406
    setSubs : function (name /*:String*/, value /*:Object*/, options /*:Object*/) /*:String*/ {
 
407
        
 
408
        var lang = YAHOO.lang;
 
409
        
 
410
        if (!lang.isString(name)){
 
411
            throw new TypeError("Cookie.setSubs(): Cookie name must be a string.");
 
412
        }
 
413
        
 
414
        if (!lang.isObject(value)){
 
415
            throw new TypeError("Cookie.setSubs(): Cookie value must be an object.");
 
416
        }
 
417
    
 
418
        var text /*:String*/ = this._createCookieString(name, this._createCookieHashString(value), false, options);
 
419
        document.cookie = text;
 
420
        return text;        
 
421
    }    
 
422
 
 
423
};
 
424
YAHOO.register("cookie", YAHOO.util.Cookie, {version: "2.6.0", build: "1321"});