Dojo in XPages – 7: Selecting DOM Elements with dojo.query
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 in XPages Series
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 is 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.
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.
Here are some of examples of how to use dojo.query to select elements:
|To select elements by tag name, specify the tag name||
|To select an element by ID, specify a pound sign (#) then the ID||
|To select elements by class name – specify a dot (.), then the class name||
|To select elements of a specific tag with a specific class, specify the element name, a dot (.), then the class name||
|Select all elements that have a specific attribute||
|Select all elements with an attribute that has a specific value||
|Select odd or even elements with a pseudo class||
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
Does not work:
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
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.
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.