Getting Started

To use the Element Utility, include the following source files in your web page with the <script> tag:

<!-- Dependencies --> <script src="http://yui.yahooapis.com/2.5.1/build/yahoo-dom-event/yahoo-dom-event.js"></script> <!-- Source file --> <script src="http://yui.yahooapis.com/2.5.1/build/element/element-beta-min.js"></script>

Basic Element

To create a new Element instance, pass either the ID of the element or a reference to the HTMLElement to the Element constructor:

var el = new YAHOO.util.Element('foo');

In this example, a new instance of YAHOO.util.Element is created for an element whose id is foo. If foo is not yet available in the document, event listeners may still be added, and attibutes may be set; the Element Utility will automatically defer those actions until the element becomes available. Be aware, however, that true manipulation of the element's DOM may not be performed until the contentReady event has fired. (Note: onContentReady is a YUI construct supported by the YUI Event Utility.)

Let's look at these steps in a code example:

<script> //create a new instance of Element wrapping //'foo', which isn' yet on the page var el = new YAHOO.util.Element('foo'); //add a click event handler to 'foo' el.on('click', function(e) { alert('clicked'); }); //when 'foo' is loaded on the page, we'll fire //an anonymous function that alerts the //number of list items in 'foo', which is a //<ul> element: el.on('contentReady', function() { var items = el.getElementsByTagName('li'); alert(items.length); }); </script> <!--markup for foo--> <div id="foo"> <ul> <li>lorem</li> <li>ipsum</li> <li>dolor</li> <li>sit</li> </ul> </div>

Using Element

This section describes several common uses of Element. It contains these subsections:

• Using Element to Attach Event Listeners
• Attributes and Properties
• Manipulating Dom
• Accessing Styles

Using Element to Attach Event Listeners

All Element events are applied using the addListener method (alised as on and can be removed with removeListener.

//create an Element instance wrapping 'foo': var el = new YAHOO.util.Element('foo'); //create an event listener: var handleClick = function(e) { alert(el.get('id') + ' clicked'); //remove this listener, so that //it only fires on the firs click: el.removeListener(handleClick); }; //assign an event listener using 'on'; //el.addListener and el.on are identical here: el.on('click', handleClick);

The above example invokes the handleClick function when the element whose id attribute is foo is clicked. The handler then removes the listener, so subsequent clicks will not fire the event.

Attributes and Properties

All of the attributes and properties of the HTMLElement can be accessed via the set and get methods of Element. Additionally, the actual HTMLElement bound to the Element instance can be retrieved via get('element').

//create an Element instance wrapping 'foo': var el = new YAHOO.util.Element('foo'); //we can now use the instane's get method to retrieve //attributes and properties of 'foo': alert(el.get('id') + ' has ' + el.get('childNodes').length + ' children');

The above example alerts the element's id attribute and the number of childNodes owned by that element.

If the element is not yet available, you will need to defer accessing the HTMLElement until the contentReady event fires. You can write deferral code as follows:

//create an Element instance wrapping 'foo'; //'foo' is not yet on the page. var el = new YAHOO.util.Element('foo'); //When 'foo' becomes available, we want to alert //its id and show the number childNodes; we tell the //Element instance to do this when the contentReady //event fires: el.on('contentReady', function() { alert(el.get('id') + ' has ' + el.get('childNodes').length + ' children'); });

Manipulating Dom

Most common Dom methods can be applied directy to the Element instance itself:

var el = new YAHOO.util.Element('foo'); //We can access the Dom property hasChildNodes //directly on the Element instance: if (el.hasChildNodes) { el.removeChild(el.get('firstChild')); }

Accessing Styles

Element instances can be styled directly via the setStyle method; style properties can be retrieved via getStyle:

var el = new YAHOO.util.Element('foo'); //set the color style property of 'foo' //using the Element instance: el.setStyle('color', '#f00'); //set an event handler using the Element //instance to alert the value of the //color style property when 'foo' is clicked: el.on('click', function() { alert(this.getStyle('color')); });

Support & Community

The YUI Library and related topics are discussed on the on the ydn-javascript mailing list.

In addition, please visit the YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUI SourceForge project site. Before filing new feature requests or bug reports, please review our reporting guidelines.

• Guidelines for YUI feature requests and bug reports.
• Review current bug list or file a new bug.
• Review current feature requests or file a new feature request.