index.mustache revision 5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith<div class="intro">
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith The YUI Custom Event System enables you to define and use events beyond
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith those available in the DOM — events that are specific to and of
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith interest in your own application. Custom Events are designed to work
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith much like DOM events. They can bubble, pass event facades, have their
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith propagation and default behaviors suppressed, etc.
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith The APIs for working with custom events are provided by the
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith `EventTarget` class. All other infrastructure classes extend
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith `EventTarget`, but if you just need the custom event APIs, you can
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith `extend` or `augment` your classes with `EventTarget` directly.
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith Bundled with `EventTarget` are <a
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith href="http://en.wikipedia.org/wiki/Aspect_oriented_programming">Aspect
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith Oriented Programming</a> methods that allow you subscribe to the
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith execution of object methods in many ways as though they were events of
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith<h2>Dear Testers: The content below is unedited, copy/paste</h2>
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith<p>No need to read on. The content will be changing.</p>
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith<h3 id="simplece">Simple Custom Events Using Y.on</h3>
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith<p>You can send out notification of an interesting moment anywhere
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smithfrom your code simply by calling your yui instance's <code>fire</code> method.</p>
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith//Create a YUI instance:
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke SmithYUI().use('event-custom', function(Y) {
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith Y.fire('customapp:started', 1, 2, 3);
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith This will send out notifications to any function that previously subscribed
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith to that event:
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke SmithY.on('customapp:started', function(arg1, arg2, arg3) {
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith Y.log('Custom App Started, now I can do a few things');
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith // the arguments 1, 2, and 3 were provided by fire()
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith<h3>Defining a Custom Event on an Event Target</h3>
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith A common way to create a Custom Event is to <code>augment</code> an object
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith with <code>EventTarget</code>, making it able to host Custom Events and be
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith a target for Custom Events that are bubbling from other hosts:
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke SmithYUI().use('event-custom', function(Y) {
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith // define a constructor:
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith function Publisher() {
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith // create a custom event. it is not necessary to explicitly publish an event
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith // unless you need to override the default configuration
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith this.publish("publisher:testEvent", {
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith // configuration options for this event
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith // augment the Publisher with EventTarget:
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith Y.augment(Publisher, Y.EventTarget, null, null, {
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith // this argument is provided to EventTarget's constructor, and
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith // lets you set up default configuration values for every event
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith // published on this event target.
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith // if you accept the default configuration, augmenting EventTarget looks like this:
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith The <code>publish</code> constructor creates a new Custom Event. It takes
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith one required parameter and one optional parameter:
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith <strong>type</strong> — The type of event. This string is
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith returned to listeners that receive this event so that they know what
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith event occurred.
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith <strong>options</strong> — The specific configuration options you
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith want to define for this Custom Event. Most properties of the Custom
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith Event class can be set at this time.
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith<h3>Subscribing (Listening) to a Custom Event</h3>
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith To subscribe to a custom event, use its <code>on</code> method. Following
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith the code above, you would subscribe to the <code>publisher:testEvent</code>
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smithvar publisher = new Publisher();
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smithpublisher.on("publisher:testEvent", function(e) {
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith //event handler code
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith<h3 id="customfire">Firing the Event</h3>
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith To trigger or <code>fire</code> a custom event, simply call its
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith <code>fire</code> method:
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smithpublisher.fire("publisher:testEvent");
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith<h3>Broadcasting events/Sharing info across YUI instances</h3>
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith When publishing an event, you can specify a broadcast configuration -- this
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith makes it so any code can observe the event. You limit the notification to
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith code within the YUI instance, or you can broadcast globally so any code on
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith the page can consume the event. This is the primary way of sharing data
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith across different YUI sandboxes.
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smithvar publisher = new Y.EventTarget();
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smithpublisher.name = 'broadcast publisher';
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smithpublisher.publish('instance_notification:foo', {
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith broadcast: 1, // instance level notification
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith emitFacade: true // emit a facade so we get the event target
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith// this event is available by using the YUI instance to subscribe to it
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke SmithY.on('instance_notification:foo', function(e) {
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smithvar publisher2 = new Y.EventTarget();
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smithpublisher2.name = 'global publisher';
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smithpublisher.publish('global_notification:foo', {
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith broadcast: 2, // global notification
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith emitFacade: true // emit a facade so we get the event target
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith// external code, this new sandbox has access to the global event
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke SmithYUI().use('event-custom', function(Y2) {
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith // the global event can be listened to on a special event
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith // target referenced on your YUI instance called 'Global'
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith Y2.Global.on('global_notification:foo', function() {
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith Y2.on('instance_notification:foo', function(e) {
5abe4e6ccb00e9414eb123e8d3d7e1a8d2a7c317Luke Smith // will NOT receive notification