.. _imagemaps:

*****************************************************************************
 HTML Imagemaps
*****************************************************************************

:Author:       David Fawcett
:Contact:      david.fawcett at gmail.com
:Last Updated: 2008-10-08

.. contents::
    :depth: 2
    :backlinks: top


Introduction
============

The shpxy method of creating imagemaps uses MapServer query functionality to 
build a html imagemap.  Just like a regular MapServer query, you send a query 
request and MapServer uses the templates to build a block of html that it sends 
back to the browser.  The first example shows you how to build an imagemap 
based on a point layer.  An example template for a polygon layer is also 
included.    

**Components**

- MapServer mapfile
- query template file
- query header template
- query footer template



Mapfile Layer Definition
===========================

Here is a simple mapfile for our example

::

  MAP
  NAME "myMapFile     
  STATUS ON
  SIZE 200 200
  EXTENT 178784 4804000 772653 5483346

  UNITS METERS
  STATUS ON
  SHAPEPATH "/web/maps/data"  
  IMAGECOLOR 255 255 255

  WEB
    IMAGEPATH "/web/maps/tmp/"				
    IMAGEURL "/maps/tmp/"
  END   

  QUERYMAP
    STATUS ON
    STYLE NORMAL
  END 

  LAYER
    NAME "sites"
    STATUS DEFAULT
    TYPE point
    DATA 'aqiAreas'
	TEMPLATE "bodytemplate.html"
	HEADER "imapheader.html"
	FOOTER "imapfooter.html"
  END  
  END  


You can see that we have a mapfile with one point layer, and that it 
contains references to three query templates. 

Templates
==============================

In MapServer, the query header and footers get processed only once.  The 
main query template, 'bodytemplate.html' in this example, gets processed 
once for each record in the record set returned by the query.  

Point Layers
-------------

Here is the query header, 'imapheader.html'.  It creates the opening tag 
for your html imagemap.

:: 

  <map id="mymap" name="mymap">


Here is the query template, 'bodytemplate.html'.  It creates the body of 
the html imagemap. 

::

   <area shape="circle" coords="[shpxy precision=0 proj=image yf=",7" xf=","]" href="http://my.url/mypage.cfm?region=[NAME]" title="[NAME]" alt="[NAME]">

This template is used to create circular imagemap elements for a point layer. 
NAME is a fieldname in the data source, the value for NAME for each 
individual record gets substituted as the template is processed.  The 
href specifies the URL link if the element is clicked.  Title and alt will 
display the value when an element is moused over.  

The resulting html element looks like

::

   <area shape="circle" coords="80,103,7" href="http://my.url/mypage.cfm?region=Northern" >


The key part here is

::

   coords="[shpxy precision=0 proj=image xf="," yf=",7"]"


This is where MapServer will substitute the image coordinates for that 
query record.  With Precision=0, the coordinates will be integers.  

You also see shpxy template formatting options 'xf' and 'yf'.  'xf="," 
tells MapServer to place a comma after the x coordinate.  'yf=",7" after 
the y coordinate.  This is done to specify a radius of 7 pixels for the 
circle.  More options can be found in the :ref:`Template Reference <template>`.

The query footer template simply adds the closing tag for the html imagemap

::

   </map>


Polygon Layers
---------------

Here is a query template for a polygon layer

::

   <area shape="poly" coords="[shpxy precision=0 proj=image]" href="http://my.url/mypage.cfm?ID=[SITE_ID]" title="[NAME]" alt="[NAME]">


Request URL
==============================

To get the imagemap, you need to send a GET or POST request to MapServer 
with several URL variables defined.  The below URL tells MapServer where 
the mapfile is located, what layer we are querying, and that we are 
using nquery mode to return multiple results.  

::

   http://myurl/cgi-bin/mapserv?map=/web/maps/demoimap.map&qlayer=sites&mode=nquery&searchmap=true



Additional Notes
=================

If you use separate map files to generate your imagemap and your map 
image, make sure that the EXTENT and SIZE specified in both mapfiles 
are identical.  If they are not, your features will not align properly.

More Information
=================

 `Steve Lime's SHPXY Example`_ 

.. #### rST Link Section ####

.. _`Steve Lime's SHPXY Example`: http://maps.dnr.state.mn.us/cgi-bin/mapserv56?map=/usr/local/www/docs_maps/eco/rsg/search/search_example.map&qlayer=county&mode=nquery&searchmap=true