oop.js revision cce3fb1ef3935d8cea4963fcb7d4f05cee7f8e17
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 if (o && o[action] && o !== Y) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync switch (A.test(o)) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync return A[action](o, f, c);
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// 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 this[i] = sequestered[i];
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // apply the constructor
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // apply the original sequestered function
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 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
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @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 * Executes the supplied function for each item in
241adddf415cbdf66230864a215b24415f482e72vboxsync * a collection. The operation stops if the function
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * returns true. Supports arrays, objects, and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Y.NodeLists.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @method some
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * @param o the object to iterate
859c9a7cc74066a52cf7e76d54169859e7705c3dvboxsync * @param f the function to execute. This function
859c9a7cc74066a52cf7e76d54169859e7705c3dvboxsync * receives the value, key, and object as parameters
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param proto if true, prototype properties are
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * iterated on objects
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @return {boolean} true if the function ever returns true, false otherwise
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * Deep obj/array copy. Function clones are actually
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * wrappers around the original function.
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * Array-like objects are treated as arrays.
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * Primitives are returned untouched. Optionally, a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * function can be provided to handle other data types,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * filter keys, validate values, etc.
241adddf415cbdf66230864a215b24415f482e72vboxsync * @method clone
241adddf415cbdf66230864a215b24415f482e72vboxsync * @param o what to clone
241adddf415cbdf66230864a215b24415f482e72vboxsync * @param safe {boolean} if true, objects will not have prototype
241adddf415cbdf66230864a215b24415f482e72vboxsync * items from the source. If false, they will. In this case, the
241adddf415cbdf66230864a215b24415f482e72vboxsync * 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
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * clone, items should be nulled out rather than deleted.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param f optional function to apply to each item in a collection;
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * 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.
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync * @return {Array|Object} the cloned object
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync if (!L.isObject(o)) {
241adddf415cbdf66230864a215b24415f482e72vboxsync switch (L.type(o)) {
241adddf415cbdf66230864a215b24415f482e72vboxsync case 'date':
241adddf415cbdf66230864a215b24415f482e72vboxsync return new Date(o);
241adddf415cbdf66230864a215b24415f482e72vboxsync case 'regexp':
241adddf415cbdf66230864a215b24415f482e72vboxsync // return new RegExp(o.source); // if we do this we need to set the flags too
241adddf415cbdf66230864a215b24415f482e72vboxsync case 'function':
241adddf415cbdf66230864a215b24415f482e72vboxsync case 'array':
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // #2528250 only one clone of a given object should be created.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // #2528250 don't try to clone element properties
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync each(o, function(v, k) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync if (!f || (f.call(c || this, v, k, this, o) !== false)) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync if (k == 'prototype') {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // skip the prototype
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync } else if (o[k] === o) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync this[k] = this;
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
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
3dd1d8fdf12303b292d9ee378edbc5f5fb6d6cb5vboxsync * @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 () {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync args = (xargs) ? Y.Array(arguments, 0, true).concat(xargs) : arguments;
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync}, '@VERSION@' );