Function
dojo.NodeList is an of Array subclass which adds syntactic sugar for chaining, common iteration operations, animation, and node manipulation. NodeLists are most often returned as the result of dojo.query() calls.
dojo.NodeList instances provide many utilities that reflect core Dojo APIs for Array iteration and manipulation, DOM manipulation, and event handling. Instead of needing to dig up functions in the dojo.* namespace, NodeLists generally make the full power of Dojo available for DOM manipulation tasks in a simple, chainable way.
create a node list from a node new dojo.NodeList(dojo.byId("foo"));
get a NodeList from a CSS query and iterate on it var l = dojo.query(".thinger"); l.forEach(function(node, index, nodeList){ console.log(index, node.innerHTML); });
use native and Dojo-provided array methods to manipulate a NodeList without needing to use dojo.* functions explicitly: var l = dojo.query(".thinger"); // since NodeLists are real arrays, they have a length // property that is both readable and writable and // push/pop/shift/unshift methods console.log(l.length); l.push(dojo.create("span")); // dojo's normalized array methods work too: console.log( l.indexOf(dojo.byId("foo")) ); // ...including the special "function as string" shorthand console.log( l.every("item.nodeType == 1") ); // NodeLists can be [..] indexed, or you can use the at() // function to get specific items wrapped in a new NodeList: var node = l[3]; // the 4th element var newList = l.at(1, 3); // the 2nd and 4th elements
the style functions you expect are all there too: // style() as a getter... var borders = dojo.query(".thinger").style("border"); // ...and as a setter: dojo.query(".thinger").style("border", "1px solid black"); // class manipulation dojo.query("li:nth-child(even)").addClass("even"); // even getting the coordinates of all the items var coords = dojo.query(".thinger").coords();
DOM manipulation functions from the dojo.* namespace area also available: // remove all of the elements in the list from their // parents (akin to "deleting" them from the document) dojo.query(".thinger").orphan(); // place all elements in the list at the front of #foo dojo.query(".thinger").place("foo", "first");
Event handling couldn't be easier. `dojo.connect` is mapped in, and shortcut handlers are provided for most DOM events: // like dojo.connect(), but with implicit scope dojo.query("li").connect("onclick", console, "log"); // many common event handlers are already available directly: dojo.query("li").onclick(console, "log"); var toggleHovered = dojo.hitch(dojo, "toggleClass", "hovered"); dojo.query("p") .onmouseenter(toggleHovered) .onmouseleave(toggleHovered);
chainability is a key advantage of NodeLists: dojo.query(".thinger") .onclick(function(e){ /* ... */ }) .at(1, 3, 8) // get a subset .style("padding", "5px") .forEach(console.log);
Function
normalizes data to an array of items to insert.
Object|self|inline'd type check|Array
Function
private utility to clone a node. Not very interesting in the vanilla dojo.NodeList case, but delegates could do interesting things like clone event handlers if that is derivable from the node.
Function
private utility to handle placing an array of nodes relative to another node.
Object|self|inline'd type check|Array
Function
private function to hold to a parent NodeList. end() to return the parent NodeList.
dojo.NodeList
How to make a `dojo.NodeList` method that only returns the third node in the dojo.NodeList but allows access to the original NodeList by using this._stash: dojo.extend(dojo.NodeList, { third: function(){ var newNodeList = dojo.NodeList(this[2]); return newNodeList._stash(this); } }); // then see how _stash applies a sub-list, to be .end()'ed out of dojo.query(".foo") .third() .addClass("thirdFoo") .end() // access to the orig .foo list .removeClass("foo")
Function
Ends use of the current `dojo.NodeList` by returning the previous dojo.NodeList that generated the current dojo.NodeList.
Returns the `dojo.NodeList` that generated the current `dojo.NodeList`. If there is no parent dojo.NodeList, an empty dojo.NodeList is returned.
dojo.query("a") .filter(".disabled") // operate on the anchors that only have a disabled class .style("color", "grey") .end() // jump back to the list of anchors .style(...)
Function
Can be a positive or negative integer, with positive integers noting the offset to begin at, and negative integers denoting an offset from the end (i.e., to the left of the end)
Optional parameter to describe what position relative to the NodeList's zero index to end the slice at. Like begin, can be positive or negative.
Returns a new NodeList, maintaining this one in place
This method behaves exactly like the Array.slice method with the caveat that it returns a dojo.NodeList and not a raw Array. For more details, see Mozilla's (slice documentation)[http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:slice]
Function
begin can be a positive or negative integer, with positive integers noting the offset to begin at, and negative integers denoting an offset from the end (i.e., to the left of the end)
Optional parameter to describe what position relative to the NodeList's zero index to end the slice at. Like begin, can be positive or negative.
Any number of optional parameters may be passed in to be spliced into the NodeList
Returns a new NodeList, manipulating this NodeList based on the arguments passed, potentially splicing in new elements at an offset, optionally deleting elements
This method behaves exactly like the Array.splice method with the caveat that it returns a dojo.NodeList and not a raw Array. For more details, see Mozilla's (splice documentation)[http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:splice] For backwards compatibility, calling .end() on the spliced NodeList does not return the original NodeList -- splice alters the NodeList in place.
dojo.NodeList
Function
The value to search for.
The location to start searching from. Optional. Defaults to 0.
see dojo.indexOf(). The primary difference is that the acted-on array is implicitly this NodeList
For more details on the behavior of indexOf, see Mozilla's (indexOf docs)[http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:indexOf]
Positive Integer or 0 for a match, -1 of not found.
Integer
Function
The value to search for.
The location to start searching from. Optional. Defaults to 0.
see dojo.lastIndexOf(). The primary difference is that the acted-on array is implicitly this NodeList
For more details on the behavior of lastIndexOf, see Mozilla's (lastIndexOf docs)[http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:lastIndexOf]
Positive Integer or 0 for a match, -1 of not found.
Integer
Function
the callback
the context
see `dojo.every()` and the (Array.every docs)[http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:every]. Takes the same structure of arguments and returns as dojo.every() with the caveat that the passed array is implicitly this NodeList
Boolean
Function
the callback
the context
Takes the same structure of arguments and returns as `dojo.some()` with the caveat that the passed array is implicitly this NodeList. See `dojo.some()` and Mozilla's (Array.some documentation)[http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:some].
Boolean
Function
Any number of optional parameters may be passed in to be spliced into the NodeList
Returns a new NodeList comprised of items in this NodeList as well as items passed in as parameters
This method behaves exactly like the Array.concat method with the caveat that it returns a `dojo.NodeList` and not a raw Array. For more details, see the (Array.concat docs)[http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:concat]
Object|self|inline'd type check|Array|dojo.NodeList|Integer|Boolean
Function
see dojo.map(). The primary difference is that the acted-on array is implicitly this NodeList and the return is a dojo.NodeList (a subclass of Array) /return d.map(this, func, obj, d.NodeList); // dojo.NodeList
dojo.NodeList
Function
see `dojo.forEach()`. The primary difference is that the acted-on array is implicitly this NodeList. If you want the option to break out of the forEach loop, use every() or some() instead.
dojo.NodeList
Function
Returns the box objects of all elements in a node list as an Array (*not* a NodeList). Acts like `dojo.coords`, though assumes the node passed is each node in this list.
Array
Function
Returns border-box objects (x/y/w/h) of all elements in a node list as an Array (*not* a NodeList). Acts like `dojo.position`, though assumes the node passed is each node in this list.
Array
Function
the attribute to get/set
optional. The value to set the property to
gets or sets the DOM attribute for every element in the NodeList. See also `dojo.attr`
if no value is passed, the result is an array of attribute values If a value is passed, the return is this NodeList
dojo.NodeList|Array
Make all nodes with a particular class focusable: dojo.query(".focusable").attr("tabIndex", -1);
Disable a group of buttons: dojo.query("button.group").attr("disabled", true);
innerHTML can be assigned or retrieved as well: // get the innerHTML (as an array) for each list item var ih = dojo.query("li.replaceable").attr("innerHTML");
Function
the CSS property to get/set, in JavaScript notation ("lineHieght" instead of "line-height")
optional. The value to set the property to
gets or sets the CSS property for every element in the NodeList
if no value is passed, the result is an array of strings. If a value is passed, the return is this NodeList
dojo.NodeList|Array
Function
A String class name to add, or several space-separated class names, or an array of class names.
adds the specified class to every node in the list
dojo.NodeList
Function
An optional String class name to remove, or several space-separated class names, or an array of class names. If omitted, all class names will be deleted.
removes the specified class from every node in the list
dojo.NodeList, this list
dojo.NodeList
Function
the CSS class to add
If passed, true means to add the class, false means to remove.
Adds a class to node if not present, or removes if present. Pass a boolean condition if you want to explicitly add or remove.
dojo.NodeList
Function
the name of the method to attach to. For DOM events, this should be the lower-case name of the event
if 2 arguments are passed (methodName, objOrFunc), objOrFunc should reference a function or be the name of the function in the global namespace to attach. If 3 arguments are provided (methodName, objOrFunc, funcName), objOrFunc must be the scope to locate the bound function in
optional. A string naming the function in objOrFunc to bind to the event. May also be a function reference.
attach event handlers to every item of the NodeList. Uses dojo.connect() so event properties are normalized
add an onclick handler to every button on the page dojo.query("div:nth-child(odd)").connect("onclick", function(e){ console.log("clicked!"); });
attach foo.bar() to every odd div's onmouseover dojo.query("div:nth-child(odd)").connect("onmouseover", foo, "bar");
Function
clears all content from each node in the list. Effectively equivalent to removing all child nodes from every item in the list.
dojo.NodeList
Function
may be a string representing any valid CSS3 selector or a DOM node. In the selector case, only the first matching element will be used for relative positioning.
can be one of: "last" (default) "first" "before" "after" "only" "replace" or an offset in the childNodes property
places elements of this node list relative to the first element matched by queryOrNode. Returns the original NodeList. See: `dojo.place`
dojo.NodeList
Function
CSS selector like ".foo" or "div > span"
removes elements in this list that match the filter from their parents and returns them as a new NodeList.
`dojo.NodeList` containing the orphaned elements
dojo.NodeList
Function
a DOM node or a query string or a query result. Represents the nodes to be adopted relative to the first element of this NodeList.
can be one of: "last" (default) "first" "before" "after" "only" "replace" or an offset in the childNodes property
places any/all elements in queryOrListOrNode at a position relative to the first element in this list. Returns a dojo.NodeList of the adopted elements.
dojo.NodeList
Function
// | bacon is tasty, dontcha think?
// |
great comedians may not be funny in person
Returns a new list whose members match the passed query, assuming elements of the current NodeList as the root for each search.
Object|self|inline'd type check|Array|dojo.NodeList|Integer|Boolean
Function
If a string, a CSS rule like ".thinger" or "div > span".
"masks" the built-in javascript filter() method (supported in Dojo via `dojo.filter`) to support passing a simple string filter in addition to supporting filtering function objects.
dojo.NodeList
"regular" JS filter syntax as exposed in dojo.filter: dojo.query("*").filter(function(item){ // highlight every paragraph return (item.nodeName == "p"); }).style("backgroundColor", "yellow");
the same filtering using a CSS selector dojo.query("*").filter("p").styles("backgroundColor", "yellow");
Function
DOM node, HTML in string format, a NodeList or an Object. If a DOM node or NodeList, the content will be cloned if the current NodeList has more than one element. Only the DOM nodes are cloned, no event handlers. If it is an Object, it should be an object with at "template" String property that has the HTML string to insert. If dojo.string has already been dojo.required, then dojo.string.substitute will be used on the "template" to generate the final HTML string. Other allowed properties on the object are: "parse" if the HTML string should be parsed for widgets (dojo.require("dojo.parser") to get that option to work), and "templateFunc" if a template function besides dojo.string.substitute should be used to transform the "template".
can be one of: "last"||"end" (default) "first||"start" "before" "after" "replace" (replaces nodes in this NodeList with new content) "only" (removes other children of the nodes so new content is the only child) or an offset in the childNodes property
add a node, NodeList or some HTML as a string to every item in the list. Returns the original list.
a copy of the HTML content is added to each item in the list, with an optional position argument. If no position argument is provided, the content is appended to the end of each item.
dojo.NodeList
appends content to the end if the position is omitted dojo.query("h3 > p").addContent("hey there!");
add something to the front of each element that has a "thinger" property: dojo.query("[thinger]").addContent("...", "first");
adds a header before each element of the list dojo.query(".note").addContent("<h4>NOTE:</h4>", "before");
add a clone of a DOM node to the end of every element in the list, removing it from its existing parent. dojo.query(".note").addContent(dojo.byId("foo"));
Append nodes from a templatized string. dojo.require("dojo.string"); dojo.query(".note").addContent({ template: '<b>${id}: </b><span>${name}</span>', id: "user332", name: "Mr. Anderson" });
Append nodes from a templatized string that also has widgets parsed. dojo.require("dojo.string"); dojo.require("dojo.parser"); var notes = dojo.query(".note").addContent({ template: '<button dojoType="dijit.form.Button">${text}</button>', parse: true, text: "Send" });
Function
Create a new instance of a specified class, using the specified properties and each node in the nodeList as a srcNodeRef.
Grabs all buttons in the page and converts them to diji.form.Buttons. var buttons = dojo.query("button").instantiate("dijit.form.Button", {showLabel: true});
Function
One or more 0-based indices of items in the current NodeList. A negative index will start at the end of the list and go backwards.
Returns a new NodeList comprised of items in this NodeList at the given index or indices.
dojo.NodeList
dojo.NodeList
Shorten the list to the first, second, and third elements dojo.query("a").at(0, 1, 2).forEach(fn);
Retrieve the first and last elements of a unordered list: dojo.query("ul > li").at(0, -1).forEach(cb);
Do something for the first element only, but end() out back to the original list and continue chaining: dojo.query("a").at(0).onclick(fn).end().forEach(function(n){ console.log(n); // all anchors on the page. })
Object