This section explains the working of the tasks or instructions that you have just completed.

You will also find some other learning aids in the book, for example:

These are short multiple-choice questions intended to help you test your own understanding.

These are practical challenges that give you ideas to experiment with what you have learned.

You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.

We also provide you a PDF file that has color images of the screenshots/diagrams used in this book. The color images will help you better understand the changes in the output. You can download this file from: http://www.packtpub.com/sites/default/files/downloads/B02497_ColorImages.pdf

Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you find a mistake in one of our books—maybe a mistake in the text or the code—we would be grateful if you would report this to us. By doing so, you can save other readers from frustration and help us improve subsequent versions of this book. If you find any errata, please report them by visiting http://www.packtpub.com/submit-errata, selecting your book, clicking on the errata submission form link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata will be uploaded on our website, or added to any list of existing errata, under the Errata section of that title. Any existing errata can be viewed by selecting your title from http://www.packtpub.com/support.

Piracy of copyright material on the Internet is an ongoing problem across all media. At Packt, we take the protection of our copyright and licenses very seriously. If you come across any illegal copies of our works, in any form, on the Internet, please provide us with the location address or website name immediately so that we can pursue a remedy.

Please contact us at <copyright@packtpub.com> with a link to the suspected pirated material.

We appreciate your help in protecting our authors, and our ability to bring you valuable content.

You can contact us at <questions@packtpub.com> if you are having a problem with any aspect of the book, and we will do our best to address it.

When we say client-side, we are referring to the user's computer, specifically their web browser. The only thing you need to make OpenLayers work is the OpenLayers code itself and a web browser. You can either download it and use it on your computer locally, or download nothing and simply link to the JavaScript file served on the site that hosts the OpenLayers project (http://openlayers.org). OpenLayers works on nearly all modern web browsers and can be served by any web server or your own computer. Using a modern, standard based browser such as Firefox, Google Chrome, Safari, or Opera is recommended.

When we say library, we mean that OpenLayers is a map engine that provides an API (Application Program Interface) that can be used to develop your own web maps. Instead of building a mapping application from scratch, you can use OpenLayers for the mapping part, which is maintained and developed by a bunch of brilliant people.

For example, if you'd want to write a blog, you could either write your own blog engine, or use an existing one such as WordPress or Drupal and build on top of it. Similarly, if you'd want to create a web map, you could either write your own from scratch, or use software that has been developed and tested by a group of developers with a strong community behind it.

