<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>YUI Library Examples: Event: Using Custom Events</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../../assets/yui.css" >
<style>
/*Supplemental CSS for the YUI distribution*/
#custom-doc { width: 95%; min-width: 950px; }
#pagetitle {background-image: url(../../assets/bg_hd.gif);}
/* #pagetitle h1 {background-image: url(../../assets/title_h_bg.gif);}*/
</style>
<link rel="stylesheet" type="text/css" href="../../assets/dpSyntaxHighlighter.css">
<link type="text/css" rel="stylesheet" href="../../build/cssfonts/fonts-min.css" />
<script type="text/javascript" src="../../build/yui/yui-min.js"></script>
<style type="text/css">
#fire {margin:1em;}
#log {
border:1px dotted #999999; background-color:#FFFFFF;
}
#log li {padding:5px;}
#log li highlight {color:#993300;}
</style>
</head>
<body id="yahoo-com" class=" yui-skin-sam">
<div id="custom-doc" class="yui-t2">
<div id="hd">
<div id="ygunav">
<p>
<em>
<a href="http://developer.yahoo.com/yui/3/">YUI 3.x Home</a> <i> - </i>
</em>
</p>
<form action="http://search.yahoo.com/search" id="sitesearchform">
<input name="vs" type="hidden" value="developer.yahoo.com">
<input name="vs" type="hidden" value="yuiblog.com">
<div id="sitesearch">
<label for="searchinput">Site Search (YDN & YUIBlog): </label>
<input type="text" id="searchinput" name="p">
<input type="submit" value="Search" id="searchsubmit" class="ygbt">
</div>
</form>
</div>
<div id="ygma"><a href="../../"><img src="../../assets/logo.gif" border="0" width="200" height="93"></a></div>
<div id="pagetitle"><h1>YUI Library Examples: Event: Using Custom Events</h1></div>
</div>
<div id="bd">
<div id="bar-note"><p><strong>Note:</strong> This is YUI 3.x. Looking for <a href="http://developer.yahoo.com/yui/">YUI 2.x</a>?</p></div>
<div id="yui-main">
<div class="yui-b">
<div class="yui-ge">
<div class="yui-u first example" id="main">
<h2>Event: Using Custom Events</h2>
<div id="example" class="promo">
<p>
<p>The Custom Event framework is one of the principle communication mechanisms
in YUI. An object can be augmented with <code>EventTarget</code>, enabling it
to be both a host and a target for Custom Events. Custom Events fire from
their host and optionally bubble up to one or more targets. This allows you to
make the interesting moments of your applications broadly available within a
module, within a set of modules, or throughout a complex interface populated
with rich elements.</p>
<p>In this example, a simple Custom Event is illustrated:
<code>testEvent</code>. This Custom Event is hosted on a Publisher object and
bubbles up to a BubbleTarget object.</p>
<p><img src="assets/ce-example.gif" alt="An
illustration of the relationship between the Custom Event, its host, and its
Bubble Target."></p>
<p>Custom Events, like DOM events, can be stopped
(<code>stopPropagation</code>) and their default behavior can be suppressed
(<code>preventDefault</code>).</p>
</p>
<div class="module example-container ">
<div class="hd exampleHd">
<p class="newWindowButton yui-skin-sam">
<a href="event-ce_clean.html" target="_blank">View example in new window.</a>
</p>
</div> <div id="example-canvas" class="bd">
<!--BEGIN SOURCE CODE FOR EXAMPLE =============================== -->
<button id="fire" value="Fire">Fire publisher:testEvent</button> <br />
<input type="checkbox" id="stopPropagation"> <label for="stopPropagation">Stop Propagation (testEvent won't bubble to the BubbleTarget.)</label><br />
<input type="checkbox" id="preventDefault"> <label for="preventDefault">Prevent Default (testEvent's defaultFn won't fire.)</label>
<ol id="log">
<li>Custom Event log messages will appear here.</li>
</ol>
<script language="javascript">
//Create a YUI instance:
YUI({base:"../../build/", timeout: 10000}).use("node",
function(Y) {
//Shortcut for our logging div:
var logger = Y.Node.get("#log");
//Our BubbleTarget object is an object to which our Custom Event
//will be allowed to bubble. It needs itself to be an EventTarget,
//so we'll use augment to make it an EventTarget:
var BubbleTarget = function() {
Y.log("Host constructor executed.", "info", "example");
}
//Augment BubbleTarget to make it an EventTarget:
Y.augment(BubbleTarget, Y.EventTarget);
//Create an instance of BubbleTarget:
var bubbleTarget = new BubbleTarget();
//Now we'll subscribe to the "publisher:testEvent" -- note
//that we can do this even before this event is published:
bubbleTarget.subscribe("publisher:testEvent", function(e) {
Y.log("publisher:testEvent fired on the BubbleTarget object.", "info", "example");
});
//Now we'll create the constructor for the Publisher, which
//is the direct host of our Custom Event. It will also be an
//EventTarget, so we'll extend it as well:
var Publisher = function(bubbleTarget) {
//We'll specify now that Custom Events hosted by Publisher
//should bubble to the bubbleTarget instance passed into the
//the Publisher's constructor:
this.addTarget(bubbleTarget);
//Here we publish the Custom Event. Note that it's not
//necessary to publish the event at all if you don't have
//options you wish to configure -- firing the event or
//subscribing to it will create it on the fly if necessary:
this.publish("publisher:testEvent",
{
emitFacade: true,
//the defaultFn is what you want to have happen
//by default when no subscriber calls preventDefault:
defaultFn: function() {
Y.log("defaultFn: publisher:testEvent's defaultFn executed.", "info", "example");
},
//You can prevent the default function from firing by
//calling preventDefault from a listener (if the Custom
//Event's preventable option is set to true, as it is by
//default). If the default is prevented, the preventedFn
//is called, allowing you to respond if necessary.
preventedFn: function() {
Y.log("preventedFn: A subscriber to publisher:testEvent called preventDefault().", "info", "example");
},
//The stoppedFn is called if a subscriber calls stopPropagation or
//stopImmediatePropagation:
stoppedFn: function() {
Y.log("stoppedFn: A subscriber to publisher:testEvent called stopPropagation().", "info", "example");
}
}
);
Y.log("Publisher constructor executed.");
}
//Augment Publisher to make it an EventTarget:
Y.augment(Publisher, Y.EventTarget);
//Create a Publisher instance:
var p = new Publisher(bubbleTarget);
//We've already subscribed to the event on the bubbleTarget, but
//we can also subscribe to it here on the Publisher instance.
//We'll see the event fire here before it bubbles up to the
//bubbleTarget:
p.on("publisher:testEvent", function(e) {
Y.log("publisher:testEvent subscriber fired on the publisher object.", "info", "example");
if(Y.Node.get("#stopPropagation").get("checked")) {
//we will stopPropagation on the Custom Event, preventing
//it from bubbling to the bubbleTarget:
e.stopPropagation();
}
if(Y.Node.get("#preventDefault").get("checked")) {
//we will preventDefault on the Custom Event, preventing
//the testEvent's defaultFn from firing:
e.preventDefault();
}
});
//We can tie our testEvent to an interface gesture -- the click of a
//button, for example.
Y.on("click", function(e) {
//clear out the logger:
logger.set("innerHTML", "");
p.fire("publisher:testEvent");
}, "#fire");
//write out log messages to the page:
Y.on("yui:log", function(e) {
var s = logger.get("innerHTML");
logger.set("innerHTML", s + "<li>" + e.msg + "</li>");
});
});
</script>
<!--END SOURCE CODE FOR EXAMPLE =============================== -->
</div>
</div>
</div>
<h2>Source Code</h2>
<p>The full source code for this example follows. Read through the comments and code to get an understanding of how you can make use of Custom Events in your own application development.</p>
<textarea name="code" class="JScript" cols="60" rows="1">//Create a YUI instance:
YUI().use('node', function(Y) {
//Shortcut for our logging div:
var logger = Y.Node.get("#log");
//Our BubbleTarget object is an object to which our Custom Event
//will be allowed to bubble. It needs itself to be an EventTarget,
//so we'll use augment to make it an EventTarget:
var BubbleTarget = function() {
Y.log("Host constructor executed.", "info", "example");
}
//Augment BubbleTarget to make it an EventTarget:
Y.augment(BubbleTarget, Y.EventTarget);
//Create an instance of BubbleTarget:
var bubbleTarget = new BubbleTarget();
//Now we'll subscribe to the "publisher:testEvent" -- note
//that we can do this even before this event is published:
bubbleTarget.on("publisher:testEvent", function(e) {
Y.log("publisher:testEvent fired on the BubbleTarget object.", "info", "example");
});
//Now we'll create the constructor for the Publisher, which
//is the direct host of our Custom Event. It will also be an
//EventTarget, so we'll extend it as well:
var Publisher = function(bubbleTarget) {
//We'll specify now that Custom Events hosted by Publisher
//should bubble to the bubbleTarget instance passed into the
//the Publisher's constructor:
this.addTarget(bubbleTarget);
//Here we publish the Custom Event. Note that it's not
//necessary to publish the event at all if you don't have
//options you wish to configure -- firing the event or
//subscribing to it will create it on the fly if necessary:
this.publish("publisher:testEvent",
{
emitFacade: true,
//the defaultFn is what you want to have happen
//by default when no subscriber calls preventDefault:
defaultFn: function() {
Y.log("defaultFn: publisher:testEvent's defaultFn executed.", "info", "example");
},
//You can prevent the default function from firing by
//calling preventDefault from a listener (if the Custom
//Event's preventable option is set to true, as it is by
//default). If the default is prevented, the preventedFn
//is called, allowing you to respond if necessary.
preventedFn: function() {
Y.log("preventedFn: A subscriber to publisher:testEvent called preventDefault().", "info", "example");
},
//The stoppedFn is called if a subscriber calls stopPropagation or
//stopImmediatePropagation:
stoppedFn: function() {
Y.log("stoppedFn: A subscriber to publisher:testEvent called stopPropagation().", "info", "example");
}
}
);
Y.log("Publisher constructor executed.");
}
//Augment Publisher to make it an EventTarget:
Y.augment(Publisher, Y.EventTarget);
//Create a Publisher instance:
var p = new Publisher(bubbleTarget);
//We've already subscribed to the event on the bubbleTarget, but
//we can also subscribe to it here on the Publisher instance.
//We'll see the event fire here before it bubbles up to the
//bubbleTarget:
p.on("publisher:testEvent", function(e) {
Y.log("publisher:testEvent subscriber fired on the publisher object.", "info", "example");
if(Y.Node.get("#stopPropagation").get("checked")) {
//we will stopPropagation on the Custom Event, preventing
//it from bubbling to the bubbleTarget:
e.stopPropagation();
}
if(Y.Node.get("#preventDefault").get("checked")) {
//we will preventDefault on the Custom Event, preventing
//the testEvent's defaultFn from firing:
e.preventDefault();
}
});
//We can tie our testEvent to an interface gesture -- the click of a
//button, for example.
Y.on("click", function(e) {
//clear out the logger:
logger.set("innerHTML", "");
p.fire("publisher:testEvent");
}, "#fire");
//write out log messages to the page:
Y.on("yui:log", function(e) {
var s = logger.get("innerHTML");
logger.set("innerHTML", s + "<li>" + e.msg + "</li>");
});
});</textarea>
</div>
<div class="yui-u sidebar">
<div id="examples" class="mod box4">
<div class="hd">
<h4>
Event Examples:</h4>
</div>
<div class="bd">
<ul>
<li><a href='../event/event-simple.html'>Simple DOM Events</a></li><li><a href='../event/event-timing.html'>Using 'available', 'contentready', and 'domready'</a></li><li class='selected'><a href='../event/event-ce.html'>Using Custom Events</a></li><li><a href='../event/event-focus-blur.html'>Using the 'focus' and 'blur' custom events</a></li><li><a href='../yui/yui-augment.html'>Compose Classes of Objects with <code>augment</code> (included with examples for The YUI Global Object)</a></li><li><a href='../node-focusmanager/node-focusmanager-3.html'>Accessible Menu Button (included with examples for Focus Manager Node Plugin)</a></li><li><a href='../node-focusmanager/node-focusmanager-2.html'>Accessible TabView (included with examples for Focus Manager Node Plugin)</a></li><li><a href='../attribute/attribute-event.html'>Change Events (included with examples for Attribute)</a></li><li><a href='../widget/widget-extend.html'>Extending the base widget class (included with examples for Widget)</a></li><li><a href='../attribute/attribute-getset.html'>Getters, Setters and Validators (included with examples for Attribute)</a></li><li><a href='../dd/photo-browser.html'>Photo Browser (included with examples for Drag & Drop)</a></li> </ul>
</div>
</div>
<div class="mod box4">
<div class="hd">
<h4>More Event Resources:</h4>
</div>
<div class="bd">
<ul>
<!-- <li><a href="http://developer.yahoo.com/yui/event/">User's Guide</a> (external)</li> -->
<li><a href="../../api/module_event.html">API Documentation</a></li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b toc3" id="tocWrapper">
<!-- TABLE OF CONTENTS -->
<div id="toc">
<ul>
<li class="sect first">YUI 3.x Project</li><li class="item"><a title="The Yahoo! User Interface (YUI) Library, 3.x Branch, " href="http://developer.yahoo.com/yui/3/">YUI 3 Web Site (external)</a></li><li class="item"><a title="Examples of every YUI utility and control in action" href="../../examples/">YUI 3 Examples</a></li><li class="item"><a title="Instantly searchable API documentation for the entire YUI library." href="../../api/">YUI 3 API Docs</a></li><li class="item"><a title="The YUI Library can be downloaded from SourceForge" href="http://sourceforge.net/projects/yui/">YUI 3 on Sourceforge (external)</a></li><li class="item"><a title="YUI is free and open, offered under a BSD license." href="http://developer.yahoo.com/yui/3/license.html">YUI License (external)</a></li><li class="sect">YUI 3 Core - Examples</li><li class="item"><a title="YUI (Global Prerequisite) - Functional Examples" href="../../examples/yui/index.html">YUI (Global Prerequisite)</a></li><li class="selected "><a title="Event - Functional Examples" href="../../examples/event/index.html">Event</a></li><li class="item"><a title="Node - Functional Examples" href="../../examples/node/index.html">Node</a></li><li class="sect">YUI 3 Component Infrastructure - Examples</li><li class="item"><a title="Attribute - Functional Examples" href="../../examples/attribute/index.html">Attribute</a></li><li class="item"><a title="Plugin - Functional Examples" href="../../examples/plugin/index.html">Plugin</a></li><li class="item"><a title="Widget - Functional Examples" href="../../examples/widget/index.html">Widget</a></li><li class="sect">YUI 3 Utilities - Examples</li><li class="item"><a title="Animation - Functional Examples" href="../../examples/anim/index.html">Animation</a></li><li class="item"><a title="Cache - Functional Examples" href="../../examples/cache/index.html">Cache</a></li><li class="item"><a title="Cookie - Functional Examples" href="../../examples/cookie/index.html">Cookie</a></li><li class="item"><a title="DataSchema - Functional Examples" href="../../examples/dataschema/index.html">DataSchema</a></li><li class="item"><a title="DataSource - Functional Examples" href="../../examples/datasource/index.html">DataSource</a></li><li class="item"><a title="DataType - Functional Examples" href="../../examples/datatype/index.html">DataType</a></li><li class="item"><a title="Drag & Drop - Functional Examples" href="../../examples/dd/index.html">Drag & Drop</a></li><li class="item"><a title="Get - Functional Examples" href="../../examples/get/index.html">Get</a></li><li class="item"><a title="History - Functional Examples" href="../../examples/history/index.html">History</a></li><li class="item"><a title="ImageLoader - Functional Examples" href="../../examples/imageloader/index.html">ImageLoader</a></li><li class="item"><a title="IO - Functional Examples" href="../../examples/io/index.html">IO</a></li><li class="item"><a title="JSON (JavaScript Object Notation) - Functional Examples" href="../../examples/json/index.html">JSON</a></li><li class="item"><a title="Queue - Functional Examples" href="../../examples/queue/index.html">Queue</a></li><li class="item"><a title="Stylesheet - Functional Examples" href="../../examples/stylesheet/index.html">Stylesheet</a></li><li class="sect">YUI 3 Widgets - Examples</li><li class="item"><a title="Overlay - Functional Examples" href="../../examples/overlay/index.html">Overlay</a></li><li class="item"><a title="Slider - Functional Examples" href="../../examples/slider/index.html">Slider</a></li><li class="sect">YUI 3 Node Plugins - Examples</li><li class="item"><a title="FocusManager Node Plugin - Functional Examples" href="../../examples/node-focusmanager/index.html">FocusManager Node Plugin</a></li><li class="item"><a title="MenuNav Node Plugin - Functional Examples" href="../../examples/node-menunav/index.html">MenuNav Node Plugin</a></li><li class="sect">YUI 3 CSS - Examples</li><li class="item"><a title="YUI CSS Reset - Functional Examples" href="../../examples/cssreset/index.html">CSS Reset</a></li><li class="item"><a title="YUI Fonts - Functional Examples" href="../../examples/cssfonts/index.html">CSS Fonts</a></li><li class="item"><a title="YUI Base - Functional Examples" href="../../examples/cssbase/index.html">CSS Base</a></li><li class="sect">YUI 3 Developer Tools - Examples</li><li class="item"><a title="Console - Functional Examples" href="../../examples/console/index.html">Console</a></li><li class="item"><a title="Profiler - Functional Examples" href="../../examples/profiler/index.html">Profiler</a></li><li class="item"><a title="Test - Functional Examples" href="../../examples/test/index.html">Test</a></li><li class="sect">The YUI Community</li><li class="item"><a title="The Yahoo! User Interface Blog" href="http://yuiblog.com">YUI Blog (external)</a></li><li class="item"><a title="The Yahoo! Group YDN-JavaScript hosts the YUI community forum" href="http://tech.groups.yahoo.com/group/ydn-javascript/">YUI Forum (external)</a></li><li class="item"><a title="The Yahoo! Group yui3 is dedicated to the 3.x branch of the Yahoo! User Interface (YUI) Library." href="http://tech.groups.yahoo.com/group/yui3/">YUI 3 Forum (external)</a></li><li class="item"><a title="YUI is used by Yahoo! and by hundreds of other sites, including many you know and love." href="/yui/poweredby/">YUI Sightings (external)</a></li><li class="item"><a title="Videos and podcasts from the YUI Team and from the Yahoo! frontend engineering community." href="http://developer.yahoo.com/yui/theater/">YUI Theater (external)</a></li><li class="sect">YUI Articles on the YUI Website</li><li class="item"><a title="Answers to Frequently Asked Questions about the YUI Library" href="http://developer.yahoo.com/yui/articles/faq/">YUI FAQ (external)</a></li><li class="item"><a title="Yahoo!'s philosophy of Graded Browser Support" href="http://developer.yahoo.com/yui/articles/gbs/">Graded Browser Support (external)</a></li><li class="item"><a title="Reporting Bugs and Making Feature Requests for YUI Components" href="http://developer.yahoo.com/yui/articles/reportingbugs/">Bug Reports/Feature Requests (external)</a></li><li class="item"><a title="Serve YUI source files from Yahoo! -- free, fast, and simple" href="http://developer.yahoo.com/yui/3/articles/hosting/">Serving YUI Files from Yahoo! (external)</a></li></ul>
</div>
</div>
</div><!--closes bd-->
<div id="ft">
<p class="first">Copyright © 2009 Yahoo! Inc. All rights reserved.</p>
<p><a href="http://privacy.yahoo.com/privacy/us/devel/index.html">Privacy Policy</a> -
<a href="http://docs.yahoo.com/info/terms/">Terms of Service</a> -
<a href="http://docs.yahoo.com/info/copyright/copyright.html">Copyright Policy</a> -
<a href="http://careers.yahoo.com/">Job Openings</a></p>
</div>
</div>
<script src="../../assets/dpSyntaxHighlighter.js"></script>
<script language="javascript">
dp.SyntaxHighlighter.HighlightAll('code');
</script>
</body>
</html>