[[PageOutline]]

= Configuring MS4W and !MapCache for use in !OpenLayers=

This was spawned by an MS4W user asking how to setup !OpenLayers for an MS4W !MapCache's WMS service ([http://osgeo-org.1560.x6.nabble.com/ms4w-3-1-4-mapcache-td5267121.html thread]), with the following incorrect Javascript code, which did not write tiles to MS4W's cache directory:
{{{
#!js

new ol.layer.Tile({
title: 'Chabahar',    
source: new ol.source.TileWMS({
url: 'http://localhost:100/cgi-bin/mapserv.exe?map=D:/WEB_GIS/code_test/wms/HTML5Application/public_html/chabahar.map&',
params: {
    'LAYERS': 'chabahar',
    'FORMAT': 'image/png',
    'TILED': true
},
serverType: 'mapserver'
})
                                        })  ,
}}}
[[NoteBox(tip, See Step4 below for correct !OpenLayers code but be sure to execute all Steps)]]

== Background Links ==

* [http://ms4w.com MS4W homepage] (Windows installer for !MapServer)
* [http://mapserver.org/documentation.html MapServer documentation] (Open Source web mapping engine)
* [http://mapserver.org/mapcache/ MapCache] (!MapServer's tile caching engine)
* [http://openlayers.org/en/latest/apidoc/ OpenLayers API] (front-end Javascript framework)

== Step 0: Install MS4W ==

* install [http://ms4w.com MS4W] (if you haven't already done so)

== Step 1: Initialize !MapCache Module

* follow all of the steps in MS4W's [http://ms4w.com/README_INSTALL.html#g-mapcache-apache-module README] to initialize the !MapCache module
* confirm that tiles are being generated inside the folder: ''/ms4w/tmp/ms_tmp/cache/''

== Step 2: Install MS4W's !OpenLayers Package ==

* if you haven't installed MS4W's !OpenLayers package (we'll use its sample WMS mapfile), please install it:
  * save the !OpenLayers zip locally from: http://ms4w.com/download.html#applications-packaged-for-ms4w
  * extract its contents to the root of your MS4W installation
  * restart Apache: as Administrator, execute: ''/ms4w/apache-restart.bat''
  * on your Web browser's MS4W homepage, click on the "!MapServer WMS Example" link, in the !OpenLayers section
  * this example uses a local WMS service, it should display the world countries as below: 
[[Image(OL-WMS.PNG, 600px, nolink)]]

== Step 3: Configure mapcache.xml to use this WMS as a Source ==

* add the following to your mapcache.xml file (and if necessary change the <url> and <map> paths):
{{{
#!xml

<source name="ms4wserver" type="wms">
  <http>
    <url>http://127.0.0.1/cgi-bin/mapserv.exe</url>
  </http>
  <getmap>
    <params>
      <map>C:/ms4w/apps/openlayers-3.15.1/examples/map/wms-server.map</map>
      <layers>countries</layers>
    </params>
  </getmap>
</source> 
}}}

* edit the existing <tileset> section of mapcache.xml, so that it includes:
{{{
#!xml

<tileset name="test">
  <source>ms4wserver</source>
  <cache>disk</cache>
  <grid>GoogleMapsCompatible</grid>
  <format>PNG</format>
  <metatile>5 5</metatile>
  <metabuffer>10</metabuffer>
  <expires>3600</expires>
</tileset>
}}}
  * we use the ''"!GoogleMapsCompatible"'' grid here, because !OpenLayers assumes the [https://epsg.io/3857 EPSG:3857] projection.  
[[NoteBox(tip, Read more about the various [http://www.mapserver.org/mapcache/config.html#grid "Preconfigured Grids"] for !MapCache)]]

* delete the existing cache folder: ''/ms4w/tmp/ms_tmp/cache/test''

* restart Apache: as Administrator, execute: ''/ms4w/apache-restart.bat''

* on your Web browser's MS4W homepage, click on the "Demo" link in the "!MapCache URLs" section.  Then click on the "wmts" link.  A world countries map should appear, and if you expand the "+" button on the top right, it should list a layer named "test-!GoogleMapsCompatible WMTS", as below: [[Image(MAPCACHE-WMTS-3857.PNG, 600px)]]

* zoom in a few times, and check your cache folder (''/ms4w/tmp/ms_tmp/cache/test''), you will notice that tile images are saved there.

== Step 4: Configure !OpenLayers to use this WMS Service ==

We will use one of the existing !OpenLayers examples' html and javascript, but you can adapt this for your own page.

* copy the file ''/ms4w/apps/openlayers/examples/getfeatureinfo-tile.js'' and rename it to ''mapcache-getfeatureinfo-tile.js''

* copy the file ''/ms4w/apps/openlayers/examples/getfeatureinfo-tile.html'' and rename it to ''mapcache-getfeatureinfo-tile.html''

* edit the file ''/ms4w/apps/openlayers/examples/getfeatureinfo-tile.html'' and change the source on line#178 such as:
{{{
#!js

<script src="loader.js?id=mapcache-getfeatureinfo-tile"></script>
}}}

* load that page in your Web browser using the appropriate URL (such as: http://127.0.0.1/openlayers/examples/mapcache-getfeatureinfo-tile.html) You should see a countries map with labels, such as: 
[[Image(OL-MAPCACHE1.PNG, 600px, nolink)]]

* delete the existing cache folder: ''/ms4w/tmp/ms_tmp/cache/test''

* edit the file ''/ms4w/apps/openlayers/examples/mapcache-getfeatureinfo-tile.html.js'' and change the ''wmsSource'' variable (at the top of the file) to:

{{{
#!js

var wmsSource = new ol.source.TileWMS({
  url: 'http://127.0.0.1/mapcache/',
  params: {
	        'LAYERS': 'test',
	        'VERSION': '1.1.1',
	        'FORMAT': 'image/jpeg'
	      },
  serverType: 'mapserver',
  crossOrigin: 'anonymous'
});
}}}
[[NoteBox(tip, for the 'LAYERS' parameter we must use the name that we defined earlier as the <tileset> in our mapcache.xml file)]]

* finally, refresh its html page in your Web browser (such as: http://127.0.0.1/openlayers/examples/mapcache-getfeatureinfo-tile.html) You should see the countries map (with no labels) such as: 
[[Image(OL-MAPCACHE2.PNG, 600px, nolink)]]

* zoom in a few times, and check your cache folder (''/ms4w/tmp/ms_tmp/cache/test''), you will notice that tile images are saved there in a ''"!GoogleMapsCompatible"'' subdirectory, as below: 
[[Image(OL-MAPCACHE3.PNG, 600px)]]

== Getting Additional Help ==

* feel free to ask your questions on the MS4W mailing list ([http://lists.ms4w.com/mailman/listinfo/ms4w-users subscribe])
* for professional support, please contact [http://www.gatewaygeomatics.com/contact.html Gateway Geomatics] (the original author of this tutorial)