By choosing to use OpenLayers, you do have to learn how to use the library (or else you wouldn't be reading this book), but the benefits greatly outweigh the costs. You get to use a rich, highly tested, and maintained code base, and all you have to do is learn how to use it. Hopefully, this book will help you with it.

OpenLayers is written in JavaScript, but don't fret if you don't know it very well. All you really need is some knowledge of the basic syntax, and we'll try to keep things as clear as possible in the code examples.

OpenLayers lives on the client-side. One of the primary tasks the client performs is to get map images from a map server. Essentially, the client asks a map server for what you want to look at. Every time you navigate or zoom around on the map, the client has to make new requests to the server—because you're asking to look at something different.

OpenLayers handles this all for you, and it is happening via AJAX (asynchronous JavaScript + XML) calls to a map server. Refer to http://en.wikipedia.org/wiki/Ajax_(programming) for further information on AJAX. To reiterate—the basic concept is that OpenLayers sends requests to a map server for map data every time you interact with the map, then OpenLayers pieces together all the returned map data (which might be images or vector data) so it looks like one big, seamless map. In Chapter 2, Key Concepts in OpenLayers, we'll cover this concept in more depth.

A map server (or map service) provides the map itself. There are a myriad of different map server backends. The examples include:

If you are unfamiliar with these terms, don't sweat it. The basic principle behind all these services is that they allow you to specify the area of the map you want to look at (by sending a request), and then the map servers send back a response containing the map image. With OpenLayers, you can choose to use as many different backends in any sort of combination as you'd like.

With many web map servers, you do not have to do anything to use them—just supplying a URL to them in OpenLayers is enough. OSGeo, OpenStreetMap, Google, Here Maps, and Bing Maps, for instance, provide access to their map servers (although some commercial restrictions may apply with various services in some situations).

So, what's with the layers in OpenLayers? Well, OpenLayers allows you to have multiple different backend servers that your map can use. To access a web map server, you declare a layer and add it to your map with OpenLayers.

For instance, if you wanted to have a Bing Maps and an OpenStreetMap service displayed on your map, you would use OpenLayers to create a layer referencing Bing Maps and another one for OpenStreetMap, and then add them to your OpenLayers map. We'll soon see an example with an OpenStreetMap layer, so don't worry if you're a little confused.

The website for OpenLayers 3 is located at http://openlayers.org. Have a look at the following screenshot:

To begin, you need to download a copy of OpenLayers (or we can directly link to the library—but we'll download a local copy). You can download the compressed library as a .zip by clicking on the green button at the bottom of the release page at https://github.com/openlayers/ol3/releases/tag/v3.0.0.

We will cover the website links by following the different areas of the main web page. Let's start with the navigation bar located at the top right area:

We just installed OpenLayers 3 by copying over different pre-built, compressed JavaScript files containing the entire OpenLayers 3 library code (from the build directory) and the associated assets (style sheets). To use OpenLayers, you'll need at a minimum, the ol.js file (the other .js files will be needed during the book but are not always required) and the ol.css file. For best practice, we already gave you some tips to structure the code like separate assets, such as css and js, or separate library code from your own code.

If you open the ol.js file, you'll notice it is nearly unreadable. This is because this is a minified and obfuscated version, which basically means extra white space and unnecessary characters have been stripped out to cut down on the file size and some variables have been shortened whenever possible. While it is no longer readable, it is a bit smaller and thus requires less time to download. If you want to look at the uncompressed source code, you can view it by looking in the ol-debug.js file within the js folder of the ol3 directory.

You can, as we'll see in the last chapter of this book, build your own custom configurations of the library, including only the things you need. But for now, we'll just use the entire library. Now that we have our OpenLayers library files ready to use, let's make use of them!

The process for creating a map with OpenLayers requires, at a minimum, the following things:

Now, we're finally ready to create our first map!

We just created our first map using OpenLayers! If it did not work for you for some reason, try double-checking the code and making sure all the commas and parentheses are in place. You can also open the browser debugger and look for JavaScript errors within the console. If you don't know what a console is, don't worry, we will see it soon. You can also refer to the Preface where a link to code samples used in the book is given. By default, we're given a few controls if we don't specify any. We will use the file we created as a template for many examples throughout the book, so save a copy of it so you can easily refer to it later.

The control on the left side (the navigation buttons) is called the Zoom control, which is a ol.control.Zoom object. You can click the buttons to navigate around the map, drag the map with your mouse, use the scroll wheel to zoom in, or use your keyboard's arrow keys. ol.control.Attribution is added by default. It will be populated if a layer (such as OSM) has attribution info available. This control is on the bottom right corner and gives the credits for the data you're using such as license and data producer.

We'll cover controls in greater detail in Chapter 9, Taking Control of Controls.

Now, let's take a look at the code, line by line.

The API documentation is always up-to-date and contains an exhaustive description of all the classes in OpenLayers. It is usually the best and first place to go when you have a question. You can access the documentation at: http://openlayers.org/en/v3.0.0/apidoc/ for the 3.0.0 release. It contains a wealth of information. We will constantly refer to it throughout the book, so keep the link handy! Sometimes, however, the API docs may not seem clear enough, but there are plenty of other resources out there to help you. We'll cover a bit about how to find your way in API documentation in Chapter 2, Key Concepts in OpenLayers and in Appendix A, Object-oriented Programming – Introduction and Concepts.

The extension website for this book can be found at: http://openlayersbook.github.io/openlayersbook/. Current, up-to-date corrections and code fixes, along with more advanced tutorials and explanations, can be found there. You can also grab the code and more information about this book at Packt Publishing's website, located at https://www.packtpub.com/web-development/openlayers-3-beginner%E2%80%99s-guide.

The OpenLayers mailing list is an invaluable resource that lets you not only post questions, but also browse questions others have asked (and answered). There were two main OpenLayers news groups—Users and Dev for the OpenLayers 2 Version. There is a list only for OpenLayers 3 development discussions located at https://groups.google.com/forum/#!forum/ol3-dev. You may find some users' questions in the archives as it was before for both development and users questions.

Now, user questions should be only posted on http://stackoverflow.com and tagged with openlayers. OpenLayers 3 library developers will answer directly here.

When posting a question, please be as thorough as possible, stating your problem, what you have done, and the relevant source code (for example, "I have a problem with using a WMS layer. I have tried this and that, and here is what my source code looks like..."). A good guideline for asking questions in a way that will best elicit a response can be found at http://www.catb.org/~esr/faqs/smart-questions.html.

Books are great, but they're basically just a one way form of communication. If you have any questions that the book does not answer, your favorite search engine is the best place to go to. The Questions and Answers website http://gis.stackexchange.com, the young brother of StackOverflow, dedicated to GIS (Geographical Information System) can also be quite useful. But, at the end, don't forget that mailing lists and IRC are other great resources.

IRC (Internet Relay Chat) is another great place to go to if you have questions about OpenLayers. IRC is used for group communication; a big chat room, essentially. If you have exhausted Google, issues' trackers, and the mailing list, IRC provides you in real time with other people interested in OpenLayers.

Generally, the people who hang out in the OpenLayers chat room are very friendly, but please try to find an answer before asking in IRC. The server is irc.freenode.net and the chat room is #openlayers. You can download an IRC client online; a good Windows one is mIRC (http://mirc.com). More information about how to use IRC can be found at http://www.mirc.com/install.html. For beginners, we recommend using Chatzilla, a Firefox Mozilla add—on http://chatzilla.hacksrus.com or CIRC, a Google Chrome add—on http://flackr.github.io/circ/.

When you've installed it, just type irc://irc.freenode.net/openlayers (for Chatzilla only) in your browser address bar, press enter, wait and you're ready to speak on OpenLayers IRC channel.

In the first step, we added our boilerplate HTML code for a simple OpenLayers application. This includes standard HTML tags suitable for any web page, and also includes the OpenLayers CSS and JavaScript files.

Next, we started creating instances of various OpenLayers components to use with our map. The first one was a layer that renders tiles from the OpenStreetMap tile servers. Next, we created an interaction called DragRotateAndZoom. This interaction has no visible element, but rather is triggered by holding down the Shift key while dragging the map. As the name suggests, this interaction will rotate and zoom the map in response to dragging the mouse cursor. Then we created a control called FullScreen. Again, the name gives away what it does—launches the web page into fullscreen mode. Because it is a control, it has a button that is clicked to activate its behavior. Next, we created an overlay, which displays an HTML element at a specific geographic location. Finally, we created the view, giving it the same center as the position we provided to the overlay.

The last step is to tie it all together with the Map class object by passing all our components as part of the constructor. We'll look at the Map class's constructor in more detail in Chapter 3, Charting the Map Class but for now, it's enough to know that we can provide arrays of layers, interactions, controls, and overlays as options, and the Map class will know what to do with them.

We saw that by providing our own set of interactions and controls; we changed the default behavior of an OpenLayers application. This is because the Map class has a default set of interactions and controls that it creates when they are not explicitly provided as options to the constructor. There are two ways we can restore the default behavior and add our new components as well.

The first way is to use helper functions provided by OpenLayers to obtain the collection of default interactions and default controls and extend those with our new components. We will do something like this (this example is not complete as the Map class is missing a view):

// create our interaction
var interaction = new ol.interaction.DragRotateAndZoom();
// get the default interactions and add our new one
var interactions = ol.interaction.defaults().extend([interaction]);

// create our control
var control = new ol.control.FullScreen();
// get the default controls and add our new one
var controls = ol.control.defaults().extend([control]);

// create the map and pass in the extended set of interactions and controls
var map = new ol.Map({
  interactions: interactions,
  controls: controls
});

The second method is to add them to the map after calling the constructor, for instance, (again, this example is not complete):

var interaction = new ol.interaction.DragRotateAndZoom();
var control = new ol.control.FullScreen();
var map = new ol.Map();
map.addInteraction(interaction);
map.addControl(control);

The advantage of the first method (passing constructor options) is that it gives you complete control over which interactions and controls are in use, while the second method (adding them after creating the map) has the advantage of being simpler if you want to add to the existing set of interactions and controls.

In many parts of OpenLayers, you will discover that there are multiple ways of accomplishing a given task. This is part of the design of the OpenLayers library and provides developers with the option to write code in a way that makes most sense for them.

We used the Developer tools console to execute some JavaScript and modify our running application to add the default zoom controls that were missing. Along the way, we ran into a problem and switched to the debug build of the OpenLayers library so that we could get more useful information about problems we ran into. We touched briefly on using the powerful Developer tools, including the Console and Sources panels.

There are a great many things we can do with the Developer tools, and this just touches briefly on one aspect of them. Please read Appendix C, Squashing Bugs with Web Debuggers to learn more about using the Developer tools in application development.

In the following sections, we'll look a little more closely at each of the components we've introduced so far, starting with the view class.

Based on the previous example, use the Console to add the default interactions to the running application. You can get the default interactions by calling the ol.interaction.defaults() method.

The OpenLayers view class, ol.View, represents a simple two-dimensional view of the world. It is responsible for determining where, and to some degree how, the user is looking at the world. We'll cover views in more detail at the end of Chapter 3, Charting the Map Class, but briefly, it is responsible for managing the following information:

Although you can create a map without a view, it won't display anything until a view is assigned to it. Every map must have a view in order to display any map data at all. However, a view may be shared between multiple instances of the Map class. This effectively synchronizes the center, resolution, and rotation of each of the maps. In this way, you can create two or more maps in different HTML containers on a web page, even showing different information, and have them look at the same world position. Changing the position of any of the maps (for instance, by dragging one) automatically updates the other maps at the same time! We'll see an example of this in the next chapter.

So, if the view is responsible for managing where the user is looking in the world, which component is responsible for determining what the user sees there? That's the job of layers and overlays.

A layer provides access to a source of geospatial data. There are two basic kinds of layers, that is, raster and vector layers:

Layers are not the only way to display spatial information on the map. The other way is to use an overlay. As we saw in the example earlier in this chapter, we can create instances of ol.Overlay and add them to the map at specific locations. The overlay then positions its content (an HTML element) on the map at the specified location. The HTML element can then be used like any other HTML element.

The most common use of overlays is to display spatially relevant information in a pop-up dialog in response to the mouse moving over, or clicking on a geographic feature.

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.

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.

An event is basically what it sounds like—something happening. Events are a fundamental part of how various components of OpenLayers—the map, layers, controls, and pretty much everything else—communicate with each other. It is often important to know when something has happened and to react to it. One type of event that is very useful is a user-generated event, such as a mouse click or touches on a mobile device's screen. We used this earlier in the chapter to display an overlay at the location of a mouse click. Knowing when the user has clicked and dragged on the Map class allows some code to react to this and move the map to simulate panning it. Other types of events are internal, such as the map being moved or data finishing loading. To continue the previous example, once the map has moved to simulate panning, another event is issued by OpenLayers to say that the map has finished moving so that other parts of OpenLayers can react by updating the user interface with the center coordinates or by loading more data.

Classes inheriting from ol.Observable (including ol.Object) get the following event related methods:

It is very important to pass the exact same listener and scope values to un() as were passed to on(). A common practice is to pass anonymous functions as arguments to functions such as on(), which takes function arguments. Because un() needs the exact same listener argument to work correctly, we can't use anonymous functions if we want to call un() later. However, we can store the key returned by on() and use it with unByKey(). Let's look at some code examples:

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

This creates a Map class object, nothing new here.

map.on( 'moveend', function() { 
 console.log('move end event!'); 
});

Next, we will register for the moveend event. The moveend event is triggered by the map after it has been panned or zoomed. The function we provide will be called every time the map moves. Our code will output some text to the debug console. Because we used an inline or anonymous function, we have no way to remove our function if we no longer want to receive events. Or do we?

var key = map.on('moveend', function() { 
 console.log('move end event!'); 
});
map.unByKey(key);

This code registers for the same moveend event using an anonymous function but this time we will assign the return value to key. We can then use the value assigned to key to unregister our handler.

Let's look at another way:

function onMoveEnd(event) {
 console.log('moveend event 2');
}
map.on('moveend', onMoveEnd);
map.un('moveend', onMoveEnd);

This block declares a function called onMoveEnd() and registers it for the moveend event. The last line unregisters it. This achieves exactly the same result as the previous code; so, what's the difference? It is mostly to accommodate different coding styles and patterns. Some people prefer to write their code a certain way, or perhaps they have to follow a particular coding style guide (see Appendix B, More details on Closure Tools and Code Optimization Techniques for more information on this), and OpenLayers provides various ways to make it easier.

What about the scope parameter? This is useful for code that is written in an Object oriented style. Here is a contrived example that illustrates how it will be used:

var MyClass = function(label) {
 this.label = label;
 this.onMoveEnd = function() {
   console.log( this.label + ': moveend event');
 }
}
var obj1 = new MyClass('Object 1');
var obj2 = new MyClass('Object 2');

A simple class called MyClass is defined, which contains a single attribute, label, and a single method, onMoveEnd(). Next, two instances of this class are created with different label values. We can use the onMoveEnd() method of our instances as a function in the second parameter of the on() method. When the onMoveEnd() method is called, it will log a message to the debug console containing the value of the label attribute. Here are some examples of how this can be used:

map.on('moveend', obj1.onMoveEnd);

Registering the onMoveEnd() method for the moveend event will work, but the output will be as follows:

Undefined: zoomend event

What's wrong? It turns out that this.label is not defined because the value of this is the global window object. We can correct this by passing a scope object as the third parameter to the on() function:

map.on('moveend', obj1.onMoveEnd, obj1);
map.on('moveend', obj2.onMoveEnd, obj2);

Now, the output will be what we expected:

Object 1: moveend event
Object 2: moveend event

We then need to use the scope to unregister for the events as follows:

map.un('moveend', obj1.onMoveEnd, obj1);
map.un('moveend', obj2.onMoveEnd, obj2);

You successfully used the bindTo() method to establish the layer as an observer of the checkbox using the ol.dom.Input helper class. We bound the visible property of our layer to the checked property of the ol.dom.Input. When the checkbox is clicked, ol.dom.Input updates the checked property and notifies observers of the checked property that it has changed. Because we bound the visible property of the layer to the checked property of the input, the layer is notified of the change and updates the visible property, which causes the layer to turn on and off.

Property binding works both ways. You can manually change the visibility of the layer using the Console in Web Inspector. Try the following and observe what happens to the checkbox:

layer.setVisible(false);
layer.setVisible(true);

You should see the checkbox change state as if you had clicked it.

Sometimes, the property value that you are sharing between two objects is not exactly what you need. For instance, you might want to synchronize two maps so that they are looking at the same center point, but at different resolutions. If we share a view between the maps, we can't have one of them at a different resolution. We could use two views and use events to manually synchronize them—and this is a perfectly valid approach—but wouldn't it be nice if we could use bindTo and just modify the resolution value a little bit? This is exactly what the object returned from bindTo allows us to do. The return value from bindTo is an object with a single function, transform, that you can invoke with two functions as arguments. The first function is used to transform the value going from the source to the target and the second is used to transform the value going to the source from the target. For instance:

var transformer = view1.bindTo(resolution', view2);
var from = function(value) {
  return value * 2;
};
var to = function(value) {
  return value / 2;
};
transformer.transform(from, to);

This example binds the resolution property of view2 (the target) to the resolution property of view1 (the source). We can capture the return value in the variable transformer, create two functions that will transform the resolution value, and call the transformer variable's transform function with our two functions. The result is that view2 parameter's resolution property will be bound to view1 parameter's property but will always have a value twice that of view1.

Most classes in the OpenLayers library have one or more KVO properties (these are specified in the library documentation) and have some special features. As we saw, the name of the property can be used as the key parameter in any of the KVO methods described earlier. Additionally, three events are triggered when the value of a property changes.

The first event is beforepropertychange and is triggered before a property will change. It provides the name of the property that will change to the listener:

layer.on('beforepropertychange', function(event) {
 console.log('layer changed in some way');
 // event.type == 'beforepropertychange'
 // event.key == '<the key that is changing>'
});

The second event is propertychange is triggered as (effectively after) the property is changed:

layer.on('propertychange', function(event) {
 console.log('layer changed in some way');
 // event.type == 'propertychange'
 // event.key == '<the key that has changed>'
});

A third event is a change event specific to the property that changed. The name of the event is derived from the property name with the prefix change:. This means that we can be notified of changes to individual properties. In our previous example of binding a layer's visibility to a checkbox, we can register to be notified of the change like this:

layer.on('change:visible', function(event) {
 console.log('layer visibility changed');
 // event.type == 'change:visible'
 // event.target == layer
});

It may seem like there are a lot of events that happen in response to a KVO property changing and you are right, there are! Each event, though, is slightly different and provides both convenient and optimal ways of responding to changes that happen to objects in OpenLayers.

In addition to events, KVO properties also have special accessor functions called setters and getters defined for them. This means that instead of using the KVO methods get(key) and set(key, value), you can use get<Property>() and set<Property>(value), where <Property> is the capitalized property name. For instance:

layer.get('visible');
layer.getVisible();
layer.set('visible', true);
layer.setVisible(true);

These methods are primarily for convenience and you can use either depending on your own preferences.

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
});

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.

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.

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):

