wiki:BluePrintGISAPI

Version 23 (modified by Fran Boon, 14 years ago) ( diff )

update to current

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.

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:

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:

Proposed API

Draft - work in progress!

Embed a map within a Page

    def show_map( self,
                  height = None,
                  width = None,
                  lat = None,
                  lon = None,
                  zoom = None,
                  projection = None,
                  feature_overlays = [],
                  wms_browser = {},
                  catalogue_overlays = False,
                  catalogue_toolbar = False,
                  toolbar = False,
                  search = False,
                  print_tool = {},
                  mgrs = {},
                  window = False,
                  public_url = "http://127.0.0.1:8000"
                ):
        """
            Returns the HTML to display a map

            @param height: Height of viewport (if not provided then the default setting from the Map Service Catalogue is used)
            @param width: Width of viewport (if not provided then the default setting from the Map Service Catalogue is used)
            @param lat: default Latitude of viewport (if not provided then the default setting from the Map Service Catalogue is used)
            @param lon: default Longitude of viewport (if not provided then the default setting from the Map Service Catalogue is used)
            @param zoom: default Zoom level of viewport (if not provided then the default setting from the Map Service Catalogue is used)
            @param projection: EPSG code for the Projection to use (if not provided then the default setting from the Map Service Catalogue is used)
            @param feature_overlays: Which Feature Groups to overlay onto the map & their options (List of Dicts):
                [{
                 feature_group : db.gis_feature_group.name,
                 parent : None,         # Only display features with this parent set. ToDo: search recursively to allow all descendants
                 filter : None,         # A query to further limit which features from the feature group are loaded
                 active : False,        # Is the feed displayed upon load or needs ticking to load afterwards?
                 popup_url : None,      # The URL which will be used to fill the pop-up. it will be appended by the Location ID.
                 marker : None          # The icon used to display the feature (over-riding the normal process). Can be a lambda to vary icon (size/colour) based on attribute levels.
                }]
            @param wms_browser: WMS Server's GetCapabilities & options (dict)
                {
                name: string,           # Name for the Folder in LayerTree
                url: string             # URL of GetCapabilities
                }
            @param catalogue_overlays: Show the Overlays from the GIS Catalogue (@ToDo: make this a dict of which external overlays to allow)
            @param catalogue_toolbar: Show the Catalogue Toolbar
            @param toolbar: Show the Icon Toolbar of Controls
            @param search: Show the Geonames search box
            @param print_tool: Show a print utility (NB This requires server-side support: http://eden.sahanafoundation.org/wiki/BluePrintGISPrinting)
                {
                url: string             # URL of print service (e.g. http://localhost:8080/geoserver/pdf/)
                }
            @param mgrs: Use the MGRS Control to select PDFs
                {
                name: string,           # Name for the Control
                url: string             # URL of PDF server
                }
            @param window: Have viewport pop out of page into a resizable window
            @param public_url: pass from model (not yet defined when Module instantiated

            @ToDo: Rewrite these to use the API:
                map_viewing_client()
                display_feature()
                display_features()
        """

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.
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.

GIS BluePrints

Note: See TracWiki for help on using the wiki.