The goal of this blog entry is to explain how to perform queries using selectors when using the WinJS library. In particular, you learn how to use the WinJS.Utilities.query() method and the QueryCollection class to retrieve and modify the elements of an HTML document.
Introduction to Selectors
When you are building a Web application, you need some way of easily retrieving elements from an HTML document. For example, you might want to retrieve all of the input elements which have a certain class. Or, you might want to retrieve the one and only element with an id of favoriteColor.
The standard way of retrieving elements from an HTML document is by using a selector. Anyone who has ever created a Cascading Style Sheet has already used selectors. You use selectors in Cascading Style Sheets to apply formatting rules to elements in a document.
For example, the following Cascading Style Sheet rule changes the background color of every INPUT element with a class of .required in a document to the color red:
input.red { background-color: red }
The “input.red” part is the selector which matches all INPUT elements with a class of red.
The W3C standard for selectors (technically, their recommendation) is entitled “Selectors Level 3” and the standard is located here:
http://www.w3.org/TR/css3-selectors/
Selectors are not only useful for adding formatting to the elements of a document. Selectors are also useful when you need to apply behavior to the elements of a document. For example, you might want to select a particular BUTTON element with a selector and add a click handler to the element so that something happens whenever you click the button.
Selectors are not specific to Cascading Style Sheets. You can use selectors in your JavaScript code to retrieve elements from an HTML document.
jQuery is famous for its support for selectors. Using jQuery, you can use a selector to retrieve matching elements from a document and modify the elements. The WinJS library enables you to perform the same types of queries as jQuery using the W3C selector syntax.
Performing Queries with the WinJS.Utilities.query() Method
When using the WinJS library, you perform a query using a selector by using the WinJS.Utilities.query() method.
The following HTML document contains a BUTTON and a DIV element:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Application1</title>
<!-- WinJS references -->
<link href="//Microsoft.WinJS.0.6/css/ui-dark.css" rel="stylesheet">
<script src="//Microsoft.WinJS.0.6/js/base.js"></script>
<script src="//Microsoft.WinJS.0.6/js/ui.js"></script>
<!-- Application1 references -->
<link href="/css/default.css" rel="stylesheet">
<script src="/js/default.js"></script>
</head>
<body>
<button>Click Me!</button>
<div style="display:none">
<h1>Secret Message</h1>
</div>
</body>
</html>
The document contains a reference to the following JavaScript file named \js\default.js:
(function () {
"use strict";
var app = WinJS.Application;
app.onactivated = function (eventObject) {
if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
WinJS.Utilities.query("button").listen("click", function () {
WinJS.Utilities.query("div").clearStyle("display");
});
}
};
app.start();
})();
The default.js script uses the WinJS.Utilities.query() method to retrieve all of the BUTTON elements in the page. The listen() method is used to wire an event handler to the BUTTON click event. When you click the BUTTON, the secret message contained in the hidden DIV element is displayed. The clearStyle() method is used to remove the display:none style attribute from the DIV element.
Under the covers, the WinJS.Utilities.query() method uses the standard querySelectorAll() method. This means that you can use any selector which is compatible with the querySelectorAll() method when using the WinJS.Utilities.query() method. The querySelectorAll() method is defined in the W3C Selectors API Level 1 standard located here:
http://www.w3.org/TR/selectors-api/
Unlike the querySelectorAll() method, the WinJS.Utilities.query() method returns a QueryCollection. We talk about the methods of the QueryCollection class below.
Retrieving a Single Element with the WinJS.Utilities.id() Method
If you want to retrieve a single element from a document, instead of matching a set of elements, then you can use the WinJS.Utilities.id() method. For example, the following line of code changes the background color of an element to the color red:
WinJS.Utilities.id("message").setStyle("background-color", "red");
The statement above matches the one and only element with an Id of message. For example, the statement matches the following DIV element:
<div id="message">Hello!</div>
Notice that you do not use a hash when matching a single element with the WinJS.Utilities.id() method. You would need to use a hash when using the WinJS.Utilities.query() method to do the same thing like this:
WinJS.Utilities.query("#message").setStyle("background-color", "red");
Under the covers, the WinJS.Utilities.id() method calls the standard document.getElementById() method. The WinJS.Utilities.id() method returns the result as a QueryCollection.
If no element matches the identifier passed to WinJS.Utilities.id() then you do not get an error. Instead, you get a QueryCollection with no elements (length=0).
Using the WinJS.Utilities.children() method
The WinJS.Utilities.children() method enables you to retrieve a QueryCollection which contains all of the children of a DOM element. For example, imagine that you have a DIV element which contains children DIV elements like this:
<div id="discussContainer">
<div>Message 1</div>
<div>Message 2</div>
<div>Message 3</div>
</div>
You can use the following code to add borders around all of the child DIV element and not the container DIV element:
var discussContainer = WinJS.Utilities.id("discussContainer").get(0);
WinJS.Utilities.children(discussContainer).setStyle("border", "2px dashed red");
It is important to understand that the WinJS.Utilities.children() method only works with a DOM element and not a QueryCollection. Notice that the get() method is used to retrieve the DOM element which represents the discussContainer.
Working with the QueryCollection Class
Both the WinJS.Utilities.query() method and the WinJS.Utilities.id() method return an instance of the QueryCollection class. The QueryCollection class derives from the base JavaScript Array class and adds several useful methods for working with HTML elements:
addClass(name) – Adds a class to every element in the QueryCollection.
clearStyle(name) – Removes a style from every element in the QueryCollection.
conrols(ctor, options) – Enables you to create controls.
get(index) – Retrieves the element from the QueryCollection at the specified index.
getAttribute(name) – Retrieves the value of an attribute for the first element in the QueryCollection.
hasClass(name) – Returns true if the first element in the QueryCollection has a certain class.
include(items) – Includes a collection of items in the QueryCollection.
listen(eventType, listener, capture) – Adds an event listener to every element in the QueryCollection.
query(query) – Performs an additional query on the QueryCollection and returns a new QueryCollection.
removeClass(name) – Removes a class from the every element in the QueryCollection.
removeEventListener(eventType, listener, capture) – Removes an event listener from every element in the QueryCollection.
setAttribute(name, value) – Adds an attribute to every element in the QueryCollection.
setStyle(name, value) – Adds a style attribute to every element in the QueryCollection.
template(templateElement, data, renderDonePromiseContract) – Renders a template using the supplied data.
toggleClass(name) – Toggles the specified class for every element in the QueryCollection.
Because the QueryCollection class derives from the base Array class, it also contains all of the standard Array methods like forEach() and slice().
Summary
In this blog post, I’ve described how you can perform queries using selectors within a Windows Metro Style application written with JavaScript. You learned how to return an instance of the QueryCollection class by using the WinJS.Utilities.query(), WinJS.Utilities.id(), and WinJS.Utilities.children() methods. You also learned about the methods of the QueryCollection class.
