MapServer OpenLayers Viewer¶

MapServer (since the 6.0 release) provides a simple, built-in method for testing a mapfile using OpenLayers. This feature is for testing/development purposes only, and not for production or deploying full-featured sites. You can preview, test, and navigate a mapfile by accessing a special url which will return a built-in OpenLayers template.

Note

This feature was discussed in rfc 63 and in the ticket https://github.com/MapServer/MapServer/issues/3549

Using the OpenLayers viewer¶

Opening the OpenLayers viewer in your browser¶

Assuming you are running mapserver on your local machine, and you have the Itasca demo setup, a basic url would be (split into two lines for readability):

http://localhost/cgi-bin/mapserv?mode=browse&template=openlayers
     &layer=lakespy2&layer=dlgstln2&map=/var/www/workshop/itasca.map

Here is a quick breakdown of that url:

Basic Parameters for activating the OpenLayers browser:
```
template=openlayers
mode=browse
```

Basic Map / Layer Parameters:

map=/var/www/workshop/itasca.map
layer=lakespy2
layer=dlgstln2

That’s it!

Opening the OpenLayers viewer in the form of a WMS request¶

This feature is useful when debugging WMS requests. You can write one of these by hand, or copy the URL for a WMS tile. Running the following should give you a simple OpenLayers demo around the BBOX (split into several lines for readability):

http://localhost/cgi-bin/mapserv?map=/var/www/workshop/itasca.map
     &LAYERS=lakespy2&VERSION=1.1.1&SERVICE=WMS&REQUEST=GetMap
     &FORMAT=application/openlayers&WIDTH=512&HEIGHT=512&SRS=EPSG:26915
     &BBOX=429956.19803725,5231780.0814818,444078.32296225,5245902.2064068

Here is a quick breakdown of the interesting parts of that URL:

Special Parameter for activating the OpenLayers viewer:
```
FORMAT=application/openlayers
```
Basic MapServer Parameters:
```
map=/var/www/workshop/itasca.map
```

Basic WMS parameters:

#Layers, our bounding box and projection
LAYERS=lakespy2
BBOX=429956.19803725,5231780.0814818,444078.32296225,5245902.2064068
SRS=EPSG:26915

#Version and other WMS request params
SERVICE=WMS
VERSION=1.1.1
REQUEST=GetMap
WIDTH=512
HEIGHT=512
TRANSPARENT=true

Customizing settings¶

environment variables:

MS_OPENLAYERS_JS_URL - The URL to the OpenLayers javascript library. Per default the library loaded from the MapServer web server.

Location of the embedded OpenLayers.js file¶

If you aren’t providing your own OpenLayers library through MS_OPENLAYERS_JS_URL, MapServer will point to a hardcoded filepath of www.mapserver.org/lib to find the OpenLayers library, referred to in [maptemplate.c](https://github.com/MapServer/MapServer/blob/main/src/maptemplate.c#L54).

The contents on that lib folder is stored in the MapServer documentation repository, in the [/extra](https://github.com/MapServer/MapServer-documentation/tree/main/extra) folder. You are warmly encouraged to contribute to upgrading the OpenLayers library, at any time (maybe start with creating a new [Pull Request](https://github.com/MapServer/MapServer-documentation/pulls) there.