Vector sources

The vector layer class by itself isn't very useful—it relies on other classes to do all the interesting work. Let's look at the source class, ol.source.vector, and its subclasses first as it's the only thing that is absolutely needed to get a working vector layer.

The vector source class is named after its purpose—to be a source of vector features for a vector layer. It is responsible for fetching features when needed, providing them to the vector layer for rendering, and also for retrieving features based on various criteria. We won't actually use the vector source class as it is a base class for the classes we'll actually be using, such as ol.source.GeoJSON in the preceding example. The following diagram shows how the vector source classes fit together in the OpenLayers architecture:

As you can see, there are quite a few classes in the OpenLayers library that deal with vector formats. The classes that you can create new objects from are highlighted in green. We'll briefly describe each class before we get into more detail:

ol.source.Vector: This is the base class for all vector sources. It provides a common API for accessing features in a vector source.
ol.source.Cluster: This source automatically groups features together when they are close to each other, and represents the group as a single feature. The cluster source uses another vector source to access features to be clustered.
ol.source.FormatVector: This class provides a common API for sources that use a format for reading and writing features. You cannot create an instance of this class.
ol.source.ServerVector: This source uses a loader function that can retrieve vector features on the fly from a server, for example, a WFS (Web Feature Service) server.
ol.source.TileVector: This source loads vector features in batches based on a tiling scheme similar to how raster layers load image tiles.
ol.source.StaticVector: This source loads vector features from a file in a specific format. It is considered static in that all the available features are read from the file when it is loaded. Although you can create an instance of this class, you will normally use one of the format-specific subclasses.
ol.source.GeoJSON: This source reads a file containing features in the GeoJSON format, a standardized encoding of geographic features using JSON.
ol.source.GPX: This source reads a file containing features in the GPX (GPS Exchange format), a common file format for GPS devices.
ol.source.IGC: This source reads a file in the IGC (International Glider Commission) format, a standard format for recording glider flights.
ol.source.KML: This source reads a file in the KML (Keyhole Markup Language), an XML-based format used in Google Maps and related products.
ol.source.OSMXML: This source reads a file using the Open Street Map XML schema.
ol.source.TopoJSON: This source reads a file encoded in JSON using the TopoJSON specification, an extension of GeoJSON that encodes topology information.

The vector source class

The vector source class, ol.source.vector, not only provides a common API for all vector sources but is also be instantiated and used directly. All of its subclasses primarily deal with actually retrieving vector features, but all the useful methods for actually interacting with features once they have been processed exist in this class. You can use this class if you have an existing set of vector features or are getting features in some way not directly supported by the subclasses. Some examples might include:

Using a mobile device's GPS to track the user's current location and creating waypoints or tracks based on changes in location
Programmatically generating features
Reading features from a legacy system that is not directly supported by OpenLayers

The vector source constructor takes the following options:

Name	Type	Description
`attributions`	`Array.<ol.Attribution> \| undefined`	This is an array of attribution objects that describe the provenance of the data. The attributions will be displayed on the map in the attribution area when features from this source are rendered on the map.
`features`	`Array.<ol.Feature> \| undefined`	This is an array of feature objects initially added to this source.
`logo`	`string \| olx.LogoOptions \| undefined`	This is a logo object that represents an image logo to be displayed on the map when features from this source are rendered on the map.
`projection`	`ol.proj.ProjectionLike`	This is the projection of the features in this source, or rather the projection of the features' geometries. The projection must be specified.
`state`	`ol.source.State \| undefined`	This is the state of the source, either one of loading, ready, or error.

The vector source also provides the following methods:

Method	Parameters	Description
`addFeature(feature)`	`ol.Feature`	This adds a single feature to this source, triggering the `addfeature` event. A redraw of the map will be scheduled if the feature should appear in the current map area being viewed.
`addFeatures(features)`	`Array.<ol.Feature>`	This adds an array of features to this source. The `addfeature` event will be triggered for each feature added. As with `addFeature`, a redraw of the map will be scheduled if any of the features need to be drawn.
`clear`	`none`	This removes all features from the source. This will trigger the `removefeature` event for each feature as it is removed and schedule a redraw of the map if any of the features were visible on the map.
`forEachFeature(callback, scope)`	`callback – function` `scope – object \| null`	This method calls the callback function for each feature in the source. The callback function will be called with a feature as its only argument. Within the callback function, the value of this will be the `scope`, if provided.
`forEachFeatureInExtent(extent, callback, scope)`	`extent – ol.Extent` `callback – function` `scope – object \| null`	This method works the same way as `forEachFeature` except that it first filters the features by the provided extent. Contrary to what the method name implies, the features may not actually be within the provided extent. Rather, features whose extent intersects the provided extent are included.
`getClosestFeatureToCoordinate(coordinate)`	`ol.Coordinate`	This method returns the feature that is closest to the provided coordinate. If there are several features equidistant to the coordinate, it is indeterminate which will be returned.
`getExtent()`	`none`	This returns an `ol.Extent` object representing the extent all the features currently in this source.
`getFeatureById()`	`id – string \| number`	This method returns a feature whose ID equals the passed value. For performance, the type of the `id` is not used to determine equality. This means that a string value of `2` will match a numeric value of `2`. If multiple features have the same `id`, it is indeterminate which will be returned.
`getFeatures()`	`none`	This method returns all the features of this source as an array.
`getFeaturesAtCoordinate(coordinate)`	`ol.Coordinate`	This method returns an array of features whose extent contains the given coordinate.
`removeFeature(feature)`	`ol.Feature`	This method removes a single feature from the source and triggers the `removefeature` event. Removing a feature will schedule a redraw of the map if the feature is currently visible.

The vector source can trigger the following events:

addfeature: This event is triggered when a feature is added to the source
removefeature: This event is triggered when a feature is removed from the source

The cluster source

There are two subclasses of the vector source, FormatVector and Cluster. The FormatVector class is the basis for many subclasses that obtain features by reading them from some specifically formatted data such as GeoJSON or KML. We'll look into these classes shortly, but first let's take a brief look at the cluster source.

The cluster source dynamically groups (or clusters) features that are near each other based on the current resolution, or zoom level, of a map's view and represents those groups as individual features. It does this by finding features within a certain distance of each other and creating a new feature to represent them. The new feature contains a reference to the original features that are represented by the clustered feature.

Creating a cluster source is the same as creating a vector source except the constructor options include two additional properties:

Name	Type	Description
`distance`	`number`	This is the minimum distance, in pixels, between clusters. Features that are less than this distance apart at the current zoom level will be clustered into a single feature.
`source`	`ol.source.vector`	This is a vector source that provides the features to be clustered.

Previous Chapter

The vector layer class

Next Chapter

Time for action – using the cluster source

Table of Contents for OpenLayers 3 : Beginner's Guide

Vector sources

The vector source class

The cluster source

Table of Contents for
OpenLayers 3 : Beginner's Guide