Let's look a little closer at how we create our map object in this block of code:

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

We use the new operator to create an instance of the ol.Map class and pass it an object literal containing several options, namely, target, view, and layers. We've used these before in the previous examples without really explaining them or any of the other options we might want to use. Here's the full list of available options and what they do:

The Canvas renderer draws the map's contents onto an HTML 5 canvas element (http://en.wikipedia.org/wiki/Canvas_element). The canvas element is a high-performance 2D drawing surface supported by all modern web browsers (on Internet Explorer, Canvas support starts with version 9). The canvas renderer is the most fully supported renderer in OpenLayers. It does not support some of the advanced features of the WebGL renderer, including 3D, controlling the contrast, brightness, hue and saturation of a layer, and other advanced capabilities requiring the power of WebGL.

You will most likely want to use this renderer until WebGL is more broadly supported, unless you are building an application that can target browsers that specifically support WebGL.

It even provides the ability to render data in 3D and give full 3D navigation. Given how fantastic all this sounds, why wouldn't you use it all the time? Unfortunately, WebGL support in a browser is dependent on two things. First, the user's computer must have a graphics card and software drivers that are capable of supporting it. Second, the web browser itself must support it. Since WebGL is a relatively new specification, only the newest versions of Google Chrome, Safari, and Firefox will enable WebGL on systems with capable hardware. Internet Explorer up to version 10 does not provide WebGL support at all, although there are third-party plugins that can be added by users to provide it. Finally, mobile browser support is very limited and varies widely at this time.

