<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>YUI Library Examples: Attribute: Change 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">
#example-out .entry {
font-family:courier;
margin-top:2px;
}
#example-out .header {
font-weight:bold;
font-family:arial;
color:#8dd5e7;
margin-top:10px;
margin-bottom:3px;
}
#example-out {
margin:5px;
border:1px solid #000;
color:#ffffff;
background-color:#004c6d;
overflow:auto;
height:20em;
width:30em;
padding-left:2px;
}
.attrs {
width:30em;
border:1px solid #000;
background-color:#cdcdcd;
margin:5px;
}
.attrs .header {
font-weight:bold;
background-color:#aaa;
padding:5px;
}
.attrs .body {
padding:10px;
}
.attrs .footer {
padding:5px;
}
.attrs label {
display:block;
float:left;
clear:left;
font-weight:bold;
width:8em;
}
</style>
<script type="text/javascript">
YUI.namespace("example");
YUI.example.print = function(msg, cl) {
var o = document.getElementById("example-out");
if (o) {
cl = cl || "";
o.innerHTML += '<div class="entry ' + cl + '">' + msg + '</div>';
}
}
</script>
</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: Attribute: Change 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>Attribute: Change Events</h2>
<div id="example" class="promo">
<p>
Attribute change events are one of the key benefits of using attributes to maintain state for your objects, instead of regular object properties. This example shows how you can listen for attribute change events and work with the event payload they receive.
</p>
<div class="module example-container ">
<div class="hd exampleHd">
<p class="newWindowButton yui-skin-sam">
<a href="attribute-event_clean.html" target="_blank">View example in new window.</a>
</p>
</div> <div id="example-canvas" class="bd">
<!--BEGIN SOURCE CODE FOR EXAMPLE =============================== -->
<div class="attrs">
<div class="header">Enter a new value and click the "Change Value" button:</div>
<div class="body">
<p>
<label for="attrSel">Attribute</label>:
<select id="attrSel">
<option value="foo">foo</option>
<option value="bar">bar</option>
<option value="foobar">foobar (change will be prevented)</option>
</select>
</p>
<p><label for="currentVal">Current Value</label>: <span id="currentVal"></span></p>
<p><label for="newVal">New Value</label>: <input type="text" id="newVal" /></p>
</div>
<div class="footer">
<button type="button" id="changeValue">Change Value</button>
</div>
</div>
<div id="example-out"></div>
<script type="text/javascript">
// Get a new YUI instance
YUI({base:"../../build/", timeout: 10000}).use("node", "attribute", function(Y) {
// Shortcut to print (unrelated to example)
var print = YUI.example.print;
// Setup a custom class with attribute support
function MyClass(cfg) {
this.addAttrs(Y.merge(MyClass.ATTRIBUTES), cfg);
}
// Setup attribute configuration
MyClass.ATTRIBUTES = {
"foo" : {
value:5
},
"bar" : {
value:"Hello World!"
},
"foobar" : {
value:true
}
};
Y.augment(MyClass, Y.Attribute);
var o1 = new MyClass();
function printEvt(event) {
print("event.prevVal : " + event.prevVal);
print("event.newVal : " + event.newVal);
print("event.attrName : " + event.attrName);
}
// Start Form Handling
var attrSel = Y.Node.get("#attrSel");
var attrOpts = attrSel.get("options");
var newValTxt = Y.Node.get("#newVal");
var currentValSpan = Y.Node.get("#currentVal");
function updateVal() {
var selIndex = attrSel.get("selectedIndex");
var attr = attrOpts.item(selIndex).get("value");
o1.set(attr, newValTxt.get("value"));
}
Y.on("click", updateVal, "#changeValue");
function populateCurrentValue() {
var selIndex = attrSel.get("selectedIndex");
var attr = attrOpts.item(selIndex).get("value");
currentValSpan.set("innerHTML", o1.get(attr));
newValTxt.set("value", "");
}
populateCurrentValue();
Y.on("change", populateCurrentValue, attrSel);
// End Form Handling
// Event Listners
o1.after("fooChange", function(event) {
print("after fooChange", "header");
printEvt(event);
currentValSpan.set("innerHTML", event.newVal);
});
o1.after("barChange", function(event) {
print("after barChange", "header");
printEvt(event);
currentValSpan.set("innerHTML", event.newVal);
});
o1.on("foobarChange", function(event) {
// Calling preventDefault, in an "on" listener
// will prevent the attribute change from occuring
// and the after listener being called
print("on foobarChange (prevented)", "header");
event.preventDefault();
});
o1.after("foobarChange", function(event) {
// This will never get called, because we're
// calling preventDefault in the "on" listener
print("after foobarChange", "header");
printEvt(event);
currentValSpan.set("innerHTML", event.newVal);
});
});
</script>
<!--END SOURCE CODE FOR EXAMPLE =============================== -->
</div>
</div>
</div>
<h3>Listening For Attribute Change Events</h3>
<p>In this example, we'll look at how you can setup listeners for attribute change events, and work with the event payload which the listeners receive.</p>
<h4>Setting Up A Custom Class With Attribute</h4>
<p>We start by setting up the same custom class we created for the <a href="attribute-basic.html">basic example</a> with 3 attributes <code>foo</code>, <code>bar</code> and <code>foobar</code>, using the code below:</p>
<textarea name="code" class="JScript" cols="60" rows="1">
YUI().use("attribute", "node", function(Y) {
// Setup a custom class with attribute support
function MyClass(cfg) {
this.addAttrs(Y.merge(MyClass.ATTRIBUTES), cfg);
}
// Setup attribute configuration
MyClass.ATTRIBUTES = {
"foo" : {
value:5
},
"bar" : {
value:"Hello World!"
},
"foobar" : {
value:true
}
};
Y.augment(MyClass, Y.Attribute);
});
</textarea>
<h4>Registering Event Listeners</h4>
<p>Once we have an instance of the custom class, we can use the <code>on</code> and <code>after</code> methods provided by Attribute, to listen for changes in the value of each of the attributes:</p>
<textarea name="code" class="JScript" cols="60" rows="1">
var o1 = new MyClass();
...
// Event Listners
o1.after("fooChange", function(event) {
print("after fooChange", "header");
printEvt(event);
currentValSpan.set("innerHTML", event.newVal);
});
o1.after("barChange", function(event) {
print("after barChange", "header");
printEvt(event);
currentValSpan.set("innerHTML", event.newVal);
});
o1.on("foobarChange", function(event) {
// Calling preventDefault, in an "on" listener
// will prevent the attribute change from occurring
// and the after listener being called
print("on foobarChange (prevented)", "header");
event.preventDefault();
});
o1.after("foobarChange", function(event) {
// This will never get called, because we're
// calling preventDefault in the "on" listener
print("after foobarChange", "header");
printEvt(event);
currentValSpan.set("innerHTML", event.newVal);
});
</textarea>
<p>As seen in the above code, the event type for attribute change events is created by concatenating the attribute name with <code>"Change"</code> (e.g. <code>"fooChange"</code>), and this event type is used for both the <code>on</code> and <code>after</code> subscription methods. Whenever an attribute value is changed through Attribute's <code>set</code> method, both "on" and "after" subscribers are notified.</p>
<h4>On vs. After</h4>
<p><strong>on :</strong> Subscribers to the "on" moment, will be notified <em>before</em> any actual state change has occurred. This provides the opportunity to prevent the state change from occurring, using the <code>preventDefault</code> method of the event facade object passed to the subscriber. If you use <code>get</code> to retrieve the value of the attribute in an "on" subscriber, you will receive the current, unchanged value. However the event facade provides access to the value which the attribute is being set to, through it's <code>newVal</code> property.</p>
<p><strong>after :</strong> Subscribers to the "after" moment, will be notified <em>after</em> the attribute's state has been updated. This provides the opportunity to update state in other parts of your application, in response to a change in the attribute's state.</p>
<p>Based on the definition above, <code>after</code> listeners are not invoked if state change is prevented, for example, due to one of the <code>on</code> listeners calling <code>preventDefault</code> on the event object, as is done in the <code>on</code> listener for the <code>foobar</code> attribute:</p>
<textarea name="code" class="JScript" cols="60" rows="1">
o1.on("foobarChange", function(event) {
// Calling preventDefault, in an "on" listener
// will prevent the attribute change from occurring
// and prevent the after listeners from being called
print("on foobarChange (change prevented)", "header");
event.preventDefault();
});
</textarea>
<p>The <code>after</code> listeners will also not be invoked if there is no change in the actual value of the attribute. That is, if the new value of the attribute is identical to the current value (based on the identity operator, <code>===</code>), the <code>after</code> listeners will not be notified because there is no change in state. You can see this, by setting an attribute to the same value twice in a row.</p>
<h4>Event Facade</h4>
<p>The event object (an instance of <a href="../../api/EventFacade.html">EventFacade</a>) passed to attribute change event subscribers, has the following interesting properties and methods related to attribute management:</p>
<dl>
<dt>newVal</dt>
<dd>The value which the attribute will be set to (in the case of "on" subscribers), or has been set to (in the case of "after" subscribers</dd>
<dt>prevVal</dt>
<dd>The value which the attribute is currently set to (in the case of "on" subscribers), or was previously set to (in the case of "after" subscribers</dd>
<dt>attrName</dt>
<dd>The name of the attribute which is being set</dd>
<dt>subAttrName</dt>
<dd>Attribute also allows you to set nested properties of attributes which have values which are objects through the
<code>set</code> method (e.g. <code>o1.set("x.y.z")</code>). This property will contain the path to the property which was changed.</dd>
<dt>preventDefault()<dt>
<dd>This method can be called in an "on" subscriber to prevent the attribute's value from being updated (the default behavior). Calling this method in an "after" listener has no impact, since the default behavior has already been invoked.</dd>
<dt>stopImmediatePropagation()</dt>
<dd>This method can be called in "on" or "after" subscribers, and will prevent the rest of the subscriber stack from
being invoked, but will not prevent the attribute's value from being updated.</dd>
</dl>
</div>
<div class="yui-u sidebar">
<div id="examples" class="mod box4">
<div class="hd">
<h4>
Attribute Examples:</h4>
</div>
<div class="bd">
<ul>
<li><a href='../attribute/attribute-basic.html'>Basic Configuration</a></li><li class='selected'><a href='../attribute/attribute-event.html'>Change Events</a></li><li><a href='../attribute/attribute-getset.html'>Getters, Setters and Validators</a></li><li><a href='../attribute/attribute-rw.html'>readOnly and writeOnce Configuration</a></li> </ul>
</div>
</div>
<div class="mod box4">
<div class="hd">
<h4>More Attribute Resources:</h4>
</div>
<div class="bd">
<ul>
<!-- <li><a href="http://developer.yahoo.com/yui/attribute/">User's Guide</a> (external)</li> -->
<li><a href="../../api/module_attribute.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="item"><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="selected "><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>