Time for action – overlaying information

In the previous example, we added an overlay but we didn't really investigate how it behaves. Let's do something a bit more interesting with overlays to illustrate what they do. In this example, we'll build an OpenLayers application that displays the latitude and longitude of the mouse position in an overlay when you click on the map:

Create a new file called overlay.html in the sandbox directory. Add the standard boilerplate content to get started:

<!doctype html>
<html>
  <head>
    <title>OpenLayers Overlays</title>
    <link rel="stylesheet" href="../assets/ol3/css/ol.css" type="text/css" />
    <link rel="stylesheet" href="../assets/css/samples.css" type="text/css" />
  </head>
  <body>
    <div id="map" class="map"></div>
    <script src="../assets/ol3/js/ol.js"></script>
  <script>
  </script>
  </body>
</html>

Now, add the following code to set up a simple map with the OpenStreetMap data.

var layer = new ol.layer.Tile({
  source: new ol.source.OSM()
});

var center = ol.proj.transform([-1.812, 52.443], 'EPSG:4326', 'EPSG:3857');
var view = new ol.View({
  center: center,
  zoom: 6
});

var map = new ol.Map({
  target: 'map',
  layers: [layer],
  view: view
});

We'll create an overlay object to display when the user clicks on the map. We will need an HTML element; so, add the following line of code right after Map's <div> element. You can change the style of the element if you wish:
```
<div id="overlay" style="background-color: white; border-radius: 10px; border: 1px solid black; padding: 5px 10px;">
```

The overlay object itself is pretty simple. Add this at the end, after creating the Map class:

var overlay = new ol.Overlay({
  element: document.getElementById('overlay'),
  positioning: 'bottom-center'
});

Now, we need to respond to the user clicking on the map by updating the content of our overlay and adding it to the map at the correct position. Put the following code snippet in the overlay:

map.on('click', function(event) {
  var coord = event.coordinate;
  var degrees = ol.proj.transform(coord, 'EPSG:3857', 'EPSG:4326')
  var hdms = ol.coordinate.toStringHDMS(degrees);
  var element = overlay.getElement();
  element.innerHTML = hdms;
  overlay.setPosition(coord);
  map.addOverlay(overlay);
});

The result should look something like this, depending on where you click! After clicking on the map, try panning or zooming the map and notice how the overlay stays in the same geographic location (it moves with the map).

What just happened?

In this example, we illustrated how an overlay is positioned at a geographic location on the map, how it moves with the map to stay at that same location, and how it can be used to display information about some location.

After setting up the boilerplate HTML structure for the page, we added a raster layer with the OpenStreetMap data, a view, and a map to the application. We then created an overlay object pointing at an HTML element for content and with the positioning set to 'bottom-center', which tells OpenLayers to align the bottom, center of the HTML element with the geographic position of the overlay. This means that the overlay will appear above the location, centered on it.

The last step was to register an event handler (more on events later in this chapter) for the map's click event. When the user clicks on the map, the event handler function is called with an event object that contains coordinate (the geographic position) of the click on the map. We transform the coordinate from the map's projection into decimal degrees (longitude and latitude values) and use a helper function in the OpenLayers library to format this into degrees minutes and seconds (a standard way of representing geographic location in human readable form). We then update the content of our overlay's HTML element with this information, set the position of the overlay to the coordinate provided with the event, and add it to the map using the addOverlay method.

If some of this seems overwhelming, don't worry, we'll be covering all of this in later chapters.

Interacting with the map

As mentioned earlier, the two components that allow users to interact with the map are interactions and controls. Let's look at them in a bit more detail.

Using interactions

Interactions are components that allow the user to interact with the map via some direct input, usually by using the mouse (or a finger with a touch screen). Interactions have no visible user interface. The default set of interactions are:

ol.interaction.DoubleClickZoom: If you double-click the left mouse button, the map will zoom in by a factor of 2
ol.interaction.DragPan: If you drag the map, it will pan as you move the mouse
ol.interaction.PinchRotate: On touch-enabled devices, placing two fingers on the device and rotating them in a circular motion will rotate the map
ol.interaction.PinchZoom: On touch-enabled devices, placing two fingers on the device and pinching them together or spreading them apart will zoom the map out and in respectively
ol.interaction.KeyboardPan: You can use the arrow keys to pan the map in the direction of the arrows
ol.interaction.KeyboardZoom: You can use the + and – keys to zoom in and out
ol.interaction.MouseWheelZoom: You can use the scroll wheel on a mouse to zoom the map in and out
ol.interaction.DragZoom: If you hold the Shift key while dragging on map, a rectangular region will be drawn and when you release the mouse button, you will zoom into that area.

We will discuss interactions in detail in Chapter 8, Interacting with Your Map.

Controls

Controls are components that allow the user to modify the map state via some visible user interface element, such as a button. In the examples we've seen so far, we've seen zoom buttons in the top-left corner of the map and an attribution control in the bottom-right corner of the map. In fact, the default controls are:

ol.control.Zoom: This displays the zoom buttons in the top-left corner.
ol.control.Rotate: This is a button to reset rotation to 0; by default, this is only displayed when the map's rotation is not 0.
The ol.control.Attribution: This displays attribution text for the layers currently visible in the map. By default, the attributions are collapsed to a single icon in the bottom-right corner and clicking the icon will show the attributions.

We will discuss these controls and more in detail in Chapter 9, Taking Control of Controls.

This concludes our brief overview of the central components of an OpenLayers application. We saw that the Map class is at the center of everything and there are some key components—the view, layers, overlays, interactions, and controls—that it uses to accomplish its job of putting an interactive map onto a web page. At the beginning of this chapter, we talked about both relationships and inheritance. So far, we've only covered the relationships. In the next section, we'll show the inheritance architecture of the key components and introduce three classes that have been working behind the scenes to make everything work.

Previous Chapter

Time for action – using the JavaScript console

Next Chapter

OpenLayers' super classes

Table of Contents for OpenLayers 3 : Beginner's Guide

Time for action – overlaying information

What just happened?

Interacting with the map

Using interactions

Controls

Table of Contents for
OpenLayers 3 : Beginner's Guide