Map methods

The Map class, being the central organizing point for OpenLayers, provides methods for managing many aspects of the map. As there are quite a few methods, we've grouped them into some logical groups—Control methods, Interaction methods, Layer methods, Overlay methods, Rendering methods, Conversion methods, and other methods.

Control methods

These methods are used to manage Controls associated with a map. Controls are covered in more detail in Chapter 9, Taking Control of Controls; so, we won't go into any detail here:

Method	Parameters	Description
`addControl( control )`	`control` - `ol.Control`	This method adds a control to the map.
`removeControl( control )`	`control` - `ol.Control`	This method removes a control from the map.
`getControls()`		This method returns an `ol.Collection` of controls associated with the map.

Interaction methods

These methods are used to manage interactions associated with a map. Interactions are covered in more detail in Chapter 8, Interacting with Your Map; so, we won't go into any detail here:

Method	Parameters	Description
`addInteraction( interaction )`	`interaction` - `ol.Control`	This method adds an interaction to the map.
`removeInteraction( interaction )`	`interaction` - `ol.Control`	This method removes an interaction from the map.
`getInteractions()`		This method returns an `ol.Collection` of interactions associated with the map.

Layer methods

The methods are used to manage layers in the map. Layers can also be managed through the layergroup property but these methods are a bit easier to use:

Method	Parameters	Description
`addLayer( layer )`	`layer` –`ol.Layer`	This method adds a layer to the map.
`removeLayer( layer )`	`layer` –`ol.Layer`	This method removes a layer from the map.
`getLayers()`		This method returns all the layers that have been added to the map as an `ol.Collection`.

Overlay methods

These methods are used to manage overlays associated with a map. Overlays are covered in more detail in Chapter 8, Interacting with Your Map; so, we won't go into any detail here:

Method	Parameters	Description
`addOverlay( overlay )`	`overlay` - `ol.Overlay`	This method adds an overlay to the map.
`removeOverlay( overlay )`	`overlay` - `ol.Overlay`	This method removes an overlay from the map.
`getOverlays()`		This method returns an `ol.Collection` of overlays associated with the map.

Map rendering methods

When we programmatically change the map's view (which we'll discuss at the end of this chapter), the state of the map changes and a redraw of the map is scheduled. This means that if we change the center of the view from London to New York, the map will re-center on New York and fetch tiles for that area and the screen will be updated almost instantly. This behavior can produce a jarring effect for the user. Fortunately, the Map class provides some ways to modify how the map will change state by using the beforeRender() method and how the map will appear using the render() and renderSync() methods.

Method	Parameters	Description
`beforeRender(fn)`	`fn` – `function`	This adds a `render` function and initiates frame rendering.
`render`	`None`	This programmatically triggers a redraw of the map. This will happen asynchronously, which means that it will not happen before this method returns but rather will be scheduled to occur at some later time.
`renderSync`	`None`	This causes the map to be redrawn synchronously, which means that by the time this method returns, the map will have been redrawn.

Animation functions

The primary use of the beforeRender() method is to add animation effects to our map's navigation. After we add a function using beforeRender(), the map will call the function and allow it to update the state of the map. This function can be used to smoothly animate any of the view's state including location, level of detail, and rotation.

While the creation of animation functions is beyond the scope of this book, their use is straightforward, and OpenLayers provides some useful ways for creating animation functions for most common scenarios. Let's indulge ourselves in a bit of fun by exploring how to create and use them.

All the following methods take a single options argument with three common parameters: start, duration, and easing.

start: This is a number, the time in milliseconds to start the animation at. If not provided, the default is to start immediately. You can use the JavaScript Date object to get the current time in milliseconds, such as var start = (new Date()).getTime();. To specify a start time in the future, just add a number of milliseconds to this number; for instance, to start an effect one second from now, use var start = (new Date()).getTime() + 1000;.
duration: This is a number, the duration of the animation in milliseconds, the default is 1000 (1 second).
easing: This function is an easing function. An easing function is a function that computes a smooth transition for an animation. The default is ol.easing.inAndOut, which provides a smooth acceleration into and out of an animated transition. These are the built-in easing functions:
- ol.easing.bounce: This adds a bounce effect to the end of a transition
- ol.easing.easeIn: This smoothly accelerates the start of the transition
- ol.easing.easeOut: This smoothly decelerates the end of the transition
- ol.easing.inAndOut: This smoothly accelerates the start and decelerates the end of the transition
- ol.easing.elastic: This is similar to the bounce effect
- ol.easing.upAndDown: This applies the transition, and then, reverses it

In addition to the three common options, each animation function has at least one additional property you can provide. Here are the functions with a note on the additional properties that can be passed. We'll try out these functions afterwards:

Function	Options	Description
`ol.animation.bounce( options )`	`resolution` – `number`	The `resolution` parameter is the resolution to bounce to. This function returns an animation function that provides a bounce effect when animating a transition. It is usually combined with other functions such as `pan`.
`ol.animation.pan( options )`	`source` – `ol.Coordinate`	The `source` parameter is the location to start panning from. This function returns an animation function that smoothly transitions from one location to another. It is usually used immediately before updating the view's location to animate the transition from the current location to a new location
`ol.animation.rotate( options )`	`rotation` – `number`	The `rotation` parameter is the rotation to apply in radians. This function returns an animation function that rotates the map by the rotation indicated.
`ol.animation.zoom( options )`	`resolution` – `number`	The `resolution` parameter is the resolution to zoom to. This function returns an animation function that smoothly zooms the map from one resolution to another. It is usually used immediately before changing the view's resolution.

As you might guess, some of the built-in controls such as the zoom controls use these animation functions to create nice effects.

Previous Chapter

Time for action – target practice

Next Chapter

Time for action – creating animated maps

Table of Contents for OpenLayers 3 : Beginner's Guide