Time for action – geometries in action

The last example only used one linear ring for the polygon. Let's use the Web Inspector's console to create a polygon and then add a linear ring to see what happens. Open the vector_template.html file in your browser and then open the Web Inspector's Console. We'll be typing the commands into the console directly and observing the result on the map.

First, create a polygon using the preceding example:

var polygon = new ol.geom.Polygon([ [ [-20,-20],[-20,20],[20,20],[20,-20],[-20,-20] ] ]);

We'll need to reproject the coordinates into our view's projection:
```
polygon.transform('EPSG:4326', 'EPSG:3857');
```

Now, we'll need a source and a layer:

var source = new ol.source.vector({
  features: [new ol.Feature(polygon)],
  projection: 'EPSG:4326'
});
var layer = new ol.layer.vector({
  source: source,
  style: vectorStyle
});

And add it to the map:
```
map.addLayer(layer);
```
You should see something like the following screenshot:

Now create a linear ring that will make a hole in our polygon.

var linearRing = new ol.geom.LinearRing([ [-10,-10],[10,-10],[10,10],[-10,10],[-10,-10] ]);
linearRing.transform('EPSG:4326','EPSG:3857');
polygon.appendLinearRing(linearRing);

Now, it should look like the following screenshot:

What just happened?

We've just seen linear rings in action. When you create a polygon, the first linear ring is the outer boundary of the polygon and any other linear rings you create define holes in the outer ring.

Have a go hero

Try the last example again, only this time add two or more linear rings to the polygon and observe what happens.

The GeometryCollection class

The GeometryCollection class, as the name suggests, is a collection of geometry objects. Unlike the MultiPoint, MultiLine, and MultiPolygon classes, a GeometryCollection can contain any type of geometry. You can create an instance of ol.geom.GeometryCollection by passing an array of geometries to it, for example:

var geomCollection = new ol.geom.GeometryCollection([geom1, geom2, geom3]);

The GeometryCollection methods

Although you can use a GeometryCollection as an ol.geom.Geometry class anywhere, you can't use any of the SimpleGeometry methods on a GeometryCollection. Instead there is a separate API for accessing the geometries managed by the collection.

Method	Parameters	Description
`getGeometries()`	`None`	This returns an array of geometries managed by the collection.
`setGeometries`	`Array.<ol.geom.Geometry>`	This sets the array of geometries managed by the collection.

The Feature class

To complete our discussion of vector layers, we'll finish with the Feature class. We've already seen features in action—in fact, you can't display vector data without them—but we haven't really talked about what they are and what they do.

In the previous section, we explored the various OpenLayers Geometry classes. They contain the geospatial coordinates that represent a particular shape. However, to display a shape on the map, we need to work with features. When we model things in the real world and build data structures to represent their position, we also want to capture other information about them. A polygon representing the outline of a building is an interesting thing to display on a map, but when we click on it, it's pretty reasonable to expect to get some information about the building such as its address, its height, and building type (that is, commercial, industrial, or residential). These nonspatial properties of a feature can also be used to change the style of a shape on the map.

A feature combines these two concepts—the spatial location of a thing, and nonspatial properties of the thing that we are interested in.

Creating a feature

Creating a new feature is pretty straightforward; you just need to provide a geometry object (to create a feature with no extra properties) or an object literal containing the geometry and other properties of the feature. For instance, given a point geometry, we can construct a simple feature like this:

var point = new ol.geom.Point([x, y]);
var feature = new ol.Feature(point);

To create a feature with information associated with the point, we do it this way:

var feature = new ol.Feature({
  geometry: point,
  name: 'My Cottage'
});

By convention, the geometry key is used to specify the geometry associated with the feature. It's possible, though, to use a different key and the setGeometryName() method to change this. For our purposes, we'll be doing it the default way.

The Feature class properties

We refer to this extra, nonspatial information associated with a feature as properties. The properties associated with a feature are almost completely free-form and contain any value. The geometry property is really the only exception.

You might wonder why we care about the nonspatial properties of a feature since we can create a feature without them and things work just fine. There are essentially two reasons:

We want to provide users with information about the feature when they interact with them in some way. For instance, if we are displaying the country layer, we might want to show some information about the country – its name or population for instance.
We want to style features based on some property. For instance, if we are displaying earthquake locations, we might draw circles of varying radii and intensity of color based on the magnitude of the earthquake recorded at that location.

We'll look at the first case—interactive information—in the last example for this chapter. We'll explore the second case in the next chapter when we look more closely at styling vector layers.

Feature methods

Before we jump into our last example, let's look at the methods available on a feature object. Note that Feature class is a subclass of ol.Object and inherits all the Event class and KVO properties, methods, and events. We won't include them here, but if you need a refresher jump back to Chapter 2, Key Concepts in OpenLayers for a moment.

Method	Parameters	Description
`getGeometry()`	`None`	This returns the geometry associated with this feature. This uses the geometry name to decide which property contains the geometry.
`getGeometryName()`	`None`	This returns the name of the property, which contains the geometry for this feature. By default, this will be `geometry`, unless `setGeometryName` has been used to change it.
`getId()`	`None`	This returns the unique ID associated with this feature, if any has been set.
`getProperties()`	`None`	This returns an object literal containing all the properties of this feature.
`getStyle()`	`None`	This returns the style, if any, associated with this feature.
`getStyleFunction()`	`None`	This returns the function that will be used to style the feature.
`setGeometry(geom)`	`geom - ol.geom.Geometry`	This sets the geometry of this feature. This will set a property based on the current geometry name (see `setGeometryName`)
`setGeometryName(name)`	`name - string`	This sets the property name to be used for getting the geometry associated with this feature.
`setId(id)`	`id – number or string`	This sets the ID of this feature, a value that uniquely identifies it.
`setProperties(values)`	`values – object`	This sets properties for this feature.
`setStyle(style)`	`style – ol.style.Style \| Array.<ol.style.Style> \| function`	This is a style to be used for this feature.

While we are not including the ol.Object methods in this list, it is relevant and important to note that feature properties are treated as object properties. This means that you can:

Change or create a property using feature.set(key, value)
Get the value of a property using feature.get(key)
Observe changes to a property using feature.on('change:<key>', observerFunction), where <key> is the name of a property
Change several properties at once using feature.setProperties(values)

One last thing before our final example—feature objects can have their own styles. Normally, styles are assigned to the vector layer and all features that are rendered as part of that layer use the layer's style. It is possible, however, to assign styles to individual features and that style will be used instead of the layer's style. Because a feature comes from a source, and a source can be used for more than one vector layer, this means that a feature without a style can be rendered differently depending on the layer's style while a feature with a style will be rendered the same way regardless of the different styles on different layers.

Previous Chapter

Features and geometries

Next Chapter

Time for action – interacting with features

Table of Contents for OpenLayers 3 : Beginner's Guide