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.
