Collection is a generic object that stores an array of items of the same type. It provides useful utility methods for working with items in the Collection, including filter(), find(), and reduce().

A Collection can be of any type. For example, GraphicsLayer.graphics is a collection of graphics that are stored in the GraphicsLayer. You can use the methods found in the Collection class to add, remove, re-order, or manipulate graphics in a GraphicsLayer.

Another example of a Collection is Map.layers, which is a Collection of operational layers included in the Map.

// Removes a layer from the map using Collection.remove();
map.layers.remove(layer);

The change event fires each time an item is added, moved, or removed from the Collection. Since properties of type Collection cannot be watched, the change event should be used to notify the developer/user of changes made to the collection.

Filters the Collection's items based on a test defined by the callback function. Each item is passed into the callback function, which returns true if the item passes the test and false if it does not.

// filteredLayers is a Collection of all the non-visible layers in the mapvar filteredLayers = map.layers.filter(function(layer){
return !layer.visible;
});

find(callback){*}

Returns an item in the Collection if that item passes a test as defined in the callback function. Each item is passed into the callback function, which returns true if the item passes the test and false if it does not.

// If the id of a map layer is already known, get the layer that matches the idvar myLayer = map.layers.find(function(layer){
return layer.id === "speciesLyr01";
});
// myLayer references the layer in map with ID "speciesLyr01"

Returns the index of an item in the Collection if that item passes a test as defined in the callback function. Each item is passed into the callback function, which returns true if the item passes the test and false if it does not.

// gpcIndex is assigned the index of the first graphic whose name// property is 'Redlands'. This result can be used in getItemAt()var gpcIndex = graphicsLyr.graphics.findIndex(function(item){
return item.attributes.name === "Redlands";
});

Flattens a hierarchical Collection containing at least one child collection. Each item in the collection is passed into the callback function, which should check for child collections specified by the developer. A flat collection of all items (parent and children) is returned.

This is useful for scenarios where the user would like to search all the layers in a map, including a GroupLayer's layers and a MapImageLayer's sublayers. The callback should return the sub-collection of the item. If multiple levels of collections exist in the hierarchy, then this method recursively executes for all sub-collections.

Returns a flat collection of all items in the original collection and their children.

Example:

// create a MapImageLayer with several sublayers and add to a map// containing another GraphicsLayervar layer = new MapImageLayer({ sublayers: [ ... ] });
var map = newMap({
layers: [ layer, new GraphicsLayer() ]
});
// A flat collection of all layers and sublayers// (if layer is a MapImageLayer) in the map.// This collection may be searched or used for other purposesvar allLayersAndSublayers = map.layers.flatten(function(item){
return item.layers || item.sublayers;
});

Passes each Collection item into the callback function and returns a new array of the returned values. For example, if you have a Collection of numbers and would like to add each number by 10, you can use map() to create a new Collection with the same numbers incremented by 10.

Removes each item in the input array. If an item is present multiple times in the collection, only the first occurrence is removed. The change event is fired after an item is removed from the Collection.

// Get the first two layers in a mapvar layer1 = map.layers.getItemAt(0);
var layer2 = map.layers.getItemAt(1);
// Moves the second layer to the first position in the map.layers Collection// effectively swapping the positions of layer1 and layer2
map.layers.reorder(layer2, 0);

// If at least one of the point graphics has a geometry whose// elevation is above 1000m, then passes will have a value of true.// Otherwise, it will be false.var passes = graphicsLayer.graphics.some(function(item, i){
return item.geometry.z > 1000;
});

// prevents a layer from being added to the map more than once.
map.layers.on("before-add", function(event){
if(map.layers.includes(event.item){
event.preventDefault();
console.log("layer already exists in map.");
}
});

before-changes

Fires before any modifications are performed on the collection. This event can be used to prevent an item from being added or removed from the collection by cancelling it with the event.preventDefault() method.

// This function will fire each time a layer is either added,// moved, or removed from the map.layers Collection
map.layers.on("change", function(event){
var newLayers = event.added; // An array of layers added to the map.layers Collectionvar reorderedLayers = event.moved; // An array of layers moved in the Collectionvar removedLayers = event.removed; // An array of layers removed from map
});