In summary, the WebGL renderer can give your application amazing performance and some cutting edge capabilities if your intended users can be relied on to have the latest web browser versions and capable hardware. It isn't suitable if you need to support older web browsers, Internet Explorer, or mobile users.

The DOM renderer draws the map's contents using HTML elements (<img> and <div> tags) and uses CSS to position them. This renderer is supported by older versions of most browsers, including Internet Explorer 8. However, it does not provide many of the capabilities enjoyed by the Canvas renderer. Of the features that it does not support, the most important is vector support covered in Chapter 6, Styling Vector Layers. The DOM renderer will also generally exhibit poorer performance.

There is some effort being undertaken by community members to provide some vector capabilities for the DOM renderer, including support for Internet Explorer 8, but in general, you will probably not want to use the DOM renderer unless you need to support older browsers that do not provide Canvas support.

Now, we see a lot of <img> elements. By choosing the DOM renderer, we have asked OpenLayers to use a different way of presenting the map in the browser. OpenLayers now creates a new <img> element for each map tile coming from the remote server and positions it next to the others to create the complete map.

When you click the button, the changeTarget() function is called. This function uses getTarget() to find out which element the map is rendered in and setTarget() to move it to the other map element.

Moving the map between two HTML elements is really a contrived example to illustrate how the methods work. A more likely use of these methods might be to show and hide the map entirely. Try changing the above example to show and hide the map, rather than moving it. Also, try using get() and set() instead of getTarget() and setTarget() 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:

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:

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:

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:

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.

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.

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:

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

