oop.js revision 23209f57fce338501bc1dc828a991d103732b92f
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 // dispatch = function(o, f, c, proto, action) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // if (o[action] && o.item) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // return o[action].call(o, f, c);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // } else {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // switch (A.test(o)) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // return A[action](o, f, c);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // return A[action](Y.Array(o, 0, true), f, c);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // default:
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // return Y.Object[action](o, f, c, proto);
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;
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync // augmenting an instance, so apply the constructor immediately
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Applies object properties from the supplier to the receiver. If
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * the target has the property, and the property is an object, the target
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * object will be augmented with the supplier's value. If the property
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * is an array, the suppliers value will be appended to the target.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @method aggregate
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 * @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
241adddf415cbdf66230864a215b24415f482e72vboxsync * @param o the object to iterate
241adddf415cbdf66230864a215b24415f482e72vboxsync * @param f the function to execute. This function
241adddf415cbdf66230864a215b24415f482e72vboxsync * receives the value, key, and object as parameters
241adddf415cbdf66230864a215b24415f482e72vboxsync * @param proto if true, prototype properties are
241adddf415cbdf66230864a215b24415f482e72vboxsync * iterated on objects
241adddf415cbdf66230864a215b24415f482e72vboxsync * @return {YUI} the YUI instance
241adddf415cbdf66230864a215b24415f482e72vboxsync switch (A.test(o)) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync return A.each(o, f, c);
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync // return Y.Object.each(o, f, c);
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync // Y.each = function(o, f, c, proto) {
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync // return dispatch(o, f, c, proto, 'each');
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * Executes the supplied function for each item in
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * a collection. The operation stops if the function
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * returns true. Supports arrays, objects, and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Y.NodeLists.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @method some
241adddf415cbdf66230864a215b24415f482e72vboxsync * @param o the object to iterate
241adddf415cbdf66230864a215b24415f482e72vboxsync * @param f the function to execute. This function
241adddf415cbdf66230864a215b24415f482e72vboxsync * receives the value, key, and object as parameters
241adddf415cbdf66230864a215b24415f482e72vboxsync * @param proto if true, prototype properties are
241adddf415cbdf66230864a215b24415f482e72vboxsync * iterated on objects
241adddf415cbdf66230864a215b24415f482e72vboxsync * @return {boolean} true if the function ever returns true, false otherwise
241adddf415cbdf66230864a215b24415f482e72vboxsync // Y.some = function(o, f, c, proto) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // return dispatch(o, f, c, proto, 'some');
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * Deep obj/array copy. Functions are cloned with Y.bind.
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * Array-like objects are treated as arrays.
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * Primitives are returned untouched. Optionally, a
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * function can be provided to handle other data types,
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * filter keys, validate values, etc.
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * @method clone
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * @param o what to clone
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * @param safe {boolean} if true, objects will not have prototype
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * items from the source. If false, they will. In this case, the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * original is initially protected, but the clone is not completely immune
241adddf415cbdf66230864a215b24415f482e72vboxsync * from changes to the source object prototype. Also, cloned prototype
241adddf415cbdf66230864a215b24415f482e72vboxsync * items that are deleted from the clone will result in the value
241adddf415cbdf66230864a215b24415f482e72vboxsync * of the source prototype being exposed. If operating on a non-safe
241adddf415cbdf66230864a215b24415f482e72vboxsync * clone, items should be nulled out rather than deleted.
241adddf415cbdf66230864a215b24415f482e72vboxsync * @TODO review
241adddf415cbdf66230864a215b24415f482e72vboxsync * @param f optional function to apply to each item in a collection;
241adddf415cbdf66230864a215b24415f482e72vboxsync * it will be executed prior to applying the value to
241adddf415cbdf66230864a215b24415f482e72vboxsync * the new object. Return false to prevent the copy.
241adddf415cbdf66230864a215b24415f482e72vboxsync * @param c optional execution context for f
241adddf415cbdf66230864a215b24415f482e72vboxsync * @param owner Owner object passed when clone is iterating an
241adddf415cbdf66230864a215b24415f482e72vboxsync * object. Used to set up context for cloned functions.
241adddf415cbdf66230864a215b24415f482e72vboxsync * @return {Array|Object} the cloned object
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync if (!L.isObject(o)) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync switch (L.type(o)) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync case 'date':
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync return new Date(o);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync case 'regexp':
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync return new RegExp(o.source);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync case 'function':
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync case 'array':
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // #2528250 only one clone of a given object should be created.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // #2528250 don't try to clone element properties
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Y.each(o, function(v, k) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync if (!f || (f.call(c || this, v, k, this, o) !== false)) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync this[k] = Y.clone(v, safe, f, c, owner || o, marked);
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 beginning of the arguments collection the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * 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
4791a729647f035b6561d292c9f848dd1fc797a9vboxsync * 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;
3dd1d8fdf12303b292d9ee378edbc5f5fb6d6cb5vboxsync * 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 () {