wiki:BluePrintGISAPI

Version 12 (modified by Fran Boon, 12 years ago) ( diff )

--

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>

Proposed API

Early draft!

Embed a map within a Page

    gis.show_map(height              = <default>, 
                 width               = <default>,
                 base_layers         = <default>, 
                 internal_overlays   = None,
                 internal_layertree  = True,
                 external_overlays   = None,
                 external_layertree  = True,
                 toolbar             = False,
                 lat                 = <default>,
                 lon                 = <default>,
                 zoom                = <default> 
)
    """
    height - int - height of map in pixels
    width - int - width of map in pixels
    base_layers - list of strings - base layers used for map
    internal_overlays - list of dictionaries:
        {
         db.gis_feature_group.name,
         filter = None,
         marker = <default>,
        }
    internal_layer_menu - bool - whether or not to display the menu to turn on and off the internal_layers
    external_layers - list of ints - The external overlays (WMS/KML/GeoRSS/etc) to display on the map. Hard-coding this is Ugly! Can we not just make it Bool & use Map Service Catalogue for more control?
    external_layer_menu - bool - whether or not to display the menu to turn on and off the external_layers
    toolbar - bool - whether or not to display the toolbar
    lat - double - Initial map center point
    lon - double - Initial map center point
    zoom - int - the initial zoom level of the map

    markers - list of URLs - to images to display
    popup_url - list of strings - The URL which will be used to fill the pop-up (potentially different for each internal_layer) (???current term). it will be appended by the Location ID.

    Will return the HTML to embed a map with the specified options.
    It would be cool if the layer menus could be tabs on the side, which slide out when you click on them...
   
    Questions: 
    * I am not entirely sure how the gis_feature_group will work. Perhaps it would be good to be able to pass a query to the function (one of the results of the query will be a location_id field). That would be really nice.

    Given all of these, I wonder if it would be best to pass a list of:
    internal_layer_options = {gis_feature_group_name,
                              query, #if query = None, use gis_feature_group_name
                              marker,
                              default #if the layer defaults on, or just appears on the menu.
                              }
    """

GIS BluePrints

Note: See TracWiki for help on using the wiki.