In the last post, I showed how to easily select an individual element on the page by its ID with dojo. In this post, we’ll look at dojo.query(), a far more powerful feature that lets you select and manipulate multiple elements on the page.
dojo.query()
dojo.query() is automatically available in XPages — it does not require loading an additional module.
It selects any number of elements on the page that match the CSS selector that you provide. You can choose elements based on the tag, class, id, attributes, or any combination thereof.
It can be used to access multiple elements and manipulate them simultaneously. When you run a query, it returns a NodeList.
What is a NodeList?
A NodeList which an array of elements with additional functions available to make it more convenient to process (more on those in the next post). Even if the query only returns one element, an array is returned.
Selecting Elements
The same CSS selectors you use to target elements with stylesheet properties are used for selecting elements with dojo.query. You can select elements by tag name, class name, ID, use pseudoselectors, or combine them as needed for more specific targeting.
The selector is a string, so it can either be hard-coded or it can be replaced with a variable.
Standard Examples
Here are some of examples of how to use dojo.query to select elements:
| Description | Example |
|---|---|
| To select elements by tag name, specify the tag name | dojo.query('li'); |
| To select an element by ID, specify a pound sign (#) then the ID | dojo.query('#myID'); |
| To select elements by class name – specify a dot (.), then the class name | dojo.query('.myClass'); |
| To select elements of a specific tag with a specific class, specify the element name, a dot (.), then the class name | dojo.query('li.myClass'); |
Select all img tags within any div that has the myDiv class |
dojo.query('div.myDiv img'); |
| Select all elements that have a specific attribute | dojo.query('[size]'); |
| Select all elements with an attribute that has a specific value | dojo.query('[size=5]'); |
| Select odd or even elements with a pseudo class | dojo.query('li:nth-child(odd)'); |
Check out this W3Schools page for more information on CSS selectors. The better you understand them, the more efficiently you can target the elements you want to select on your page.
Test with Browser Tools!
As I mentioned in the last post, it can dramatically streamline your development when you work on code snippets directly in the browser console, rather than changing event code in XPages, saving, building, and refreshing the page.
This is especially true with working out query selectors. When you test a dojo query in the console, you’ll see an array of elements returned.
To get a quick count of the number of elements a query will return, you can add .length to the end of the statement to get the array length.
Selecting XPages Components – A Caveat
The query selector cannot handle the colons that are part of every XPages component ID, so if you want to use dojo.query() to select a component by its ID, you’ll need to use the string replace() method in JavaScript to escape the colons so the query can be executed properly.
Does not work:
dojo.query('#view:_id1:inputText1');
dojo.query('##{id:inputText1}');
Works:
dojo.query('#view\\:_id1\\:inputText1');
dojo.query('##{id:inputText1}'.replace(/:/g, '\\:'));
The last example looks a little strange because of the double pound sign (#); the first pound sign specifies that you’re selecting an ID, then #{id:inputText1} is the EL syntax that gets replaced with the XPages component’s client-side JavaScriptID. The replace code uses a regular expression to replace all colons in the ID with \\:
There are two backslashes because the backslash is an escape character; the first backslash escapes the second one, so the resulting string has one backslash.
With all of that being said, the code is kind of confusing. It is often simpler to add an attribute or class name to XPages elements, so the dojo query can be easier to understand and maintain.
Up Next
dojo.query() is the starting point for a lot of dojo functionality. Now that we can select elements on the page, we’ll start looking at how to manipulate them in future posts.
