API Documentation

Choose a stylesheet:

dojo.NodeList

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.

Examples

Example 1

create a node list from a node

new dojo.NodeList(dojo.byId("foo"));

Example 2

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 3

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>howdy!</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 4

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 5

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 6

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 7

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

NamespacesBack to top

dojo.NodeList.addContent(content: String|DomNode, position: String|Integer?): dojo.NodeList

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

dojo.NodeList.attr(property: String, value: String?): dojo.NodeList | Array

gets or sets the DOM attribute for every element in the NodeList

dojo.NodeList.style(property: String, value: String?): dojo.NodeList | Array

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

FunctionsBack to top

addClass(className: String): dojo.NodeList

Overrides

adds the specified class to every node in the list

adopt(queryOrListOrNode: String|Array|DomNode, position: String?): dojo.NodeList

Overrides

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.

anim(properties: Object, duration: Integer?, easing: Function?, onEnd: Function?, delay: Integer?): dojo._Animation

Overrides

Animate one or more CSS properties for all nodes in this list. The returned animation object will already be playing when it is returned. See the docs for dojo.anim for full details.

animateProperty(args): dojo._Animation

Overrides

see dojo.animateProperty(). Animate all elements of this NodeList across the properties specified.

at(index: Integer...): dojo.NodeList

Overrides

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

concat(item: Object?): dojo.NodeList

Overrides

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

connect(methodName: String, objOrFunc: Object|Function|String, funcName: String?)

Overrides

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

coords(): Array

Overrides

Returns the box objects all elements in a node list as an Array (*not* a NodeList)

dtl(template: dojox.dtl.__StringArgs|String, context: dojox.dtl.__ObjectArgs|Object)

Overrides

empty(): dojo.NodeList

Overrides

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

every(callback: Function:, thisObject: Object:?): Boolean

Overrides

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

fadeIn(args): dojo._Animation

Overrides

fade in all elements of this NodeList. Returns an instance of dojo._Animation

fadeOut(args): dojo._Animation

Overrides

fade out all elements of this NodeList. Returns an instance of dojo._Animation

fadeTo(args)

Overrides

fade all elements of the node list to a specified opacity

filter(simpleFilter: String|Function): dojo.NodeList

Overrides

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

forEach(callback, thisObj): dojo.NodeList

Overrides

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

highlight(args): dojo._Animation

Overrides

highlight all elements of the node list. Returns an instance of dojo._Animation

html(content, params: Object?): dojo.NodeList

Overrides

see dojo.html.set(). Set the content of all elements of this NodeList

indexOf(value: Object:, fromIndex: Integer:?): Integer

Overrides

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

instantiate(declaredClass: String|Object, properties: Object?): dojo.NodeList

Overrides

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

lastIndexOf(value: Object, fromIndex: Integer?): Integer

Overrides

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

map(func: Function, obj: Function?): dojo.NodeList

Overrides

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

orphan(simpleFilter: String?): dojo.NodeList

Overrides

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

place(queryOrNode: String|Node, position: String): dojo.NodeList

Overrides

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

query(queryStr: String): dojo.NodeList

Overrides

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

removeClass(className: String): dojo.NodeList

Overrides

removes the specified class from every node in the list

sizeTo(args): dojo._Animation

Overrides

size all elements of this NodeList. Returns an instance of dojo._Animation

slice(begin: Integer, end: Integer?)

Overrides

Returns a new NodeList, maintaining this one in place

slideBy(args): dojo._Animation

Overrides

slide all elements of this NodeList. Returns an instance of dojo._Animation

slideTo(args): dojo._Animation

Overrides

slide all elements of the node list to the specified place. Returns an instance of dojo._Animation

some(callback: Function:, thisObject: Object:?): Boolean

Overrides

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

splice(index: Integer, howmany: Integer?, item: Object?)

Overrides

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

toggleClass(className: String, condition: Boolean?): dojo.NodeList

Overrides

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

wipeIn(args): dojo._Animation

Overrides

wipe in all elements of this NodeList. Returns an instance of dojo._Animation

wipeOut(args): dojo._Animation

Overrides

wipe out all elements of this NodeList. Returns an instance of dojo._Animation

wipeTo(args)

Overrides

Wipe all elements of the NodeList to a specified width: or height:

_anim(obj, method, args)

Overrides

PropertiesBack to top

dojo.NodeList._adaptAsFilter

dojo.NodeList._adaptAsForEach

dojo.NodeList._adaptAsMap

dojo.NodeList._adaptWithCondition

dojo.NodeList._wrap

Navigating the Dojo API Tool

There are several different methods of navigating through the object structure of the Dojo Toolkit:

Use the namespace list (to the left). The simplest method would be to use the list of namespaces defined by the Dojo Toolkit, on the left side of every page.
Drill-down from where you are. The API Tool was designed to give you as much information via drill-down as possible. Everything defined in an object can be clicked on, for more information.
Use the search. At the top of the namespace list to the left is a search box; type in the terms you are looking for, and you will be taken to a result page that spans the entire toolkit.

In addition, objects with large numbers of contained types have a simple way of jumping to sections on a page; simply look at the right side of any heading, and you will see a set of quick navigation icons. Clicking a type icon will take you to that section; clicking the up arrow icon will return you to the top of the page.

Inherited and private members

The Dojo API Tool will show the full ancestry of an object's members (including how that member was defined and whether or not it overrides an original). By default, all members of an object that are inherited are shown with the object's API listing, and all private members are hidden.

