Working with collections

The last section for this chapter is about the OpenLayers' Collection class, ol.Collection. As mentioned, the Collection class is not a super class like Observable and Object, but it is an integral part of the relationship model. Many classes in OpenLayers make use of the Collection class to manage one-to-many relationships.

At its core, the Collection class is a JavaScript array with additional convenience methods. It also inherits directly from the Object class and inherits the functionality of both Observable and Object. This makes the Collection class extremely powerful and we will use it many times in the rest of this book.

Creating a collection

A collection is created just like any other class, just use the new operator:

var collection = new ol.Collection();

The Collection constructor takes one optional argument, an array that is used to initially populate the collection with elements. The elements in the array can be of any type, but if you are using the collection with one of the OpenLayers API methods, the type of the values will typically be specified in the API documentation. For instance, the Map class constructor allows passing a collection of layers, interactions, controls, and overlays. In these cases, the contents of the collection must be instances of the correct type of an object. For instance, check the following code snippet:

var layer1 = new ol.layer.Tile({/*options */);
var layer2 = new ol.layer.Vector({/* options */});
var layerCollection = new ol.Collection([layer1, layer2]);
var map = new ol.Map({
  layers: layerCollection
});

Collection properties

A Collection class, inherited from the Object class, has one observable property, length. When a collection changes (elements are added or removed), its length property is updated. This means it also emits an event, change:length, when the length property is changed.

Collection events

A Collection class also inherits the functionality of the Observable class (via Object class) and emits two other events—add and remove. Registered event handler functions of both events will receive a single argument, a CollectionEvent, that has an element property with the element that was added or removed.

Collection methods

The Collection class has the following methods (the ones from Object and Observable classes are not included in this list, but those methods are also available):

Method	Parameters	Description
`clear()`	`none`	This removes all elements from the collection.
`extend(arr)`	`arr` – `array`	This adds the elements from the `arr` parameter to the collection.
`forEach(iterator, opt_this)`	`iterator` – `function` `opt_this` – `optional, object`	This method invokes the `iterator` function for each element in the collection, passing the element, index and a reference to the collection itself as arguments. If the `opt_this` parameter is provided, it will be the value of `this` inside the iterator function.
`getArray()`	`none`	This returns a reference to the internal array managed by the collection, which is useful if you need a real JavaScript array for something. You should not modify the array returned by this value as no events will be triggered and the `length` property will go out of sync.
`insertAt(index, element)`	`index` – `number` `element` – `mixed`	This inserts an element into the collection at the given index. This will change the length of the array.
`item(index)`	`index` – `number`	This returns the element at the given index.
`pop()`	`none`	This removes the last element from the collection and returns it.
`push(element)`	`element` – `mixed`	This adds an element to the end of the collection and returns the new length.
`remove(element)`	`element` – `mixed`	This removes the first occurrence of the element from the collection.
`removeAt(index)`	`index` – `number`	This removes the element at the given index and returns it.
`setAt(index, element)`	`index` – `number` `element` – `mixed`	This replaces an element at a given index with a new element.

Previous Chapter

Time for action – using bindTo

Next Chapter

Summary

Table of Contents for OpenLayers 3 : Beginner's Guide

Working with collections

Creating a collection

Collection properties

Collection events

Collection methods

Table of Contents for
OpenLayers 3 : Beginner's Guide