= GIS API =

Developers need to be able to embed maps within their Modules & display Features.

They don't want to have to become GIS experts for this - they just want to be able to call a documented mapping API:

 * A function which returns all the HTML needed to insert a map on the page, with the following customizations:
  * Be able to define which locations get placed on this map. This might include a number of different types (groups?) of locations. For each type/group we can specify:
   * The Marker (default from gis module). 
   * A function to call to return the size/colour of the marker, based on the location id. (advanced)  
   * A form which get displayed as the pop-up for the markers (along with the location_id as a arg/var, so can customize the display)
  * Be able to define the default size of the map
 * It would be good to be able to pass additional layers (or turn current layers off) to the map via JS, so that the map can be controlled dynamically using external controls. Although this probably represents a great deal of complexity and may need to be reconsidered.

== Status ==
Live:
 * [wiki:DeveloperGuidelinesGIS#GuidelinesforDeveloperswishingtomakeuseofMappingwithintheirModule]

Still needed:
 * [wiki:BluePrintGISSelectLocationFromMap Popup to add Location by placing cursor on Map]
 * Dynamic filtering of the Features in a Feature Layer
 * Graphs on Icons &/or Popups (probably using SVG from the [http://eden.sahanafoundation.org/browser/modules/savage SaVaGe] library)
  * Bar charts
   * e.g. Number of assessed buildings per administrative unit with Green/Yellow/Red statuses
  * Pie charts (see bottom of http://robslink.com/SAS/democd28/exceptional_info.htm)
   * e.g. For Shelters to represent utilised/free capacity, and the total size of the centre.
   * A caution on using the size of a circle to denote amount:  People can't estimate amount well from the diameter of a circle - the visual size increases as the square, so a circle that is twice as large as another dominates the smaller one - it "feels" more than twice as large.  A linear visualization like a bar graph will let people more accurately get an idea of both absolute and relative amounts.

== Discussion ==

We can pass information in 3 different ways:
 1. Argument
 2. Global variable (e.g. request.s3.gis_*) <- Not Advised
 3. Config in Database <- Not efficient
  * {{{gis.read_config()}}}

Here is the API from the original PHP version:
 * http://wiki.sahanafoundation.org/doku.php/dev:gisapi

This is the current API used by the FRP application:
{{{
http://127.0.0.1:8000/frp/gis/map_viewing_client?
    kml_name=Programmes&
    kml_feed=http://127.0.0.1:8000/frp/or/programme/report.kml?
        from=2010-04-23&
        until=2010-04-23&
        mode=programme
}}}

The pr/person/presence includes a link to embedding a map within a page:
{{{
<a onclick="viewMapMulti('{{=request.controller}}','{{=request.function}}',{{=request.args[0]}},'{{=request.args[1]}}');return false" href="#">View All on Map</a>
}}}

!MapFish have an API in !JavaScript to allow their apps to be embedded in CMSs:
 * http://mapfish.org/doc/contribs/mapfishapi.html

=== Produce Custom Overlay ===

This would produce a custom overlay with either:
 * polygons highlighted
 * variable sized markers (image, circle, bar)
I'm not sure if this is the right way to do it. But this is the sort of functionality I'd want.[[BR]]
In fact, this function should be included with the API above, or I think that parts of the API above should be included with this.
{{{
Args:
Locations - list of dicts - [{ location_id: ..., code_id: ...,  value:...}, {}, ...]
code_id - used to lookup the marker/colour from the code_values list for this location_id.
value - used to define the size of the marker.
Type - Fill-Colour (for polygons only) / Marker / Circle / Bar Graph.
Code Values - list - either of marker images to use, or colour values. *Predefined code values could be included in the code.
popup_url = <default>, # The URL which will be used to fill the pop-up. it will be appended by the Location ID.
}}}

Want to be able to change the selection of Features without reloading the map.
 * Have just a single Feature Layer defined?
  * {{{displayInLayerSwitcher: false;}}}
 * The controls to filter need to hook directly into the Map to reload the Features Layer over the (static) Base Layer
  * Catch Event & call [http://dev.openlayers.org/releases/OpenLayers-2.9.1/doc/apidocs/files/OpenLayers/Map-js.html#OpenLayers.Map.removeLayer map.removeLayer()] then a new [http://dev.openlayers.org/releases/OpenLayers-2.9.1/doc/apidocs/files/OpenLayers/Map-js.html#OpenLayers.Map.addLayer map.addLayer()]
  * Filters in main HTML & hence using jQuery: http://api.jquery.com/change/ or
  * Filters in map window & hence using Ext: http://www.extjs.com/deploy/dev/docs/source/Observable.html#method-Ext.util.Observable-addListener

  * Example app: http://mkgeomatics.com/apps/ajax_dev/Working052809/logged_in.html
   * Also includes nice example of clustering!

----
[wiki:BluePrintGeographicInformationSystems GIS BluePrints]