Cookie.js revision 515f1aa146757a100a18e302a97be31235c34d62
/**
* Utilities for cookie management
* @module cookie
*/
//shortcuts
var L = Y.Lang,
O = Y.Object,
NULL = null,
//shortcuts to functions
isUndefined = L.isUndefined,
isFunction = L.isFunction,
/*
* Throws an error message.
*/
}
/**
* Cookie utility.
* @class Cookie
* @static
*/
Y.Cookie = {
//-------------------------------------------------------------------------
// Private Methods
//-------------------------------------------------------------------------
/**
* Creates a cookie string that can be assigned into document.cookie.
* @param {String} name The name of the cookie.
* @param {String} value The value of the cookie.
* @param {encodeValue} encodeValue True to encode the value, false to leave as-is.
* @param {Object} options (Optional) Options for the cookie.
* @return {String} The formatted cookie string.
* @method _createCookieString
* @private
* @static
*/
_createCookieString : function (name /*:String*/, value /*:Variant*/, encodeValue /*:Boolean*/, options /*:Object*/) /*:String*/ {
//expiration date
}
//path
}
//domain
}
//secure
text += "; secure";
}
}
return text;
},
/**
* Formats a cookie value for an object containing multiple values.
* @param {Object} hash An object of key-value pairs to create a string for.
* @return {String} A string suitable for use as a cookie value.
* @method _createCookieHashString
* @private
* @static
*/
error("Cookie._createCookieHashString(): Argument must be an object.");
}
var text /*:Array*/ = [];
}
});
},
/**
* Parses a cookie hash string into an object.
* @param {String} text The cookie hash string to parse (format: n1=v1&n2=v2).
* @return {Object} An object containing entries for each cookie value.
* @method _parseCookieHash
* @private
* @static
*/
hash /*:Object*/ = {};
}
}
return hash;
},
/**
* Parses a cookie string into an object representing all accessible cookies.
* @param {String} text The cookie string to parse.
* @param {Boolean} shouldDecode (Optional) Indicates if the cookie values should be decoded or not. Default is true.
* @return {Object} An object containing entries for each accessible cookie.
* @method _parseCookieString
* @private
* @static
*/
var cookies /*:Object*/ = {};
//check for normally-formatted cookie (name-value)
if (cookieNameValue instanceof Array){
} else {
//means the cookie does not have an "=", so treat it as a boolean flag
}
}
}
}
return cookies;
},
//-------------------------------------------------------------------------
// Public Methods
//-------------------------------------------------------------------------
/**
* Returns the cookie value for the given name.
* @param {String} name The name of the cookie to retrieve.
* @param {Function} converter (Optional) A function to run on the value before returning
* it. The function is not used if the cookie doesn't exist.
* @return {Variant} If no converter is specified, returns a string or null if
* the cookie doesn't exist. If the converter is specified, returns the value
* returned from the converter or null if the cookie doesn't exist.
* @method get
* @static
*/
error("Cookie.get(): Cookie name must be a non-empty string.");
}
return NULL;
}
if (!isFunction(converter)){
} else {
}
},
/**
* Returns the value of a subcookie.
* @param {String} name The name of the cookie to retrieve.
* @param {String} subName The name of the subcookie to retrieve.
* @param {Function} converter (Optional) A function to run on the value before returning
* it. The function is not used if the cookie doesn't exist.
* @return {Variant} If the cookie doesn't exist, null is returned. If the subcookie
* doesn't exist, null if also returned. If no converter is specified and the
* subcookie exists, a string is returned. If a converter is specified and the
* subcookie exists, the value returned from the converter is returned.
* @method getSub
* @static
*/
error("Cookie.getSub(): Subcookie name must be a non-empty string.");
}
return NULL;
}
if (!isFunction(converter)){
} else {
}
} else {
return NULL;
}
},
/**
* Returns an object containing name-value pairs stored in the cookie with the given name.
* @param {String} name The name of the cookie to retrieve.
* @return {Object} An object of name-value pairs if the cookie with the given name
* exists, null if it does not.
* @method getSubs
* @static
*/
//check cookie name
error("Cookie.getSubs(): Cookie name must be a non-empty string.");
}
}
return NULL;
},
/**
* Removes a cookie from the machine by setting its expiration date to
* sometime in the past.
* @param {String} name The name of the cookie to remove.
* @param {Object} options (Optional) An object containing one or more
* cookie options: path (a string), domain (a string),
* by the method.
* @return {String} The created cookie string.
* @method remove
* @static
*/
//check cookie name
error("Cookie.remove(): Cookie name must be a non-empty string.");
}
//set options
//set cookie
},
/**
* Removes a sub cookie with a given name.
* @param {String} name The name of the cookie in which the subcookie exists.
* @param {String} subName The name of the subcookie to remove.
* @param {Object} options (Optional) An object containing one or more
* cookie options: path (a string), domain (a string), expires (a Date object),
* subcookie.
* @return {String} The created cookie string.
* @method removeSub
* @static
*/
//check cookie name
error("Cookie.removeSub(): Cookie name must be a non-empty string.");
}
//check subcookie name
error("Cookie.removeSub(): Subcookie name must be a non-empty string.");
}
//get all subcookies for this cookie
//delete the indicated subcookie
//reset the cookie
} else {
return "";
}
},
/**
* Sets a cookie with a given name and value.
* @param {String} name The name of the cookie to set.
* @param {Variant} value The value to set for the cookie.
* @param {Object} options (Optional) An object containing one or more
* cookie options: path (a string), domain (a string), expires (a Date object),
* @return {String} The created cookie string.
* @method set
* @static
*/
error("Cookie.set(): Cookie name must be a string.");
}
if (isUndefined(value)){
error("Cookie.set(): Value cannot be undefined.");
}
return text;
},
/**
* Sets a sub cookie with a given name to a particular value.
* @param {String} name The name of the cookie to set.
* @param {String} subName The name of the subcookie to set.
* @param {Variant} value The value to set.
* @param {Object} options (Optional) An object containing one or more
* cookie options: path (a string), domain (a string), expires (a Date object),
* @return {String} The created cookie string.
* @method setSub
* @static
*/
setSub : function (name /*:String*/, subName /*:String*/, value /*:Variant*/, options /*:Object*/) /*:String*/ {
error("Cookie.setSub(): Cookie name must be a non-empty string.");
}
error("Cookie.setSub(): Subcookie name must be a non-empty string.");
}
if (isUndefined(value)){
error("Cookie.setSub(): Subcookie value cannot be undefined.");
}
hash = {};
}
},
/**
* Sets a cookie with a given name to contain a hash of name-value pairs.
* @param {String} name The name of the cookie to set.
* @param {Object} value An object containing name-value pairs.
* @param {Object} options (Optional) An object containing one or more
* cookie options: path (a string), domain (a string), expires (a Date object),
* @return {String} The created cookie string.
* @method setSubs
* @static
*/
error("Cookie.setSubs(): Cookie name must be a string.");
}
error("Cookie.setSubs(): Cookie value must be an object.");
}
var text /*:String*/ = this._createCookieString(name, this._createCookieHashString(value), false, options);
return text;
}
};