dojo/_base/NodeList.js

• Provides:

  • dojo._base.NodeList

• Requires:

  • dojo.lib.kernel in common
  • dojo._base.lang in common
  • dojo._base.array in common
  • dojo._base.connect in common
  • dojo._base.html in common

• dojo.NodeList

  • type

    Function

  • summary

    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.

  • description

    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.

  • example

    create a node list from a node
    	new dojo.NodeList(dojo.byId("foo"));

  • example

    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);
    	});

  • example

    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

  • example

    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();

  • example

    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");

  • example

    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);

  • example

    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);

• dojo.NodeList._normalize

  • parameters:
    • content: (typeof String||Element||Object||NodeList)
    • refNode: (typeof DOMNode)
  • returns

    Array

  • summary

    normalizes data to an array of items to insert.

  • description

    If content is an object, it can have special properties "template" and
    "parse". If "template" is defined, then the template value is run through
    dojo.string.substitute (if dojo.string.substitute has been dojo.required elsewhere),
    or if templateFunc is a function on the content, that function will be used to
    transform the template into a final string to be used for for passing to dojo._toDom.
    If content.parse is true, then it is remembered for later, for when the content
    nodes are inserted into the DOM. At that point, the nodes will be parsed for widgets
    (if dojo.parser has been dojo.required elsewhere).

  • type

    Function

• dojo.NodeList._cloneNode

  • parameters:
    • node: (typeof DOMNode)
  • summary

    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.

  • type

    Function

• dojo.NodeList._place

  • parameters:
    • ary: (typeof Array)
    • refNode: (typeof DOMNode)
    • position: (typeof String)
    • useClone: (typeof Boolean)
  • summary

    private utility to handle placing an array of nodes relative to another node.

  • description

    Allows for cloning the nodes in the array, and for
    optionally parsing widgets, if ary._runParse is true.

  • type

    Function

• dojo.NodeList._stash

  • parameters:
    • parent
  • returns

    dojo.NodeList

  • summary

    private function to hold to a parent NodeList. end() to return the parent NodeList.

  • example

    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")

  • type

    Function

• dojo.NodeList._stash._parent

• dojo.NodeList.end

  • summary

    Ends use of the current <code>dojo.NodeList</code> by returning the previous dojo.NodeList
    that generated the current dojo.NodeList.

  • description

    Returns the `dojo.NodeList` that generated the current `dojo.NodeList`. If there
    is no parent dojo.NodeList, an empty dojo.NodeList is returned.

  • example

    	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(...)

  • type

    Function

• dojo.NodeList.slice

  • parameters:
    • begin: (typeof Integer)

      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)

    • end: (typeof Integer)

      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.

  • summary

    Returns a new NodeList, maintaining this one in place

  • description

    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]

  • type

    Function

• dojo.NodeList.splice

  • parameters:
    • index: (typeof Integer)

      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)

    • howmany: (typeof Integer)

      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.

    • item: (typeof Object)

      Any number of optional parameters may be passed in to be
      spliced into the NodeList

  • summary

    Returns a new NodeList, manipulating this NodeList based on
    the arguments passed, potentially splicing in new elements
    at an offset, optionally deleting elements

  • description

    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.

  • return_summary

    dojo.NodeList

  • type

    Function

• dojo.NodeList.indexOf

  • parameters:
    • value: (typeof Object:)

      The value to search for.

    • fromIndex: (typeof Integer:)

      The location to start searching from. Optional. Defaults to 0.

  • returns

    Integer

  • summary

    see dojo.indexOf(). The primary difference is that the acted-on
    array is implicitly this NodeList

  • description

    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]

  • return_summary

    Positive Integer or 0 for a match, -1 of not found.

  • type

    Function

• dojo.NodeList.lastIndexOf

  • parameters:
    • value: (typeof Object)

      The value to search for.

    • fromIndex: (typeof Integer)

      The location to start searching from. Optional. Defaults to 0.

  • returns

    Integer

  • summary

    see dojo.lastIndexOf(). The primary difference is that the
    acted-on array is implicitly this NodeList

  • description

    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]

  • return_summary

    Positive Integer or 0 for a match, -1 of not found.

  • type

    Function

• dojo.NodeList.every

  • parameters:
    • callback: (typeof Function:)

      the callback

    • thisObject: (typeof Object:)

      the context

  • returns

    Boolean

  • summary

    see <code>dojo.every()</code> 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

  • type

    Function

• dojo.NodeList.some

  • parameters:
    • callback: (typeof Function:)

      the callback

    • thisObject: (typeof Object:)

      the context

  • returns

    Boolean

  • summary

    Takes the same structure of arguments and returns as
    <code>dojo.some()</code> with the caveat that the passed array is
    implicitly this NodeList.  See <code>dojo.some()</code> and Mozilla's
    (Array.some
    documentation)[http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Array:some].

  • type

    Function