Not too bad! In a few lines of code, we managed to create some pretty impressive animation effects using ol.animation functions and the Map's beforeRender() method.

In step 3, we created the doBounce() function. This function takes a single parameter, location, which is the location that we want to bounce to. The effect we want to achieve is to smoothly zoom out from our current location and then into the new location. We called ol.animation.bounce() to create a function that implements the bounce animation effect. For this example, we provided only the resolution property and let the other properties (start, duration, and easing) take their default values. We set the resolution property to two times the current resolution of the map's view. This is equivalent to clicking the ZoomOut control (the button in the top-left corner of the map with the minus sign) once. What this does is smoothly zoom out from the current resolution to the next zoom level, and then back into the current resolution.

Next, we created a function that implements the pan animation effect. Again, we used the defaults for start, duration, and easing by not specifying them and set the source property to the current center of the map's view. We added both bounce and pan functions to the map by calling beforeRender(); then, we changed the map's view to go to the location we passed into this function.

In step 4, the doPan() function takes a single parameter, location, and smoothly pans the map to it. To do this, we called ol.animation.pan() with the map's current center for the source as we did in the doBounce() function, then we told the map's view to go to the new location.

In step 5, the doRotate() function doesn't take any parameters; we just wanted to spin the map 360 degrees. We used the ol.animation.rotate() function for this and set the rotation option to specify how much to rotate. When we add this to the map using beforeRender(), the effect happens immediately.

Step 6 adds the doZoom() function. It takes a single parameter, factor, which is the amount to zoom. We used ol.animation.zoom() to create our animation function using the view's current resolution as our starting point. Then, we added our animation function and told the map's view to zoom to a new resolution by multiplying the current resolution by the factor parameter. A factor of two will cause the map to zoom out to the next zoom level and a factor of 0.5 will cause the map to zoom in to the next zoom level.

Now that we've seen how the basic animations work, try modifying the animation properties in each function to see how to change its parameters and overriding the default duration, start time and easing functions. You can also try combining the animations in different ways.

When we click on a web page, the browser generates a MouseEvent that contains, among other things, the position that the click happened at. This position is in pixels and is relative to the browser window. In an OpenLayers application, we will often want to respond to the user interacting with the map and it is important to understand these events specify the position in pixels. It is common to need to determine the geographic coordinate that corresponds to this position. OpenLayers provides several methods that allow us to convert between the browser's pixel space and geographic coordinates:

The map object contains a few other methods that don't neatly fit into the previous groups; so, we've included them here for completeness:

The Browser events are all events that are provided in response to the user interacting with the map's HTML element. The available events are:

Listeners attached to the Browser events will receive an object of the ol.MapBrowserEvent type that contains the following properties:

There are two events that are triggered when the map state changes.

Listeners attached to the map events will receive an object of the ol.MapEvent type, which contains the following properties:

There are two events that are triggered when the map is being rendered. These can be used to programmatically alter the appearance of the rendered map image in interesting ways:

Listeners attached to the render events will receive an object of the ol.render.Event type that contains the following properties:

OpenLayers currently provides a single View class, ol.View. This class represents a simple 2D view, which can be manipulated through three key properties: center, resolution, and rotation. We will create a new instance of ol.View in the same way that we create a map object, like the following:

var view = new ol.View(ViewOptions);

We've used views in all our examples because a view is a mandatory parameter when creating a new map instance, but we haven't discussed it in detail yet. Let's dive in.

The options you can use when creating a new ol.View instance are as follows:

As with the Map class, the View class has a number of KVO properties that have accessor methods (get and set), property binding, and events as discussed earlier:

With a single line of code, we bound the view property of the two maps and were able to produce a pretty interesting effect. By itself, this doesn't do much that could be considered useful but it is the basis for building some interesting functionalities such as creating an overview map or a highlight map that shows the same area as a main map but at a different level of detail.

