.. index::
   simple: OpenLayers viewer

.. _openlayers:

*****************************************************************************
 MapServer OpenLayers Viewer
*****************************************************************************

MapServer 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 <http://mapserver.org/development/rfc/ms-rfc-63.html>`_
    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!**

.. uncomment me when the demo server is up to 6.0
.. If you don't have a live MapServer install to play with, you can also try this out on the demo server::
..
..    https://demo.mapserver.org/cgi-bin/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&BBOX=-180,-90,180,90&SRS=EPSG:4326&WIDTH=953&HEIGHT=480&LAYERS=bluemarble,continents,country_bounds,cities&STYLES=&FORMAT=image/png&TRANSPARENT=true&mode=browse&template=openlayers
..


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.
