= !MapContext Howto =

----
IMPORTANT NOTE: '' A formal HOWTO is now available at http://www.mapserver.org/ogc/mapcontext.html. This Wiki document is now considered out of date. ''
----

Support for OGC Web Map Context has been added to MapServer in version 3.7. This allows client applications to load and save a map configuration in an standard XML format. Note that a context definition contains only references to WMS layers (CONNECTIONTYPE WMS).

MapServer can read context documents of versions 0.1.2, 0.1.4 and 0.1.7 and can export contexts in versions 0.1.4 and 0.1.7.

A copy of the OGC Web Map Context 0.1.4 specification can be downloaded from:

    http://www.opengis.org/techno/discussions/02-066r1.pdf

== Special Build consideration ==

Map Context support requires PROJ4, GDAL/OGR and PHP support libraries.

Build/install the above libraries on your system and then build MapServer with the '--with-wmsclient --with-proj --with-php' configure options.

== Map Context options in a mapfile ==

As mentioned above, a map context document can contain only references to WMS layers (CONNECTIONTYPE WMS). Please refer to the MapServer WMS Client HOWTO for more information on WMS layers. The following metadata are used by MapServer to handle map context information:

=== Web object metadata ===

- wms_context_version
    Version of the Map Context specification. 

- wms_context_fid
    Feature id of the context. Set to 0 if there's when saving if not specified. 

- wms_title
    This metadata does not exist anymore in version 0.1.7. 

- wms_keywordlist

- wms_abstract

- wms_logourl
    This metadata contains 4 elements space separated. The width of the image, the height, the format and the URL. 

- wms_dataurl

- wms_contactperson

- wms_contactorganization

- wms_contactposition

- wms_addresstype

- wms_address

- wms_city

- wms_stateorprovince

- wms_postcode

- wms_country

- wms_contactvoicetelephone

- wms_contactfacsimiletelephone

- wms_contactelectronicmailaddress

=== Layer object metadata ===

- wms_name
    Name of the WMS layer on the server. 

- wms_title

- wms_abstract

- wms_onlineresource
    URL to access the server. 

- wms_server_version

- wms_formatlist
    List of available format for this layer. 

- wms_format
    Current format used. 

- wms_stylelist
    List of available style for this layer. 

- wms_style
    Current style used. 

- wms_style_%s_title
    Title of the layer. %s = The name of the style. 

- wms_style_%s_sld
    URL to the SLD document of this style. %s = The name of the style. 

- wms_style_%s_legendurl
    Location of an image describing the style. This metadata contains 4 elements separated by spaces. The width of the image, the height, the format and the URL. %s = The name of the style. 

== Testing Map Context Support ==

The first thing to do is to save your mapfile using the saveMapContext? function available from the php_mascript library. After, scan the XML output to look for <!-- WARNING: ... --> comments. Then take actions to fix every warning that you encounter. At the end of this you should have a mapfile compatible with the Map Context.

Then you can load your new Map Context with a php_mapscript application. MapBrowser? from MapLab? is a good tool for that. With this tool you can load Map Context from othere servers with the loadMapContext? function from php_mapscript or save a mapfile into a Map Context.

== TODO, Known limitations ==

Before 3.7 release

- Need to validate request results against the corresponding XMLSchema files.

-Maybe add a configure option (--with-context).

Longer term TODO and limitations

- Implement new metadata to separate all element from the wms_style_%s_legendurl. Because theyare space separated and the legendurl format can contain spaces and the legendurl url can contain commas.