lib/yui/yahoo/yahoo.js

   1 /*
   2 Copyright (c) 2006, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.net/yui/license.txt
   5 version: 0.12.2
   6 */
   7 /**
   8  * The YAHOO object is the single global object used by YUI Library.  It
   9  * contains utility function for setting up namespaces, inheritance, and
  10  * logging.  YAHOO.util, YAHOO.widget, and YAHOO.example are namespaces
  11  * created automatically for and used by the library.
  12  * @module yahoo
  13  * @title  YAHOO Global
  14  */
  15
  16 if (typeof YAHOO == "undefined") {
  17     /**
  18      * The YAHOO global namespace object
  19      * @class YAHOO
  20      * @static
  21      */
  22     var YAHOO = {};
  23 }
  24
  25 /**
  26  * Returns the namespace specified and creates it if it doesn't exist
  27  * <pre>
  28  * YAHOO.namespace("property.package");
  29  * YAHOO.namespace("YAHOO.property.package");
  30  * </pre>
  31  * Either of the above would create YAHOO.property, then
  32  * YAHOO.property.package
  33  *
  34  * Be careful when naming packages. Reserved words may work in some browsers
  35  * and not others. For instance, the following will fail in Safari:
  36  * <pre>
  37  * YAHOO.namespace("really.long.nested.namespace");
  38  * </pre>
  39  * This fails because "long" is a future reserved word in ECMAScript
  40  *
  41  * @method namespace
  42  * @static
  43  * @param  {String*} arguments 1-n namespaces to create
  44  * @return {Object}  A reference to the last namespace object created
  45  */
  46 YAHOO.namespace = function() {
  47     var a=arguments, o=null, i, j, d;
  48     for (i=0; i<a.length; ++i) {
  49         d=a[i].split(".");
  50         o=YAHOO;
  51
  52         // YAHOO is implied, so it is ignored if it is included
  53         for (j=(d[0] == "YAHOO") ? 1 : 0; j<d.length; ++j) {
  54             o[d[j]]=o[d[j]] || {};
  55             o=o[d[j]];
  56         }
  57     }
  58
  59     return o;
  60 };
  61
  62 /**
  63  * Uses YAHOO.widget.Logger to output a log message, if the widget is available.
  64  *
  65  * @method log
  66  * @static
  67  * @param  {String}  msg  The message to log.
  68  * @param  {String}  cat  The log category for the message.  Default
  69  *                        categories are "info", "warn", "error", time".
  70  *                        Custom categories can be used as well. (opt)
  71  * @param  {String}  src  The source of the the message (opt)
  72  * @return {Boolean}      True if the log operation was successful.
  73  */
  74 YAHOO.log = function(msg, cat, src) {
  75     var l=YAHOO.widget.Logger;
  76     if(l && l.log) {
  77         return l.log(msg, cat, src);
  78     } else {
  79         return false;
  80     }
  81 };
  82
  83 /**
  84  * Utility to set up the prototype, constructor and superclass properties to
  85  * support an inheritance strategy that can chain constructors and methods.
  86  *
  87  * @method extend
  88  * @static
  89  * @param {Function} subc   the object to modify
  90  * @param {Function} superc the object to inherit
  91  * @param {Object} overrides  additional properties/methods to add to the
  92  *                              subclass prototype.  These will override the
  93  *                              matching items obtained from the superclass
  94  *                              if present.
  95  */
  96 YAHOO.extend = function(subc, superc, overrides) {
  97     var F = function() {};
  98     F.prototype=superc.prototype;
  99     subc.prototype=new F();
 100     subc.prototype.constructor=subc;
 101     subc.superclass=superc.prototype;
 102     if (superc.prototype.constructor == Object.prototype.constructor) {
 103         superc.prototype.constructor=superc;
 104     }
 105
 106     if (overrides) {
 107         for (var i in overrides) {
 108             subc.prototype[i]=overrides[i];
 109         }
 110     }
 111 };
 112
 113 /**
 114  * Applies all prototype properties in the supplier to the receiver if the
 115  * receiver does not have these properties yet.  Optionally, one or more
 116  * methods/properties can be specified (as additional parameters).  This
 117  * option will overwrite the property if receiver has it already.
 118  *
 119  * @method augment
 120  * @static
 121  * @param {Function} r  the object to receive the augmentation
 122  * @param {Function} s  the object that supplies the properties to augment
 123  * @param {String*}  arguments zero or more properties methods to augment the
 124  *                             receiver with.  If none specified, everything
 125  *                             in the supplier will be used unless it would
 126  *                             overwrite an existing property in the receiver
 127  */
 128 YAHOO.augment = function(r, s) {
 129     var rp=r.prototype, sp=s.prototype, a=arguments, i, p;
 130     if (a[2]) {
 131         for (i=2; i<a.length; ++i) {
 132             rp[a[i]] = sp[a[i]];
 133         }
 134     } else {
 135         for (p in sp) {
 136             if (!rp[p]) {
 137                 rp[p] = sp[p];
 138             }
 139         }
 140     }
 141 };
 142
 143 YAHOO.namespace("util", "widget", "example");