One thing you probably noticed with the previous example is that changes from one map aren't animated in the other one. This behavior is to be expected. If you recall, we mentioned in the animation section that programmatic changes are applied instantly. Since we aren't adding animation effects with beforeRender(), the changes applied from one view to the other happen instantly and the result is sometimes quite jarring.

Use the knowledge you've gained in this chapter to adapt the previous example into something more useful. Try to make the second map respond to changes in the first map, but zoomed out three times. Remember that zooming out once is equivalent to doubling the zoom level. When the page loads, it should look like this:

When the first map is panned or zoomed, the second map should center on the same location and stay zoomed out in three levels. The second map should not have any controls or interactions—set both the controls and interactions option to new ol.Collection() to achieve this.

Let's do a series of questions to see what you understood during the chapter:

Q1. I want to start my map looking at a specific location and level of detail. Which object is responsible for this?

Q2. I want to take some action when the user pans the map. What event should I listen for?

Q3. Which object files this event?

Q4. I want to update a property called center of the view object when the center property on another object obj, changes. Which class provides the bindTo() method that I'll use?

A base layer is at the very bottom of the layer list, and all other layers are on top of it. This would be our printed map from the earlier example. The order of the other layers can change, but the base layer is always below the overlay layers. By default, the first layer that you add to your map acts as the base layer. You can, however, change the order of any layer on your map to act as the base layer.

You can also have multiple base layers. Although you can set more than one base layer active at a time, for visual readability, most of the time, you only use one.

Any layer that is not a base layer is called an overlay layer. Like we talked about earlier, the order that you add layers to your map is important. Every time you add a layer to the map, it is placed above the previous one.

After this reminder about layers concepts, see what's happening at the OpenLayers 3 library level inheritance to discover the main layers type.

There are two types of layers: raster and vector layers. The main differences between both are:

To give you an overview of layers organization at the library level, let's look at the following diagram:

When you are creating a new web mapping application, you have to make a choice between benefits and drawbacks of those layers. For raster, it's mainly that images do not overload the browser as vector layers mostly can. As you can see in the diagram, raster layers such as vector layers are derived from a common ol.layer.Layer class. This ol.layer.Layer class inherits from an ol.layer.Base class, (base in this case means common behavior between layers). This class is also inherited by an ol.layer.Group class designed to group layers to treat them as a single layer. In our case, we will focus mainly on the two raster layer classes, ol.layer.Image and ol.layer.Tile. We will also do a review of the common ol.layer.Layer methods. Moreover, you can divide raster in two categories: tiled or untiled. We will cover both types in this chapter. The ol.layer.Vector class will be covered in Chapter 5, Using Vector Layers.

We reviewed how to manage main methods attached to the ol.layer.Layer subclass (remember that ol.layer.Tile inherits from it).

The interesting thing here, is that you are able to manipulate and create generic properties for all the ol.layer.Layer subclasses.

The most common operations on layers have their custom getters/setters such as getVisible() / setVisible(property), but you can replace them with the ol.layer.Layer getters/setters, get('visible')/set('visible', property). These are inherited from ol.Object, and consequently, ol.layer.Tile inherits them too. In the normal case, you use these getters/setters only for arbitrary properties we want to add, such as a name.

Another benefit you may not be aware of is that when you add new properties to a layer object, you can attach information for new applications related to layers. For example, you can set a property to reference metadata for the layer (intellectual properties, license, link to a PDF file to download, or more). Some other ways to use it are to define groups, set a unique identifier, set a display name to reuse in a custom layer manager, and set a reference to a legend resource (URL, image, and so on).

The possibilities are endless.

Now, after this short introduction to manage layer properties, we will review different raster layers and also the source property. It's mainly these elements that make the difference between raster layers in the OpenLayers 3 library.

So, how can we define a source? What is its purpose?

Sources in OpenLayers 3 language define how and where you can access the layer. You always need a source from an ol.source subclass in order to retrieve and display layers.

Why did OpenLayers 3 development team invent this concept?

It was mainly for the organization of the code and reusability of the same principles. You gain modularity because you have only three types of layers but more sources. It enables you to decouple the type of layer you are using from the data source and the way you call it. It's simpler to manage a new source than to create a new layer by example if a new source appears.

You can see in the following diagram that ol.source.Source has three main child subclasses, ol.source.Vector, ol.source.TileSource, and ol.source.ImageSource.

They are abstract classes. It means, they work as a skeleton for all types of sources but are never directly used:

Most of the layers we are manipulating are inherited from the past.

Web-based maps are commonplace today. The catalyst for the explosive growth of web maps was the introduction of Google Maps. Web maps existed before, but they were not quick or developer friendly. In June 2005, Google released an API for Google Maps, which provided a frontend client (the role OpenLayers plays), along with an access to the backend map server via their frontend client API.

This allowed anyone to insert not just a Google Map on their site, but also allowed them to add in their own point data and manipulate the map in other ways. Google Maps grew in popularity, and other companies such as Microsoft, Yahoo, MapQuest, MapBox, Nokia, and others followed in their footsteps, creating their own web mapping APIs.

Most of them are more likely to make mashups.

The term mashup refers to an application that combines various different data sources and functionality together. A map mashup is a map that combines different layers and data. Third-party mapping APIs, such as MapQuest and Microsoft Bing Maps, allow people to more easily create these map mashups. For example, a map with an OpenStreetMap base layer overlaid with markers that track places you've traveled to can be considered a map mashup.

OpenLayers did not introduce map mashups, but it allows us to create very powerful ones with ease. Combining an OpenStreetMap layer, a WMS layer, and a vector layer is pretty simple with OpenLayers.

