wiki:DeveloperGuidelines/GIS

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

--

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,
              add_feature = False,
              add_feature_active = False,
              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 add_feature: Whether to include a DrawFeature control to allow adding a marker to the map
    @param add_feature_active: Whether the DrawFeature control should be active by default
    @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, which can be from a simple query or a Join. Extra fields can be added for 'marker' or 'shape' (with optional 'color' & 'size') & 'popup_label'
         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).
         }]
    @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).
         }]
    @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
    """

Variable Markers

Example:

query = (db.gis_location.deleted == False)
query = query & (db.gis_location.id == db["%s_%s" % (module, resource)].location_id)
locations = db(query).select(db.gis_location.id, db.gis_location.uuid, db.gis_location.name, db.gis_location.wkt, db.gis_location.lat, db.gis_location.lon)
for i in range(0, len(locations)):
    locations[i].gis_location.shape = "circle"
    locations[i].gis_location.size = locations[i][db["%s_%s" % (module, resource)].MyIntegerField]

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

Debugging advice: http://docs.openlayers.org/help/minimize.html

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():

BluePrintGeographicInformationSystems

UserGuidelinesGIS

DeveloperGuidelines

Note: See TracWiki for help on using the wiki.