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

Up to the MapServer 8.4 release the OpenLayers Viewer was based on OpenLayers 2. As of MapServer 8.6-dev the OpenLayers viewer was updated to work with OpenLayers 10.5+. The MapServer CGI Layer, used by the viewer, can be see in the OpenLayers examples.

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:

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

When using the mode=browse MapServer will create an image on the server. By default this will be in the same folder as the Mapfile. If this MapServer cannot write to this folder you will see an error similar to:

msSaveImage(): Unable to access file. Failed to create output file (/etc/mapserver/Test174833722471.png).

In this case you will need to set your IMAGEPATH to a folder MapServer can write to.

That’s it!

If you don’t have a live MapServer install to play with, you can also try the MapServer demo.

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 parameters
SERVICE=WMS
VERSION=1.3.0
REQUEST=GetMap
WIDTH=512
HEIGHT=512
TRANSPARENT=true
CRS=EPSG:4326
BBOX=-90,-180,90,180
STYLES=

If you don’t have a live MapServer install to play with, you try the `MapServer demo <https://demo.mapserver.org/cgi-bin/wms?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetMap&BBOX=-90,-180,90,180&CRS=EPSG:4326&WIDTH=953&HEIGHT=480&LAYERS=bluemarble,continents,country_bounds,cities&STYLES=&FORMAT=application/openlayers&TRANSPARENT=true`__.>`__.

Customizing settings¶

environment variables:
MS_OPENLAYERS_JS_URL - the URL to the OpenLayers JavaScript library.
MS_OPENLAYERS_CSS_URL - the URL to the OpenLayers CSS file used for styling.

These variables can also be set in a mapfile, for example to point to the full OpenLayers build on a CDN (Content Delivery Network):

CONFIG "MS_OPENLAYERS_CSS_URL" "//cdn.jsdelivr.net/npm/ol@v10.5.0/ol.css"
CONFIG "MS_OPENLAYERS_JS_URL" "//cdn.jsdelivr.net/npm/ol@v10.5.0/dist/ol.js"

Location of the embedded OpenLayers.js file¶

If you aren’t providing your own OpenLayers library through MS_OPENLAYERS_JS_URL and MS_OPENLAYERS_CSS_URL, MapServer will point to hard-coded filepaths at mapserver.org/lib to find the OpenLayers library, referred to in maptemplate.c.

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.