oop.js revision d15bebe7c35995c08b4ad26e6e9f5b25bc5e2a96
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// 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;
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // augmenting an instance, so apply the constructor immediately
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * 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
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync * @param {Function} r the object to receive the augmentation
e7c4c205cb0af88b5ef0786be46da94847a9a37bvboxsync * @param {Function} s the object that supplies the properties to augment
e7c4c205cb0af88b5ef0786be46da94847a9a37bvboxsync * @param ov {boolean} if true, properties already on the receiver
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync * will be overwritten if found on the supplier.
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync * @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) {
4aebc69aadd38c5c13ed4211d60635ad49538275vboxsync // add prototype overrides
4aebc69aadd38c5c13ed4211d60635ad49538275vboxsync // add object overrides
4aebc69aadd38c5c13ed4211d60635ad49538275vboxsync * Executes the supplied function for each item in
4aebc69aadd38c5c13ed4211d60635ad49538275vboxsync * a collection. Supports arrays, objects, and
4aebc69aadd38c5c13ed4211d60635ad49538275vboxsync * Y.NodeLists
4aebc69aadd38c5c13ed4211d60635ad49538275vboxsync * @method each
4aebc69aadd38c5c13ed4211d60635ad49538275vboxsync * @param o the object to iterate
4aebc69aadd38c5c13ed4211d60635ad49538275vboxsync * @param f the function to execute. This function
4aebc69aadd38c5c13ed4211d60635ad49538275vboxsync * receives the value, key, and object as parameters
4aebc69aadd38c5c13ed4211d60635ad49538275vboxsync * @param proto if true, prototype properties are
4aebc69aadd38c5c13ed4211d60635ad49538275vboxsync * iterated on objects
4aebc69aadd38c5c13ed4211d60635ad49538275vboxsync * @return {YUI} the YUI instance
4aebc69aadd38c5c13ed4211d60635ad49538275vboxsync switch (A.test(o)) {
4aebc69aadd38c5c13ed4211d60635ad49538275vboxsync return A.each(o, f, c);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync // return Y.Object.each(o, f, c);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Deep obj/array copy. Functions are cloned with Y.bind.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Array-like objects are treated as arrays.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Primitives are returned untouched. Optionally, a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * function can be provided to handle other data types,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * filter keys, validate values, etc.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @method clone
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param o what to clone
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @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
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * items that are deleted from the clone will result in the value
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * of the source prototype being exposed. If operating on a non-safe
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * clone, items should be nulled out rather than deleted.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @TODO review
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param f optional function to apply to each item in a collection;
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * it will be executed prior to applying the value to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * the new object. Return false to prevent the copy.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param c optional execution context for f
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @param owner Owner object passed when clone is iterating an
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * 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)) {
241adddf415cbdf66230864a215b24415f482e72vboxsync case 'date':
241adddf415cbdf66230864a215b24415f482e72vboxsync return new Date(o);
241adddf415cbdf66230864a215b24415f482e72vboxsync case 'regexp':
241adddf415cbdf66230864a215b24415f482e72vboxsync return new RegExp(o.source);
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync case 'function':
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync case 'array':
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync Y.each(o, function(v, k) {
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync if (!f || (f.call(c || this, v, k, this, o) !== false)) {
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * 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.
241adddf415cbdf66230864a215b24415f482e72vboxsync * @method bind
241adddf415cbdf66230864a215b24415f482e72vboxsync * @param f {Function|String} the function to bind, or a function name
241adddf415cbdf66230864a215b24415f482e72vboxsync * to execute on the context object
241adddf415cbdf66230864a215b24415f482e72vboxsync * @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
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync Y.bind = function(f, c) {
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync var xargs = arguments.length > 2 ? Y.Array(arguments, 2, true) : null;
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync return function () {
a8ce9568e18b8c1a49833bf3b3ac2b2cc634b13cvboxsync args = (xargs) ? xargs.concat(Y.Array(arguments, 0, true)) : arguments;
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * 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 end of the arguments the function
241adddf415cbdf66230864a215b24415f482e72vboxsync * is executed with.
241adddf415cbdf66230864a215b24415f482e72vboxsync * @method rbind
241adddf415cbdf66230864a215b24415f482e72vboxsync * @param f {Function|String} the function to bind, or a function name
241adddf415cbdf66230864a215b24415f482e72vboxsync * to execute on the context object
241adddf415cbdf66230864a215b24415f482e72vboxsync * @param c the execution context
241adddf415cbdf66230864a215b24415f482e72vboxsync * @param args* 0..n arguments to append to the end of arguments collection
241adddf415cbdf66230864a215b24415f482e72vboxsync * supplied to the function
241adddf415cbdf66230864a215b24415f482e72vboxsync * @return {function} the wrapped function
241adddf415cbdf66230864a215b24415f482e72vboxsync Y.rbind = function(f, c) {
241adddf415cbdf66230864a215b24415f482e72vboxsync 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@' );