• dojo.NodeList.concat

  • parameters:
    • item: (typeof Object)

      Any number of optional parameters may be passed in to be
      spliced into the NodeList

  • returns

    dojo.NodeList

  • summary

    Returns a new NodeList comprised of items in this NodeList
    as well as items passed in as parameters

  • description

    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]

  • return_summary

    dojo.NodeList

  • type

    Function

• dojo.NodeList.map

  • parameters:
    • func: (typeof Function)
    • obj: (typeof Function)
  • returns

    dojo.NodeList

  • summary

    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

  • type

    Function

• dojo.NodeList.forEach

  • parameters:
    • callback
    • thisObj
  • returns

    dojo.NodeList

  • summary

    see <code>dojo.forEach()</code>. 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.

  • type

    Function

• dojo.NodeList.coords

  • returns

    Array

  • summary

    Returns the box objects of all elements in a node list as
    an Array (*not* a NodeList). Acts like <code>dojo.coords</code>, though assumes
    the node passed is each node in this list.

  • type

    Function

• dojo.NodeList.position

  • returns

    Array

  • summary

    Returns border-box objects (x/y/w/h) of all elements in a node list
    as an Array (*not* a NodeList). Acts like <code>dojo.position</code>, though
    assumes the node passed is each node in this list.

  • type

    Function

• dojo.NodeList.attr

  • parameters:
    • property: (typeof String)

      the attribute to get/set

    • value: (typeof String)

      optional. The value to set the property to

  • returns

    dojo.NodeList|Array

  • summary

    gets or sets the DOM attribute for every element in the
    NodeList. See also <code>dojo.attr</code>

  • return_summary

    if no value is passed, the result is an array of attribute values
    If a value is passed, the return is this NodeList

  • example

    Make all nodes with a particular class focusable:
    	dojo.query(".focusable").attr("tabIndex", -1);

  • example

    Disable a group of buttons:
    	dojo.query("button.group").attr("disabled", true);

  • example

    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");

  • type

    Function

• dojo.NodeList.style

  • parameters:
    • property: (typeof String)

      the CSS property to get/set, in JavaScript notation
      ("lineHieght" instead of "line-height")

    • value: (typeof String)

      optional. The value to set the property to

  • returns

    dojo.NodeList|Array

  • summary

    gets or sets the CSS property for every element in the NodeList

  • return_summary

    if no value is passed, the result is an array of strings.
    If a value is passed, the return is this NodeList

  • type

    Function

• dojo.NodeList.addClass

  • parameters:
    • className: (typeof String|Array)

      A String class name to add, or several space-separated class names,
      or an array of class names.

  • returns

    dojo.NodeList

  • summary

    adds the specified class to every node in the list

  • type

    Function

• dojo.NodeList.removeClass

  • parameters:
    • className: (typeof String|Array)

      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.

  • returns

    dojo.NodeList

  • summary

    removes the specified class from every node in the list

  • return_summary

    dojo.NodeList, this list

  • type

    Function

• dojo.NodeList.toggleClass

  • parameters:
    • className: (typeof String)

      the CSS class to add

    • condition: (typeof Boolean)

      If passed, true means to add the class, false means to remove.

  • returns

    dojo.NodeList

  • summary

    Adds a class to node if not present, or removes if present.
    Pass a boolean condition if you want to explicitly add or remove.

  • type

    Function

• dojo.NodeList.connect

  • parameters:
    • methodName: (typeof String)

      the name of the method to attach to. For DOM events, this should be
      the lower-case name of the event

    • objOrFunc: (typeof Object|Function|String)

      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

    • funcName: (typeof String)

      optional. A string naming the function in objOrFunc to bind to the
      event. May also be a function reference.

  • summary

    attach event handlers to every item of the NodeList. Uses dojo.connect()
    so event properties are normalized

  • example

    add an onclick handler to every button on the page
    	dojo.query("div:nth-child(odd)").connect("onclick", function(e){
    		console.log("clicked!");
    	});

  • example

    attach foo.bar() to every odd div's onmouseover
    	dojo.query("div:nth-child(odd)").connect("onmouseover", foo, "bar");

  • type

    Function

• dojo.NodeList.empty

  • returns

    dojo.NodeList

  • summary

    clears all content from each node in the list. Effectively
    equivalent to removing all child nodes from every item in
    the list.

  • type

    Function

• dojo.NodeList.place

  • parameters:
    • queryOrNode: (typeof String||Node)

      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.

    • position: (typeof String)

      can be one of:
      	"last" (default)
      	"first"
      	"before"
      	"after"
      	"only"
      	"replace"
      or an offset in the childNodes property

  • returns

    dojo.NodeList

  • summary

    places elements of this node list relative to the first element matched
    by queryOrNode. Returns the original NodeList. See: <code>dojo.place</code>

  • type

    Function

