Skip to end of metadata
Go to start of metadata

This tutorial aims to walk through the process of adding a new map layer from a Web Mapping Service (WMS)

Start with a working application

Go to the mapbuilder directory and find the "simple" demo:

There you will find a configuration file named "simpleConfig.xml". Open this up in a text editor and look for the line:

This atlasWorld.xml file is known as a context document. The context document defines what WMS layers are displayed in your map. Since you don't want to mess with a working document without first making a copy, we should change this line to read:

And finally we'll create the mycontext.xml by copying the existing atlasWorld.xml file. Exit the text editor and copy the file like so:

Now go to http://localhost:8080/mapbuilder/demo/simple/index.html and your should see a world map whose data sources are configured in the mycontext.xml. Note that the url above will have to be adjusted according to your particular installation.

Find the WMS layer you want to add

Let's say we want to add the "modis" layer from the NASA WMS site. This layer is better known as "Blue Marble" and is a beautiful world-wide satellite image.. exactly as I imagine the earth would look from space if there were no clouds and the earth were crushed into two dimensions (wink)

We know the URL to the NASA WMS site so we use a web browser to make a request to get it's capabilities, creatively called a "GetCapabilities" request:

This returns an xml document containing, among other things, a list of the available layers. We scroll down and find the "modis" layer:

Also, take a look at the rest of the document and note the available image formats, coordinate systems (look for EPSG:***) and the online resource URL for the server.

Note that the scales defined in <ScaleHint> will not be the same as the scales seen in Mapbuilder by default. OpenLayers renders maps at 72 dpi by default, whereas OGC uses 90.714 dpi. If it is required to have Mapbuilder use the same scales, the following code has to be added in a script tag in the head of the application's html page, after the script tag that loads Mapbuilder.js (MapbuilderCompressed.js):

The "modis" layer looks like the one we want so now we proceed to add it to our map.

(To discover other WMS layers, visit

Adding the WMS layer to myconfig.xml

Open myconfig.xml in a text editor. Scroll down to find the <LayerList>. Each layer listed hereafter is drawn in turn on the map; The layers at the top of the file will show up underneath those below. Since we want this image to be a base map, we add it to the top of the list, directly after <LayerList>.

But what exactly do we add? The layer entry in our myconfig.xml will differ slightly from the layer entry in the GetCapabilities file. Some things are the same (Name, Title). Some things must be determined from variables eleswhere in the GetCapabilities file (SRS, FormatList, Server). Look carefully at the GetCapabilities document and compare the two and you will see how this layer entry is constructed.

Before you close myconfig.xml, take a look at some of the other layers below it.

The layers with names "ocean", "land", and "lake_fill" are all polygon layers that will block display of the underlying base map. For each of these layers, you can either delete them entirely OR simply make them hidden. If you're using another demo the display this same config file, this would give you the opportunity to toggle those layer on and off. To make them hidden, change the hidden="0" to hidden="1" for each layer:

One final thing: We want a nice big map that shows a bit more detail. Scroll up to the top of the file and find the "Window" attribute. This defines the size of our map image. Let's change it from a 400x200 pixel size to 800x400:

All right, we're done! Check out the URL for the simple demo again and you should see a bigger map with the blue marble image added as a base map.

  • No labels