wiki:DeveloperGuidelines/GIS

Version 25 (modified by Fran Boon, 11 years ago) ( diff )

feature_queries is a list of dicts

DeveloperGuidelines

GIS Module

Guidelines for Developers wishing to make use of Mapping within their Module

The easiest approach is to call the Mapping API.

Controller

map = gis.show_map()
return dict(map=map)

View

{{=XML(map)}}

Examples

Check the following functions in controllers/gis.py:

  • map_viewing_client()
  • display_feature()
  • display_features()

Full API description

def show_map( self,
              height = None,
              width = None,
              bbox = {},
              lat = None,
              lon = None,
              zoom = None,
              projection = None,
              feature_queries = [],
              feature_groups = [],
              wms_browser = {},
              catalogue_overlays = False,
              catalogue_toolbar = False,
              legend = False,
              toolbar = False,
              search = False,
              print_tool = {},
              mgrs = {},
              window = False,
              collapsed = False,
              public_url = "http://127.0.0.1:8000"
            ):
    """
    @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 bbox: default Bounding Box of viewport (if not provided then the Lat/Lon/Zoom are used) (Dict):
        {
        "max_lat" : float,
        "max_lon" : float,
        "min_lat" : float,
        "min_lon" : float
        }
    @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_queries: Feature Queries to overlay onto the map & their options (List of Dicts):
                [{
                 name   : "Query",      # A string: the label for the layer
                 query  : query,        # A gluon.sql.Rows of gis_locations
                 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 marker_id for the icon used to display the feature (over-riding the normal process).
                                        # [Plan: Can be a lambda to vary icon (size/colour) based on attribute levels.]
                }]
            @param feature_groups: 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 marker_id for the icon used to display the feature (over-riding the normal process).
                                        # [Plan: 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 legend: Show the Legend panel
    @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/)
        mapTitle: string        # Title for the Printed Map (optional)
        subTitle: string        # subTitle for the Printed Map (optional)
        }
    @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 collapsed: Start the Tools panel (West region) collapsed
    @param public_url: pass from model (not yet defined when Module instantiated
    """

Guidelines for Developers wishing to extend the functionality of the core GIS

OpenLayers

The GIS module uses OpenLayers for Display purposes, so a thorough understanding of this is a great foundation for what we do:

Projections: http://trac.openlayers.org/wiki/Documentation/Dev/proj4js

GUI

The map window is wrapped in an Ext GUI based on GeoExt (formerly MapFish client)

How to debug WMS

How to add a new Layer type

Assuming that OpenLayers supports the layertype:

Model

models/_gis.py

gis_layer_types=['newlayertype','...']
gis_layer_newlayertype_subtypes=['Satellite','Maps','Hybrid']
# Base table from which the rest inherit
gis_layer=SQLTable(db,'gis_layer',
            db.Field('modified_on','datetime',default=now),
            #db.Field('uuid',length=64,default=uuid.uuid4()),   # Layers like OpenStreetMap, Google, etc shouldn't sync
            db.Field('name'),
            db.Field('description',length=256),
            #db.Field('priority','integer'),    # System default priority is set in ol_layers_all.js. User priorities are set in WMC.
            db.Field('enabled','boolean',default=True))
gis_layer.name.requires=IS_NOT_EMPTY()
for layertype in gis_layer_types:
    resource='layer_'+layertype
    table=module+'_'+resource
    title_create=T('Add Layer')
    title_display=T('Layer Details')
    title_list=T('List Layers')
    title_update=T('Edit Layer')
    subtitle_create=T('Add New Layer')
    subtitle_list=T('Layers')
    label_list_button=T('List Layers')
    label_create_button=T('Add Layer')
    msg_record_created=T('Layer added')
    msg_record_modified=T('Layer updated')
    msg_record_deleted=T('Layer deleted')
    msg_list_empty=T('No Layers currently defined')
    # Create Type-specific Layer tables
    if layertype=="newlayertype":
        t=SQLTable(db,table,
            db.Field('subtype'),
            gis_layer)
        t.subtype.requires=IS_IN_SET(gis_layer_newlayertype_subtypes)
        db.define_table(table,t)
        db['%s' % table].represent=lambda table:shn_list_item(table,resource='layer_newlayertype',action='display',extra=str(table.enabled))
        if not len(db().select(db['%s' % table].ALL)):
            # Populate table
            for subtype in gis_layer_newlayertype_subtypes:
                db['%s' % table].insert(
                        name='New Layer Type '+subtype,
                        subtype=subtype
                    )
        # Customise CRUD strings if-desired
        msg_list_empty=T('No New Layer Type Layers currently defined')
        exec('crud_strings.%s=Storage(title_create=title_create, title_display=title_display, title_list=title_list, title_update=title_update, subtitle_create=subtitle_create, subtitle_list=subtitle_list, label_list_button=label_list_button, label_create_button=label_create_button, msg_record_created=msg_record_created, msg_record_modified=msg_record_modified, msg_record_deleted=msg_record_deleted, msg_list_empty=msg_list_empty)' % resource)

Module

New Layer Types & their Fields need adding to modules/s3gis.py

def show_map():

DeveloperGuidelines

Note: See TracWiki for help on using the wiki.