oop.js revision 4d9274a50fe5ecc9c0c3cfa1377ea596c44cd9b7
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Supplies object inheritance and manipulation utilities. This adds
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * additional functionaity to what is provided in yui-base, and the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * methods are applied directly to the YUI instance. This module
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * is required for most YUI components.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @module oop
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync A = Y.Array,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * The following methods are added to the YUI instance
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @class YUI~oop
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Applies prototype properties from the supplier to the receiver.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * The receiver can be a constructor or an instance.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @method augment
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param {Function} r the object to receive the augmentation
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param {Function} s the object that supplies the properties to augment
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param ov {boolean} if true, properties already on the receiver
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * will be overwritten if found on the supplier.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param wl {string[]} a whitelist. If supplied, only properties in
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * this list will be applied to the receiver.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param args {Array | Any} arg or arguments to apply to the supplier
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * constructor when initializing.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @return {object} the augmented object
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @todo constructor optional?
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @todo understanding what an instance is augmented with
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @TODO best practices for overriding sequestered methods.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // working on a class, so apply constructor infrastructure
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // sequester all of the functions in the supplier and replace with
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // one that will restore all of them.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync replacements[k] = function() {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync// Y.log('sequestered function "' + k + '" executed. Initializing EventTarget');
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync// overwrite the prototype with all of the sequestered functions,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync// but only if it hasn't been overridden
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync if (sequestered.hasOwnProperty(i) && (this[i] === replacements[i])) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // Y.log('... restoring ' + k);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync this[i] = sequestered[i];
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // apply the constructor
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // apply the original sequestered function
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // Y.log('augment: ' + k);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // sequester the function
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync// replace the sequestered function with a function that will
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync// restore all sequestered functions and exectue the constructor.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync this[k] = replacements[k];
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // Y.log('augment() applying non-function: ' + k);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync this[k] = v;
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // augmenting an instance, so apply the constructor immediately
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync * Applies object properties from the supplier to the receiver. If
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync * the target has the property, and the property is an object, the target
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync * object will be augmented with the supplier's value. If the property
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync * is an array, the suppliers value will be appended to the target.
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync * @method aggregate
e7c4c205cb0af88b5ef0786be46da94847a9a37bvboxsync * @param {Function} r the object to receive the augmentation
e7c4c205cb0af88b5ef0786be46da94847a9a37bvboxsync * @param {Function} s the object that supplies the properties to augment
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync * @param ov {boolean} if true, properties already on the receiver
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync * will be overwritten if found on the supplier.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param wl {string[]} a whitelist. If supplied, only properties in
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * this list will be applied to the receiver.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @return {object} the extended object
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Utility to set up the prototype, constructor and superclass properties to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * support an inheritance strategy that can chain constructors and methods.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Static members will not be inherited.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @method extend
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param {Function} r the object to modify
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param {Function} s the object to inherit
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param {Object} px prototype properties to add/override
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param {Object} sx static properties to add/override
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @return {YUI} the YUI instance
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync if (!s||!r) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // @TODO error symbols
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // assign constructor property
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync if (s != Object && sp.constructor == OP.constructor) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // add prototype overrides
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // add object overrides
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Executes the supplied function for each item in
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * a collection. Supports arrays, objects, and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Y.NodeLists
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @method each
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param o the object to iterate
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param f the function to execute. This function
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * receives the value, key, and object as parameters
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param proto if true, prototype properties are
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * iterated on objects
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @return {YUI} the YUI instance
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync switch (A.test(o)) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync return A.each(o, f, c);
241adddf415cbdf66230864a215b24415f482e72vboxsync // return Y.Object.each(o, f, c);
241adddf415cbdf66230864a215b24415f482e72vboxsync * Deep obj/array copy. Functions are cloned with Y.bind.
241adddf415cbdf66230864a215b24415f482e72vboxsync * Array-like objects are treated as arrays.
241adddf415cbdf66230864a215b24415f482e72vboxsync * Primitives are returned untouched. Optionally, a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * function can be provided to handle other data types,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * filter keys, validate values, etc.
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * @method clone
859c9a7cc74066a52cf7e76d54169859e7705c3dvboxsync * @param o what to clone
859c9a7cc74066a52cf7e76d54169859e7705c3dvboxsync * @param safe {boolean} if true, objects will not have prototype
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * items from the source. If false, they will. In this case, the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * original is initially protected, but the clone is not completely immune
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * from changes to the source object prototype. Also, cloned prototype
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * items that are deleted from the clone will result in the value
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * of the source prototype being exposed. If operating on a non-safe
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * clone, items should be nulled out rather than deleted.
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * @TODO review
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * @param f optional function to apply to each item in a collection;
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * it will be executed prior to applying the value to
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * the new object. Return false to prevent the copy.
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * @param c optional execution context for f
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * @param owner Owner object passed when clone is iterating an
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * object. Used to set up context for cloned functions.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @return {Array|Object} the cloned object
241adddf415cbdf66230864a215b24415f482e72vboxsync if (!L.isObject(o)) {
241adddf415cbdf66230864a215b24415f482e72vboxsync switch (L.type(o)) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync case 'date':
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync return new Date(o);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync case 'regexp':
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync return new RegExp(o.source);
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync case 'function':
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync case 'array':
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.each(o, function(v, k) {
241adddf415cbdf66230864a215b24415f482e72vboxsync if (!f || (f.call(c || this, v, k, this, o) !== false)) {
241adddf415cbdf66230864a215b24415f482e72vboxsync * Returns a function that will execute the supplied function in the
241adddf415cbdf66230864a215b24415f482e72vboxsync * supplied object's context, optionally adding any additional
241adddf415cbdf66230864a215b24415f482e72vboxsync * supplied parameters to the beginning of the arguments collection the
241adddf415cbdf66230864a215b24415f482e72vboxsync * supplied to the function.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @method bind
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param f {Function|String} the function to bind, or a function name
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * to execute on the context object
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param c the execution context
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param args* 0..n arguments to include before the arguments the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * function is executed with.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @return {function} the wrapped function
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.bind = function(f, c) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync var xargs = arguments.length > 2 ? Y.Array(arguments, 2, true) : null;
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync return function () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync args = (xargs) ? xargs.concat(Y.Array(arguments, 0, true)) : arguments;
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Returns a function that will execute the supplied function in the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * supplied object's context, optionally adding any additional
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * supplied parameters to the end of the arguments the function
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * is executed with.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @method rbind
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param f {Function|String} the function to bind, or a function name
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * to execute on the context object
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param c the execution context
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param args* 0..n arguments to append to the end of arguments collection
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * supplied to the function
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @return {function} the wrapped function
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.rbind = function(f, c) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync var xargs = arguments.length > 2 ? Y.Array(arguments, 2, true) : null;
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync return function () {