• dojo.NodeList.orphan

  • parameters:
    • filter: (typeof String)

      CSS selector like ".foo" or "div > span"

  • returns

    dojo.NodeList

  • summary

    removes elements in this list that match the filter
    from their parents and returns them as a new NodeList.

  • return_summary

    `dojo.NodeList` containing the orphaned elements

  • type

    Function

• dojo.NodeList.adopt

  • parameters:
    • queryOrListOrNode: (typeof String||Array||DomNode)

      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.

    • position: (typeof String)

      can be one of:
      	"last" (default)
      	"first"
      	"before"
      	"after"
      	"only"
      	"replace"
      or an offset in the childNodes property

  • returns

    dojo.NodeList

  • summary

    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.

  • type

    Function

• dojo.NodeList.query

  • parameters:
    • queryStr: (typeof String)
  • returns

    dojo.NodeList

  • summary

    Returns a new list whose members match the passed query,
    assuming elements of the current NodeList as the root for
    each search.

  • example

    assume a DOM created by this markup:
    	<div id="foo">
    		<p>
    			bacon is tasty, <span>dontcha think?</span>
    		</p>
    	</div>
    	<div id="bar">
    		<p>great comedians may not be funny <span>in person</span></p>
    	</div>
    If we are presented with the following definition for a NodeList:
    	var l = new dojo.NodeList(dojo.byId("foo"), dojo.byId("bar"));
    it's possible to find all span elements under paragraphs
    contained by these elements with this sub-query:
     	var spans = l.query("p span");

  • type

    Function

• dojo.NodeList.filter

  • parameters:
    • filter: (typeof String|Function)

      If a string, a CSS rule like ".thinger" or "div > span".

  • returns

    dojo.NodeList

  • summary

    "masks" the built-in javascript filter() method (supported
    in Dojo via <code>dojo.filter</code>) to support passing a simple
    string filter in addition to supporting filtering function
    objects.

  • example

    "regular" JS filter syntax as exposed in dojo.filter:
    	dojo.query("*").filter(function(item){
    		// highlight every paragraph
    		return (item.nodeName == "p");
    	}).style("backgroundColor", "yellow");

  • example

    the same filtering using a CSS selector
    	dojo.query("*").filter("p").styles("backgroundColor", "yellow");

  • type

    Function

• dojo.NodeList.addContent

  • parameters:
    • content: (typeof String||DomNode||Object||dojo.NodeList)

      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".

    • position: (typeof String||Integer)

      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

  • returns

    dojo.NodeList

  • summary

    add a node, NodeList or some HTML as a string to every item in the
    list.  Returns the original list.

  • description

    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.

  • example

    appends content to the end if the position is omitted
    	dojo.query("h3 > p").addContent("hey there!");

  • example

    add something to the front of each element that has a
    "thinger" property:
    	dojo.query("[thinger]").addContent("...", "first");

  • example

    adds a header before each element of the list
    	dojo.query(".note").addContent("<h4>NOTE:</h4>", "before");

  • example

    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"));

  • example

    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"
    });

  • example

    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"
    });

  • type

    Function

• dojo.NodeList.instantiate

  • parameters:
    • declaredClass: (typeof String|Object)
    • properties: (typeof Object)
  • summary

    Create a new instance of a specified class, using the
    specified properties and each node in the nodeList as a
    srcNodeRef.

  • example

    Grabs all buttons in the page and converts them to diji.form.Buttons.
    	var buttons = dojo.query("button").instantiate("dijit.form.Button", {showLabel: true});

  • type

    Function

• dojo.NodeList.at

  • parameters:
    • index: (typeof Integer)

      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

    dojo.NodeList

  • summary

    Returns a new NodeList comprised of items in this NodeList
    at the given index or indices.

  • example

    Shorten the list to the first, second, and third elements
    	dojo.query("a").at(0, 1, 2).forEach(fn);

  • example

    Retrieve the first and last elements of a unordered list:
    	dojo.query("ul > li").at(0, -1).forEach(cb);

  • example

    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.
    	})

  • return_summary

    dojo.NodeList

  • type

    Function

• dojo

  • alias - dojo

• Array

  • alias - Array.prototype

• Array.slice

  • alias - Array.prototype.slice

• Array.concat

  • alias - Array.prototype.concat

• dojo._NodeListCtor

  • alias - dojo.NodeList

• dojo.NodeList._wrap

  • alias - tnl

• dojo.NodeList._adaptAsMap

  • alias - adaptAsMap

• dojo.NodeList._adaptAsForEach

  • alias - adaptAsForEach

• dojo.NodeList._adaptAsFilter

  • alias - adaptAsFilter

• dojo.NodeList._adaptWithCondition

  • alias - adaptWithCondition

• dojo.NodeList.events

  • type

    Array

• dojo._base.NodeList

  • type

    Object

• dojo._base

  • type

    Object