Dissecting Your Map

As demonstrated in the previous section, a map is generated by bringing together markup, style declarations, and initialization code. We'll look at each of these parts in a bit more detail.

Map Markup

The markup for the map in the previous example generates a single document element:

  <div id="map"></div>

This <div> element will serve as the container for our map viewport. Here we use a <div> element, but the container for the viewport can be any block-level element.

In this case, we give the container an id attribute so we can reference it as the target of our map.

Map Style

OpenLayers comes with a default stylesheet that specifies how map-related elements should be styled. We've explicitly included this stylesheet in the map.html page (<link rel="stylesheet" href="/ol.css" type="text/css">).

OpenLayers doesn't make any guesses about the size of your map. Because of this, following the default stylesheet, we need to include at least one custom style declaration to give the map some room on the page.

  <link rel="stylesheet" href="/ol.css" type="text/css">
  <style>
    #map {
      height: 256px;
      width: 512px;
    }
  </style>

In this case, we're using the map container's id value as a selector, and we specify the width (512px) and the height (256px) for the map container.

The style declarations are directly included in the <head> of our document. In most cases, your map related style declarations will be a part of a larger website theme linked in external stylesheets.

Map Initialization

The next step in generating your map is to include some initialization code. In our case, we have included a <script> element at the bottom of our document <body> to do the work:

  <script>
    var map = new ol.Map({
      target: 'map',
      layers: [
        new ol.layer.Tile({
          source: new ol.source.TileWMS({
            url: 'https://ahocevar.com/geoserver/wms',
            params: {LAYERS: 'nasa:bluemarble', TILED: true}
          })
        })
      ],
      view: new ol.View({
        projection: 'EPSG:4326',
        center: [0, 0],
        zoom: 0,
        maxResolution: 0.703125
      })
    });
  </script>

The order of these steps is important. Before our custom script can be executed, the OpenLayers library must be loaded. In our example, the OpenLayers library is loaded in the <head> of our document with <script src="/loader.js"></script>.

Similarly, our custom map initialization code (above) cannot run until the document element that serves as the viewport container, in this case <div id="map"></div>, is ready. By including the initialization code at the end of the document <body>, we ensure that the library is loaded and the viewport container is ready before generating our map.

Let's look in more detail at what the map initialization script is doing. Our script creates a new ol.Map object with a few config options:

  target: 'map'

We use the viewport container's id attribute value to tell the map constructor where to render the map. In this case, we pass the string value "map" as the target to the map constructor. This syntax is a shortcut for convenience. We could be more explicit and provide a direct reference to the element (e.g. document.getElementById("map")).

The layers config creates a layer to be displayed in our map:

  layers: [
    new ol.layer.Tile({
      source: new ol.source.TileWMS({
        url: 'https://ahocevar.com/geoserver/wms',
        params: {LAYERS: 'nasa:bluemarble', TILED: true}
      })
    })
  ],

Don't worry about the syntax here if this part is new to you. Layer creation will be covered in another module. The important part to understand is that our map view is a collection of layers. In order to see a map, we need to include at least one layer.

The final step is defining the view. We specify a projection, a center and a zoom level. We also specify a maxResolution to make sure we don't request bounding boxes that GeoWebCache cannot handle.

  view: new ol.View({
     projection: 'EPSG:4326',
     center: [0, 0],
     zoom: 0,
     maxResolution: 0.703125
  })

You've successfully dissected your first map! Next let's learn more about developing with OpenLayers.