YAHOO.lang is packaged with the YAHOO Global Object

YAHOO.lang comes bundled with the YAHOO Global Object. To add the YAHOO Global Object, include the following in your markup:

<script type="text/javascript" src="http://yui.yahooapis.com/2.5.1/build/yahoo/yahoo-min.js"></script>

If you are using any other YUI component on your page, you should already have YAHOO.lang available.

The example: Any class can be an EventProvider

This example creates a custom class, then augments it with YAHOO.util.EventProvider (functionality included in the YUI Event Utility). Using the packaged functionality of EventProvider, the code for Foo is able to focus on the functionality unique to its purpose.

YAHOO.namespace('example'); // Create a class Foo for some greater purpose YAHOO.example.Foo = function () { /* code specific to Foo */ // Add a custom event for the instance this.createEvent('interestingMoment'); } YAHOO.example.Foo.prototype.doSomething = function() { /* ..do something interesting... */ // Fire off the custom event this.fireEvent('interestingMoment'); } // Make the custom event stuff possible via augmentProto YAHOO.lang.augmentProto(YAHOO.example.Foo, YAHOO.util.EventProvider); var f = new YAHOO.example.Foo(); // Add some event listeners f.subscribe('interestingMoment', function () { var p = YAHOO.util.Dom.get('demo_p1'); p.innerHTML = 'I was notified of an interesting moment'; }); f.subscribe('interestingMoment', function () { var p = YAHOO.util.Dom.get('demo_p2'); p.innerHTML = 'I was also notified of an interesting moment'; }); // Add a listener to the button to call the instance's doSomething method YAHOO.util.Event.on('demo','click', function () { f.doSomething() });

Composition, not inheritance

If Foo were a part of a class hierarchy, it would be improper to include EventProvider in the inheritance chain, since the purpose of the two are fundamentally different.

Unlike extended classes, the relationship between a class and the classes augmenting it is not an indication of type hierarchy. The intent of augmentProto is to aid in extracting nonessential behaviors or behaviors shared by many classes, allowing for a composition-style class architecture.

This may appear similar to multiple inheritance, but it's not. augmentProto simply adds the public methods and members from one class prototype to another class prototype. Instances of the augmented class will not pass instanceof tests for the class(es) which augmented it.

function Foo() {} Foo.prototype.doSomething = function () { /* something */ }; function Bar() {} YAHOO.lang.augmentProto(Bar, Foo); var b = new Bar(); if (b instanceof Bar) {} // true if (b instanceof Foo) {} // FALSE

A short history of augmentProto

augmentProto started its life as YAHOO.augment way back in version 0.12 of YUI.

In version 2.2.0, it was moved into the YAHOO.lang module. The alias YAHOO.augment was added for backward compatibility.

In version 2.3.0, augment became augmentProto. Another alias, YAHOO.lang.augment, was created for backward compatibility.

While these aliases should be around for a while, it's advisable to use YAHOO.lang.augmentProto going forward to ensure that your code is as future-compatible as possible.