OpenLayers Tutorial - Part 1: Introduction

OpenLayers
Posted on Oct 3rd, 2009
This is the first part in a series of OpenLayers tutorials. The goal of this article is to provide an overview of OpenLayers, show what it can do, and begin working with the code.

OpenLayers is an OpenSource, javascript based web mapping platform.

OpenLayers easily supports a wide variety of various map sources - WMS, WFS, Google Maps, Microsoft's Bing, and many many more. There are many built into tools, such as scale bars, overview maps, zoom bars, and many more; but OpenLayers also supports custom tools and allows for intricate configuration of existing ones.
Useful OpenLayers links
OpenLayers - http://openlayers.org
OpenLayers API docs - http://dev.openlayers.org/apidocs
OpenLayers Examples - http://openlayers.org/dev/examples


OpenLayers Examples
The follow examples are pulled directly from http://openlayers.org/dev/examples

Simple WMS map- http://openlayers.org/dev/examples/wms.html
Vector layer manipulation - http://openlayers.org/dev/examples/vector-formats.html
Google Map layer - http://openlayers.org/dev/examples/google.html
ArcGIS 9.3 REST API Interaction - http://openlayers.org/dev/examples/arcgis93rest.html

Section 1 - First OpenLayers Map


We'll start with a basic map. As OpenLayers is Javascript based, some working knowledge of how to program in Javascript is helpful, but expertise is by no means required. First we'll take a look at the code then break it apart.

Create and show a simple OpenLayers Map
Step 1. Create a folder called "OLTutorial". If working in windows, this tutorial assumes you are placing the folder in your C:\ drive ( so the full path would be C:\OLTutorial )

Step 2. Create a file called index.html (If you're on windows, you will probably need to disable the "Hide extensions for known file types" option. How to disable hidden file extensions in windows xp)

Step 3. Input the following code

<html>

<head>

<script type="text/javascript" src="http://openlayers.org/api/OpenLayers.js"></script>

<script type="text/javascript">

var map;

function init() {
    map = new OpenLayers.Map('map');
    var wms = new OpenLayers.Layer.WMS(
        "OpenLayers WMS",
        "http://labs.metacarta.com/wms/vmap0",
        {layers: 'basic'}
    );
    map.addLayers([wms]);
    map.zoomToMaxExtent();
}

</script>

</head>

<body onload="init()">

<div id="map" style="width: 600px; height: 300px"></div>

</body>

Step 4. Save the file then open it in your browser.

You should see a very simple OpenLayers map.
Explanation
The above OpenLayers example requires, essentially, only three things.
1. The location of the OpenLayers library
2. An HTML element (a div in this case) to hold the map
3. Javascript code to define the OpenLayers map and tell the map where to point to (again, in this case, a div)

The location of the OpenLayers library in this example points to the OpenLayers.js file on the OpenLayers server. You are free to download the full OpenLayers code and run it locally, pointing your script src="..." equal to the location of the OpenLayers library on your harddrive.

Let's look at the code line by line.


<html>

<head>

<script type="text/javascript" src="http://openlayers.org/api/OpenLayers.js"></script>

Line 1 and 2 begin the HTML document and start the HEAD section of the index.html page. The HEAD section is where our script code will reside.
Line 3 points to the OpenLayers library. You must include the OpenLayers library before you try to use OpenLayers code. The library contains the OpenLayers codebase - our code relies on the OpenLayers library, and without it our code would not work.


<script type="text/javascript">

	var map;
Line 1. begins a new script tag and will hold our Javascript code to create the OpenLayers map.
Line 2. Creates a global variable called "map" which will act as our map object, which will hold the OpenLayers map itself.

function init() {
	map = new OpenLayers.Map('map');

	var wms = new OpenLayers.Layer.WMS(
		"OpenLayers WMS",
		"http://labs.metacarta.com/wms/vmap0",
        {layers: 'basic'}
	);
>This init function will initialize the map, creating the OpenLayers map and assign a layer to it.

Line 1. Create a function called init without passing anything into the function.
Line 2. We're using the map object previously declared above. Here, we're assigning the previously empty map variable to an OpenLayers map object via

our code: new OpenLayers.map('map');
general code: new OpenLayers.map('ELEMENT NAME');
new creates a new OpenLayers map object. We are passing in 'map', which is a string containing the name of element we want the OpenLayers map to appear in on the webpage. In this example, we have a div element with the id of 'map'. If this div's id was named something else, we would pass in the that div's id name instead of 'map'.

Line 3. Here we're creating a wms variable which will hold an OpenLayers layer object. We call new to create an OpenLayers Layer WMS object. For other layer types, such as WFS or Google Maps, the call is similar but WMS is replaced with the layer service. The full list of support layers and how to call them can be found at http://dev.openlayers.org/releases/OpenLayers-2.8/doc/apidocs/files/OpenLayers/Layer-js.html.

At the end of the line we have a opening parenthesis, which means that we're going to pass in some configuration stuff to this OpenLayers Layer object.

It is important to keep in mind that the following configuration code will of course differ for you, but also that the configurations will be different for different layer services. Consult the linked documentation files above for more detailed information.

Line 4. This line specifies an arbitrary title of the layer we're creating.

Line 5. This is the URL of the WMS service

Line 6. This is a dictionary of options the Layer object uses to generate the layer. In this case, we want the "basic" layer from the layers of the WMS service we're calling. You can call getCapabilities on the WMS url to view a list of layers the WMS service contains.
Note - we can specify as many WMS service layers we want to display in our OpenLayers Layer object. For example, we could show three layers from the WMS service in a -single- OpenLayers Layer.

http://labs.metacarta.com/wms/vmap0?service=WMS&request=getCapabilities
The above URL calls getCapabilities for the WMS service we're using for this OpenLayers Layer. If we look at that URL in our browser it will show us an XML file. We can see what layers the WMS service has by looking for LAYER tags and looking at the NAME. For example, this XML files contains

    ...

	    <Layer>

		    <Name>basic</Name>

    ...

    
This 'basic' layer is the 'basic' layer we are referring to in { layers: 'basic'}

Back to the code...

	map.addLayers([wms]);
	map.zoomToMaxExtent();
}
Line 1. We're adding the newly defined wms layer to the map here. We can add multiple layers at once, but in this case we are just passing in one. Regardless, the addLayers function expects a list of layers, so we must pass in a list via ([ layername ])

Line 2. After we've defined the map and added a layer to it, we need to tell the map what extent to display. If we don't do this, the map doesn't know what to display.
So, in this case, we tell the map to zoom to the max extent - in other words, we are telling the map to show everything is can.

Line 3. Finishes the init function.

</script>
</head>

<body onload="init()">

<div id="map" style="width: 600px; height: 300px"></div>

</body>
Line 1. Closes the script tag

Line 2. Closes the head tag

Line 4. Starts the body tag and call init() when the body has finished loading.

Line 5. Create a div with the id of map which the OpenLayers Map object will render to. The div can be styled however you like. We'll just make a 600 x 300px big map for this example though.

Line 6. Closes the body

Conclusion

That's all that's required to get a map up and running! There are a myriad of controls, layers, and options that we haven't even mentioned (yet!). The next tutorial will discuss the OpenLayers Layer class more and touch briefly on controls. Again, more examples and details can be found through the OpenLayers.com API or on the OpenLayers irc channel at irc.freenode.net in the #openlayers channel.

Ready for the next post? Continue to OpenLayers Tutorial - Part 2 - Layers
NEXT | OpenLayers Tutorial - Part 2: Layers
All Posts

Engage

Comments