To toggle either inherited or private members, look just beneath the breadcrumb bar (above the name of the object you are viewing) and click the appropriate link.

Switching styles

The Dojo API Tool was designed with several themes in mind; we know that some people prefer light on dark, while others might prefer dark on light. With this in mind, two themes (Noir and Blanc) are currently available, with more on the way.

To switch visual styles, click on the theme you want to use, near the top right corner of the page. The API Tool will remember which style you prefer and automatically load that theme on subsequent visits.

Key/Legend

Namespaces

A namespace in Dojo parlance is an object/property bag that can contain almost anything: constructors, methods, properties, etc. Usually is expressly defined to serve a particular purpose; for example, dojo.date.locale is a namespace defined to deal with locale-specific date handling.

Constructors

A constructor is a function designed to create instances of objects. With the Dojo Toolkit, there are two ways of creating constructors: the "old school" way (i.e. defining a function with the this keyword in the body) or using dojo.declare.

Singletons

A singleton is a constructor that is defined and then immediately executed so that only one instance may ever exist during an application's lifetime. Usually this is done to capture some information in the environment, or to ensure a set of private variables that cannot be accessed from outside of the declaration. Examples include dojox.encoding.crypto.Blowfish.

Data Types

Array

Arrays are ordered lists, native to Javascript.

Boolean

Native data type representing a simple "true/false" value.

Date

Native Javascript data type to handle common date and time representations.

Node

An object that represents any kind of element being referenced/used by Javascript code. Note that the type of element is not dictated by this data type; only that it is a node of some sort.

Error

A special, native Javascript object used to indicate an error in code. Can be subclassed and used in conjunction with the throw statement, i.e. throw new MySubError(...);

Function

Functions/methods are pieces of invocable code; in JavaScript, they are also considered data and can be passed around like any other object.

Number

A Number object is used to represent any kind of numeric value; note that Javascript does not guarentee the actual underlying datatype (though the most common is a 64-bit float).

Object

Objects are the base data type of Javascript. With the Dojo API Tool, a type that cannot be determined is usually marked with this icon, in addition to straight objects.

RegExp (Regular Expression)

A regular expression is an object used for fast string search and parsing.

String

A string is any sequence of characters.

Input formats

Filtered HTML:
- Web page addresses and e-mail addresses turn into links automatically.
- Allowed HTML tags: <a> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>
 
 This site allows HTML content. While learning all of HTML may feel intimidating, learning how to use a very small number of the most basic HTML "tags" is very easy.
 
 For more information see W3C's HTML Specifications or use your favorite search engine to find other sites that explain HTML.
 
 Most unusual characters can be directly entered without any problems.
 
 If you do encounter problems, try using HTML character entities. A common example looks like & for an ampersand & character. For a full list of entities see HTML's entities page.
- Lines and paragraphs are automatically recognized. The line break, paragraph and close paragraph tags are inserted automatically. If paragraphs are not recognized simply add a couple blank lines.
PHP code:
- Using custom PHP code
  
  If you know how to script in PHP, Drupal gives you the power to embed any script you like. It will be executed when the page is viewed and dynamically embedded into the page. This gives you amazing flexibility and power, but of course with that comes danger and insecurity if you do not write good code. If you are not familiar with PHP, SQL or with the site engine, avoid experimenting with PHP because you can corrupt your database or render your site insecure or even unusable! If you do not plan to do fancy stuff with your content then you are probably better off with straight HTML.
  
  Remember that the code within each PHP item must be valid PHP code - including things like correctly terminating statements with a semicolon. It is highly recommended that you develop your code separately using a simple test script on top of a test database before migrating to your production environment.
  
  Notes:
  - You can use global variables, such as configuration parameters, within the scope of your PHP code but remember that global variables which have been given values in your code will retain these values in the engine afterwards.
  - register_globals is now set to off by default. If you need form information you need to get it from the "superglobals" $_POST, $_GET, etc.
  - You can either use the print or return statement to output the actual content for your item.
  A basic example:
  You want to have a box with the title "Welcome" that you use to greet your visitors. The content for this box could be created by going:
```
print t("Welcome visitor, ... welcome message goes here ...");
								
```
  If we are however dealing with a registered user, we can customize the message by using:
```
global $user;
if ($user->uid) {
	print t("Welcome $user->name, ... welcome message goes here ...");
}
else {
	print t("Welcome visitor, ... welcome message goes here ...");
}
								
```
  For more in-depth examples, we recommend that you check the existing Drupal code and use it as a starting point, especially for sidebar boxes.
Full HTML:
- Web page addresses and e-mail addresses turn into links automatically.
- Lines and paragraphs are automatically recognized. The line break, paragraph and close paragraph tags are inserted automatically. If paragraphs are not recognized simply add a couple blank lines.
Markdown:
- Quick Tips:
  - Two or more spaces at a line's end = Line break
  - Double returns = Paragraph
  - *Single asterisks* or _single underscores_ = Emphasis
  - **Double** or __double__ = Strong
  - This is [a link](http://the.link.com "The optional title text")
  For complete details on the Markdown syntax, see the Markdown documentation.

dojo.NodeList

Examples

Example 1

Example 2

Example 3

Example 4

Example 5

Example 6

Example 7

NamespacesBack to top

FunctionsBack to top

PropertiesBack to top

Navigating the Dojo API Tool

Inherited and private members

Switching styles

Key/Legend

Data Types

Input formats

Using custom PHP code