OpenLayers 2 had some third-party mapping APIs embedded into its core, enabling you to use its maps inside your Openlayers-based application. Nowadays, for better decoupling of OpenLayers API from third-party APIs, the OpenLayers 3 team choose to have no support for other mapping APIs that tie together tiles and an associated JavaScript API library.

Why this decision?

One of the main goals of OpenLayers 3 was to rewrite OpenLayers 2, making its API cleaner. The support for Google Maps API in OpenLayers 2 has also put a significant maintenance burden on both library and application developers, to keep up with changes of the Google Maps API. To avoid this in OpenLayers 3, the support for Google Maps using Google Maps API is nonexistent. However, Google does provide its tiles independent from their API, but only to paying customers. Fortunately, you have more alternatives to Google Maps API. We will try to show you that Bing (Microsoft) Maps (with its tiles service) or OpenStreetMap and its derived map images' data services API such as MapQuest can fill the missing provider.

Now, it's time to review all the tiled layers, in particular, to use beautiful background layers for your maps.

OpenStreetMap (OSM) is a free, Wikipedia style map of the world driven by user contributed content. You are able to use your own OSM tiles or ones provided through the OpenStreetMap servers.

Setting up an OpenStreetMap service and tiles yourself is not too difficult, but it is outside the scope of this book (visit http://switch2osm.org for more information on this). Accessing OSM with OpenLayers, however, isn't.

More information on the OpenStreetMap project can be found at http://www.openstreetmap.org. To access OpenStreetMap, only using the ol.source.OSM constructor without any options is enough. In the previous examples, we were already using this source, so we will not give you another similar example.

var osmLayer = new ol.layer.Tile({
  source: new ol.source.OSM({
    url: 'http://{a-c}.tile.opencyclemap.org/cycle/{z}/{x}/{y}.png'
  })
});

Understanding OSM tiling

If you have different sources for tiling, it is not only to provide different URLs to access different map images. The way tiling is done depends on established standards.

For example, Stamen layers, OpenStreetMap layers, and MapQuest layers are using the same tiling convention, whereas WMTS (Web Map Tile Service) can adopt other patterns to display tiles. These patterns are set with the ol.tilegrid.TileGrid object that describe for each arbitrary zoomlevel how the tiles are split.

The rules are the following. In reality, the Earth is not a sphere, but in this case, our planet is assimilated to a sphere because we are using Spherical Mercator projection (mainly known as EPSG 900913 or EPSG 3857). Do not worry about projections at the moment, we will review them in a later chapter as it can be a difficult topic to understand.

The entire sphere is projected on a single square at the 0 level. Then, for each zoom, you increase a level and for each tile at the previous zoom, we get 4 tiles at this one.

With the preceding diagram, you will know how to access a tile covering East Europe such as Poland at the 3 level. The URL always looks like URL_TO_TILES/level_z/x_in_grid_for_level/y_for_grid_in_level.png. So, for Poland that has a zoom level 3, x equal to 4, an y to 2, the URL could be http://b.tile.openstreetmap.org/3/4/2.png or http://c.tile.openstreetmap.org/3/4/2.png to get the right tile.

MapQuest was, until around 2008, the leading provider for web mapping API. With the entry of Google Maps, the leadership was lost. In 2010, the company chose to change its position concerning web mapping API, by choosing to exclusively rely on OpenStreetMap data to do the job.

Two layers are available freely. They also provide other services such as their own web mapping API. You can get further information at the Open developer part website at http://developer.mapquest.com/web/products/open/.

The assignment is quite easy:

You will get something like the following screenshot if you center on the Statue of Liberty and use the MapQuest OSM layer:

The Stamen layers were named so after a company. To cite the OpenstreetMap wiki, Stamen (http://stamen.com) is a San Francisco design and development studio focused on data visualization and map-making. These layers extensively use OpenStreetMap data in many of their map visualizations and have provided three CC-BY OpenStreetMap tilesets: Toner, Terrain, and Watercolor. You can see how the styles look at the official demo website, http://maps.stamen.com.

The map we've just created shows a black and white Stamen layer. You can look at other available layers for Stamen, the list is available just after the Stamen Layers' properties below.

new ol.source.Stamen({
  layer: 'toner'
})

Microsoft provides an interface to their mapping services as well. Their mapping service previously was referred to as Virtual Earth, but they have since rebranded it as Bing Maps. The official Microsoft documentation can be found at http://msdn.microsoft.com/en-us/library/dd877180.aspx.

We just made a map using the Microsoft Bing Map tiles' API. It works similar to the OpenStreetMap tiles layers but required to be authenticated. We can communicate with Microsoft tiles API server and use different properties. Let's go over the properties, as there are some that the other third-party sources do not provide.

The TileJSON format was invented by MapBox, another company providing OpenStreetMap related services. It relies on JSON notation.

According to the specification, TileJSON is an open standard for representing map metadata. Its main goal is to reference the name, the attribution, the server URL, the minimum and max zoom, the center, the bounds, and the scheme of the tile (for OSM, numbering go top to bottom but other tiles' systems start numbering upwards). You can see all available parameters looking at the official specification at https://github.com/mapbox/tilejson-spec.

As it is not the mainstream way to get tiles, although it's a smart way, we will not review it through an example but directly advise you to go the official demo available at http://openlayers.org/en/v3.0.0/examples/tilejson.html and look into the code.

ol.source.TileJSON

The WMTS layer is based on the WMTS standards. The specification defines it as The Web Map Tile Service described in this standard builds on earlier efforts to develop scalable, high-performance services for web-based distribution of cartographic maps.

A WMTS-enabled server application can serve map tiles of spatially referenced data using tile images with predefined content, extent, and resolution.

This type of layer is quite different from most of the previous tiled layers we've seen. WMTS layers are more customizable. You can make a request to get tiles in custom projection, you can also choose your grid without caring about the implicit rules, that each tile when you zoom it will give you four tiles, as illustrated with the following figure:

It's really not the most common tiles layer, but you can see it as the most efficient tile system for custom requirements. You can better choose your level of tiling or you can also use custom tile size. For example, for mobile, a smaller tile with 64 pixels for its side can be used instead of the standard 256 pixels size. We recommend, if you are curious, to see the official examples at http://openlayers.org/en/v3.0.0/examples/ using the WMTS keyword. We will not be covering the details here. You can learn more about the standard itself by going to the official dedicated web pages at http://www.opengeospatial.org/standards/wmts.

You also need to understand that one of its main goals was to fill the issue for fast rendering contrary to OGC WMS standard as it can be cached.

The DebugTileSource source is only a way to debug tiles rendering in OpenLayers 3. It doesn't use the tile numbering from the source but the internal that OpenLayers use. We just mentioned it to be exhaustive. You use it into a ol.layer.Tile class. You can look at the demo to learn more about it at http://openlayers.org/en/v3.0.0/examples/canvas-tiles.html. It can really help you to debug special grid, for example, in WMTS.

A WMS (Web Map Service) is a standard protocol for serving georeferenced map images over the Internet that are generated by a map server. You can watch the full reference at the official OGC (Open Geospatial Consortium) website, the organization managing this standard (http://www.opengeospatial.org/standards/wms).

The two versions of WMS available are 1.1.1 and 1.3.0.

WMS is dynamic: you can generate on the fly images.

So, why do I see a reference to a tiled WMS in OpenLayers 3?

It's just a way to lower charge on server-side—when you are generating small images, the process is faster, the memory cost does not really change as the number of requests increase, but you gain the ability to cache the tiles.

But wait, so why can't we use ImageWMS with WMS if we can have the advantage of both tiled (caching) and untiled system (freshness)?

We will not directly answer this right now, but will give you the hint in the section dedicated to ImageWMS.

You can refer to the official example to see a simple example as a reference at http://openlayers.org/en/v3.0.0//examples/wms-tiled.html.

Contrary to most components that are useful only in a map context, this component helps you to display any arbitrary images. It's really useful when you need to display a large image and want performances associated with tiles displayed and the usual interactions of mapping such as panning and zooming.

Some use cases can be game maps, discovery of scanned historical documents such as birth certificates for genealogy, or the old maps with no referencing, meaning that they do not overlay well with existing imagery and geographical data.

To make the ol.source.Zoomify component work, you will need to preprocess a large image to create tiles.

We just made a map using images' tiles using Zoomify source with its particular grid.

The main particular thing to understand in the sample is to set a projection definition that uses image pixel coordinates, for example:

  var proj = new ol.proj.Projection({
    code: 'ZOOMIFY',
    units: 'pixels',
    extent: [0, 0, imgWidth, imgHeight]
  });

We use units' pixels instead of the more usual degrees or meters and the original image width and height are used to define the extent. Then, we use pixels as extent units, instead of meters or degrees.

The component retrieves each tile as we zoom in/out. To get an overview of this behavior, we recommend that you open the Network panel and play a bit with the demo.

Now, it's time to review untiled layers.

Like the tile layer WMS already reviewed, this component is also using the WMS standard to retrieve the map, imayer. The thing that differs here is that you add a layer using an ol.layer.Image constructor instead of the now more usual ol.layer.Tile and, your ol.source is ol.source.ImageWMS instead. Next, you just have to complete the parameters like for a tiled WMS.

Now, let's see why we need to use untiled WMS.

See the two following images coming from the official example when you zoom in. The first one comes from http://openlayers.org/en/v3.0.0/examples/wms-tiled.html. See the following screenshot:

The second image, as shown here, is the untiled one from http://openlayers.org/en/v3.0.0/examples/wms-image.html:

You can see that, particularly for labels, they are duplicated. This behavior is quite simple: each tile is requested separately in a tiled WMS. Most of the time the position of the label depends on the position of the object, but here you can request it more than one time because of your tiles. In conclusion, be careful to not use tiled WMS when you are using automatic labeling in WMS or you will suffer from labels' duplications.

After this functional review, let's inspect the WMS layer ImageWMS source class properties:

The constructor is ol.source.ImageWMS. Contrary to the tiled version, you can't call multiple URLs. The options are available as follows:

After this raster overview, it's time to review a bit more on how to combine those different layers in a big mashup. We will illustrate it combining the layers based on OpenStreetMap projection, the Spherical Mercator.

We just created a map using different tiles' layers with a WMS overlay. We also create, as a bonus, a simple but dynamic layer switcher. All the layers use the map's projection, EPSG:3857, and line up with the lower aerial Bing Maps.

After revising, it's time to see another source to display the image: the ol.source.MapGuide source.

We didn't review this server, although an open source version of this server is available at http://mapguide.osgeo.org, when we saw the various servers available to provide images for the OpenLayers 3 library. We chose to not cover it in detail, because this solution is not mainstream and beginners will not be able to dive deeper in to this complex solution.

You just need to understand that this image source is unusual and is mostly used by people coming from the CAD (Computer-aided design) world because this software was released as open source by AutoDesk, the leading company for 2D/3D drawing software.

After this short review, it's time to see ol.source.ImageStatic, a class that can be seen as the equivalent for the nonprojected image of TileWMS for ImageWMS. It can be also seen as a non-Zoomify source. We will see how to use it within an untiled layer.

You changed the center for the view by using a positive value for the second value in the imgCenter variable. It's because the ol.source.ImageStatic doesn't use the same origin as the ol.source.Zoomify.

We also set as an option, attributions referencing the credits to the Wikipedia Commons image.

The most important parts for configuration for the constructor are the url, imageSize, and imageExtent.

We also reused the projection based on pixels' units to set the projection for the source. As a reminder, you can inspect the available properties for the source.