YUI recommends YUI3.

YUI 2 has been deprecated since 2011. This site acts as an archive for files and documentation.

This documentation is no longer maintained.

YUI 2: Selector Utility

YUI 2: Selector Utility

The YUI Selector Utility brings CSS3 Selector syntax to JavaScript, providing a compact shorthand for collecting, filtering, and testing HTMLElements.

Getting Started

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

  1. <!-- Dependencies -->
  2. <script src="http://yui.yahooapis.com/2.9.0/build/yahoo/yahoo-min.js"></script>
  4. <!-- Source file -->
  5. <script src="http://yui.yahooapis.com/2.9.0/build/selector/selector-min.js"></script>
<!-- Dependencies -->
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo/yahoo-min.js"></script>
<!-- Source file -->
<script src="http://yui.yahooapis.com/2.9.0/build/selector/selector-min.js"></script>

YUI dependency configurator.

YUI Dependency Configurator:

Instead of copying and pasting the filepaths above, try letting the YUI dependency Configurator determine the optimal file list for your desired components; the Configurator uses YUI Loader to write out the full HTML for including the precise files you need for your implementation.

Note: If you wish to include this component via the YUI Loader, its module name is selector. (Click here for the full list of module names for YUI Loader.)

Where these files come from: The files included using the text above will be served from Yahoo! servers. JavaScript files are minified, meaning that comments and white space have been removed to make them more efficient to download. To use the full, commented versions or the -debug versions of YUI JavaScript files, please download the library distribution and host the files on your own server.

Order matters: As is the case generally with JavaScript and CSS, order matters; these files should be included in the order specified above. If you include files in the wrong order, errors may result.

Basic Usage

The Selector API is most commonly used to retrieve a collection of elements that match a given CSS selector. This is done using the query() method.

  1. var nodes = YAHOO.util.Selector.query('div p');
var nodes = YAHOO.util.Selector.query('div p');

In this example, the array of nodes returned contains all HTMLElements that are of type P that have a DIV ancestor.

The query() method can take an optional root node from which to begin the search and a boolean third argument that, if true, will cause the Selector Utility to return only the first node that matches the selector. For example, the following query will return only the first P element with a DIV ancestor that is a descendent of the element with an ID attribute of foo:

  1. var node = YAHOO.util.Selector.query('div p', 'foo', true);
var node = YAHOO.util.Selector.query('div p', 'foo', true);

Using Selector

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

Using Selector to Attach Event Listeners

The query method can be useful for attaching events to a number of elements.

  1. var handleClick = function(e) {
  2. alert('click');
  3. };
  4. var nodes = YAHOO.util.Selector.query('li a');
  5. YAHOO.util.Event.on(nodes, 'click', handleClick);
var handleClick = function(e) {
var nodes = YAHOO.util.Selector.query('li a');
YAHOO.util.Event.on(nodes, 'click', handleClick);

The above example listens for clicks on all anchors that are descendants of an LI element. The handleClick function is invoked when any of of the nodes are clicked.

Testing a Node

Another useful method that Selector provides is test(), which accepts a node and a simple selector, and returns true or false, depending on whether or not the node matches the provided selector.

  1. var node = document.getElementById('foo');
  2. alert(YAHOO.util.Selector.test(node, 'div.bar'));
var node = document.getElementById('foo');
alert(YAHOO.util.Selector.test(node, 'div.bar'));

The above example will alert true if the node is of type DIV and has a class of bar, otherwise it will alert false.

Filtering Nodes

Selector also provides a means for filtering a set of nodes based on a simple selector.

  1. var candidates = document.getElementsByTagName('a');
  2. var nodes = YAHOO.util.Selector.filter(candidates, '[href]');
var candidates = document.getElementsByTagName('a');
var nodes = YAHOO.util.Selector.filter(candidates, '[href]');

The above example filters the candidate anchor elements and returns only those that have the href attribute set.

Using Attribute Operators

Selector implements CSS3 Attribute Selectors, which includes a number of powerful operators for use in testing attributes.

For example, say you want to collect all input elements whose names begin with "yui". This is a job for the "starts with" ("^=") operator:

  1. var nodes = YAHOO.util.Selector.query('input[name^=yui]');
var nodes = YAHOO.util.Selector.query('input[name^=yui]');

The above example returns only input elements whose name attribute begins with "yui". See the CSS3 Specification for additional examples of attribute operators.

Using Pseudo-classes

Selector also implements most CSS3 Pseudo-classes, allowing for additional matching based on information that can not be expressed using simple selectors.

For example, you may want only the first child item of an unordered list:

  1. var nodes = YAHOO.util.Selector.query('ul li:first-child');
var nodes = YAHOO.util.Selector.query('ul li:first-child');

The not pseudo-class can be used if you want to match elements that DO NOT meet certain criteria:

  1. var nodes = YAHOO.util.Selector.query('input:not([type=button])');
var nodes = YAHOO.util.Selector.query('input:not([type=button])');

The above example returns only input elements that are NOT of type BUTTON. See the CSS3 Specification for additional examples of pseudo-classes.

YUI on Mobile: Using Selector Utility with "A-Grade" Mobile Browsers

About this Section: YUI generally works well with mobile browsers that are based on A-Grade browser foundations. For example, Nokia's N-series phones, including the N95, use a browser based on Webkit — the same foundation shared by Apple's Safari browser, which is found on the iPhone. The fundamental challenges in developing for this emerging class of full, A-Grade-derived browsers on handheld devices are:

  • Screen size: You have a much smaller canvas;
  • Input devices: Mobile devices generally do not have mouse input, and therefore are missing some or all mouse events (like mouseover);
  • Processor power: Mobile devices have slower processors that can more easily be saturated by JavaScript and DOM interactions — and processor usage affects things like battery life in ways that don't have analogues in desktop browsers;
  • Latency: Most mobile devices have a much higher latency on the network than do terrestrially networked PCs; this can make pages with many script, css or other types of external files load much more slowly.

There are other considerations, many of them device/browser specific (for example, current versions of the iPhone's Safari browser do not support Flash). The goal of these sections on YUI User's Guides is to provide you some preliminary insights about how specific components perform on this emerging class of mobile devices. Although we have not done exhaustive testing, and although these browsers are revving quickly and present a moving target, our goal is to provide some early, provisional advice to help you get started as you contemplate how your YUI-based application will render in the mobile world.

More Information:

The Selector Utility is fully supported on Apple's iPhone and the Nokia N-Series browsers; you can expect functional parity between Selector Utility on these devices as compared to the supported A-Grade browsers.

Support & Community

The YUI Library and related topics are discussed on the on the YUILibrary.com forums.

Also be sure to check out 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 YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.

Selector Utility Cheat Sheet:

Cheat Sheet for the Selector Utility.

Download full set of cheat sheets.

Selector Utility Examples:

Other YUI Examples That Make Use of the Selector Utility:

YUI Selector on del.icio.us:

bookmark on del.icio.us

be the first to bookmark this page!

Copyright © 2013 Yahoo! Inc. All rights reserved.

Privacy Policy - Copyright Policy - Job Openings