Selectors API

The Selectors API specification, currently being worked on within the WebAPI working group at the W3C, defines DOM APIs designed to make it possible to select elements within the document using Selectors. This simple, yet powerful API has the potential to make working with the DOM faster and easier. If you’re familiar with CSS, you will be familiar with Selectors and these APIs should be easy to learn.

For example, to select all the em and strong elements within the document, you can use this.

document.querySelectorAll("em, strong");

To see how much easier this is compared with traditional APIs, consider this example HTML fragment:

<ul id="fruits">
	<li><input type="checkbox" name="fruit" value="apples"> Apples</li>
	<li><input type="checkbox" name="fruit" value="oranges"> Oranges</li>
	<li><input type="checkbox" name="fruit" value="bananas"> Bananas</li>
	<li><input type="checkbox" name="fruit" value="grapes"> Grapes</li>
</ul>

After the user has filled out the form containing those check boxes, suppose you want to get the list of all the checked items. Using traditional APIs, this would require obtaining a list of all the input elements and iteratively checking which ones were checked.

var fruits = document.getElementById("fruits");
var checkboxes = fruits.getElementsByTagName("input");
var list = [];
for (var i = 0; i < checkboxes.length; i++) {
	if (checkboxes[i].checked) {
		list.push(checkboxes[i]);
	}
}

Using these new APIs, the operation can be reduced to a single line of code!

var list = document.querySelectorAll("#fruits input:checked");

This returns a node list containing all the input elements that were checked by the user. Your script can then perform any operation you like with them.

We have been working on an implementation of these APIs recently and support has been included within the recently released Acid 3 build.

There are two new methods introduced: querySelector() and querySelectorAll(). The former returns the first matching element within the tree, and the latter returns a collection of all matching elements as a NodeList. The current editor’s draft specification defines that the methods are available on the Document, Element and DocumentFragment nodes. However, our implementation currently only supports it on the Document and Elements nodes.

The querySelector() method is useful for situations where only the first matching element is needed, and is designed to be more efficient than the alternative querySelectorAll() method in such cases.

For example, the following form control and javascript function could be used to validate an email address. For simplicity, this uses the validity APIs from Web Forms 2.0. If support for legacy user agents is required, a more appropriate validity check could be written. The querySelector() method is used to obtain the correct element for outputting the appropriate error message, or clearing it when it is valid.

The JavaScript:

function validateEmail(evt) {
	var ctrl = event.target;
	var parent = ctrl.parentNode;
	var errMsg = parent.querySelector(".error");

	// Validate form control value
	if (!ctrl.validity.valid) {
		errMsg.innerHTML = "Invalid email address."
	} else {
		errMsg.innerHTML = "";
	}
}

The HTML fragment:

<p><input type="email" name="email" onchange="validateEmail();">
	 <strong class="error"></strong></p>

Our implementation also partially supports the namespace resolver features, allowing you to work with mixed namespace documents and select elements based on their namespace. Consult the specification for more information on the NSResolver object.

You can try out these examples for yourself in the recently released Acid 3 Gogi Build which is available for Windows and Linux.