Documentation
dojo.forEach¶
Contents
About¶
Since it’s not supported natively on every browser, dojo.forEach provides the standard JavaScript 1.6 forEach construct everywhere. dojo.forEach lets you apply a function to each element of an array, emulating a for loop, but with fewer scoping compliations.
dojo.forEach has a notable difference from the JavaScript 1.6 forEach: dojo.forEach runs over sparse arrays, passing the “holes” in the sparse array to the callback function. JavaScript 1.6’s forEach skips the holes in the sparse array.
dojo.forEach() cannot terminate a loop (save for throwing an exception). Use dojo.some() or dojo.every() instead.
forEach is syntactic sugar for a regular ‘ol for loop:
for(var i=0; i<queueEntries.length; i++){
console.debug(queueEntries[i], "at index", i);
}
(From dojo 1.7 on) It can be written as:
require(["dojo/_base/array"], function(array){
array.forEach(queueEntries, function(entry, i){
console.debug(entry, "at index", i);
});
});
(Before dojo 1.7) It can be written as:
dojo.forEach(queueEntries, function(entry, i){
console.debug(entry, "at index", i);
});
We use an anonymous function to define the operation. This function is always passed 3 arguments: the current item value, the index in the list being iterated over, an a reference to the list itself.
For this simple loop, dojo.forEach isn’t anything exciting. But combined with other Dojo functions, especially dojo.query(), it becomes remarkably useful. Consider this snippet, which disables all <select> tags on the page:
// Dojo 1.7+ (AMD)
require(["dojo/_base/array", "dojo/query"], function(array, query){
array.forEach(
query("select"),
function(selectTag){
selectTag.disabled = true;
}
);
});
// Dojo < 1.7
dojo.forEach(
dojo.query("select"),
function(selectTag){
selectTag.disabled = true;
}
);
How cool is that? (Answer: very!) There’s no monkeying around with DOM functions, no using tedious names or id’s, and it continues to work even when you add new SELECT tags.
Running dojo.forEach on a dojo.query result is so common, that Dojo defines a shortcut:
// Dojo 1.7+ (AMD)
require(["dojo/query"], function(query){
query("select").forEach(function(selectTag){
selectTag.disabled = true;
});
});
// Dojo < 1.7
dojo.query("select").forEach(function(selectTag){
selectTag.disabled = true;
});
does the same thing. But that’s not all! New in 1.0 you can collapse the function down to its body, passed in as a string like so:
// Dojo 1.7+ (AMD)
require(["dojo/query"], function(query){
query("select").forEach("item.disabled = true;");
});
// Dojo < 1.7
dojo.query("select").forEach("item.disabled = true;");
That’s a lot of functionality from a single method! Once you get used to the syntax, you’ll never want to go back.
API Info¶
full API: | http://dojotoolkit.org/api/dojo/forEach |
---|---|
summary: | for every item in arr, callback is invoked. Return values are ignored. If you want to break out of the loop, consider using dojo.every() or dojo.some(). forEach does not allow breaking out of the loop over the items in arr. |
Parameters¶
Signature
dojo.forEach( /* Array|String */ arr, /* Function|String */ callback, /* Object */ thisObject)
Overview
- arr Array|String
- callback Function|String
- thisObject Object
Examples¶
// log out all members of the array: dojo.forEach(
[ "thinger", "blah", "howdy", 10 ],
function(item){
console.log(item);
}
);
// log out the members and their indexes dojo.forEach(
[ "thinger", "blah", "howdy", 10 ],
function(item, idx, arr){
console.log(item, "at index:", idx);
}
);
// use a scoped object member as the callback
var obj = {
prefix: "logged via obj.callback:",
callback: function(item){
console.log(this.prefix, item);
}
};
// specifying the scope function executes the callback in that scope dojo.forEach(
[ "thinger", "blah", "howdy", 10 ],
obj.callback,
obj
);
// alternately, we can accomplish the same thing with dojo.hitch() dojo.forEach(
[ "thinger", "blah", "howdy", 10 ],
dojo.hitch(obj, "callback")
);
See Also¶
- dojo.map - The Dojo version of Array.map
- dojo.filter - Helps you narrow down the items in a list
- dojo.some - Does any item in the list meet your criteria?
- dojo.every - Do all items in the list meet your criteria?
- dojo.indexOf - Find something in a list easily
- dojo.lastIndexOf - Find something in the list easily, but starting from the back
- dojo.query - A CSS query engine that returns instances of dojo.NodeList
- dojo.NodeList - A subclass of Array which can also have forEach applied.