[[TOC]]
= 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:
 * http://trac.openlayers.org/wiki/Documentation#BeforeGettingStarted--TheTechnologiesBehindOpenLayers
 * http://trac.openlayers.org/wiki/NewToOpenLayers

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 [http://geoext.org GeoExt] (formerly [https://trac.mapfish.org/trac/mapfish/wiki/HowToUseWidgets MapFish client])

=== How to debug WMS ===
* [https://addons.mozilla.org/en-US/firefox/addon/91406 WMS Inspector] - Firefox add-on

=== How to add a new Layer type ===
Assuming that !OpenLayers supports the layertype:
==== Model ====
{{{models/03_gis.py}}}
{{{
gis_layer_types = ["newlayertype", "..."]
gis_layer_newlayertype_subtypes = ["Subtype"]
# Base table from which the rest inherit
gis_layer = db.Table(db, "gis_layer", timestamp,
            #uuidstamp, # Layers like OpenStreetMap, Google, etc shouldn't sync
            Field("name", notnull=True, label=T("Name"), requires=IS_NOT_EMPTY(), comment=SPAN("*", _class="req")),
            Field("description", label=T("Description")),
            #Field("priority", "integer", label=T("Priority")),    # System default priority is set in ol_layers_all.js. User priorities are set in WMC.
            Field("enabled", "boolean", default=True, label=T("Available in Viewer?")))
for layertype in gis_layer_types:
    resource = "layer_" + layertype
    tablename = "%s_%s" % (module, resource)
    # Create Type-specific Layer tables
    if layertype == "newlayertype":
        t = db.Table(db, table,
            gis_layer,
            Field("subtype", label=T("Sub-type"), requires = IS_IN_SET(gis_layer_newlayertype_subtypes, zero=None)),
            Field("layer_specific_option"))
        table = db.define_table(tablename, t, migrate=migrate)
}}}

==== Controller ====
{{{controllers/gis.py}}}
{{{
def layer_newlayertype():
    """ RESTful CRUD controller """
    if deployment_settings.get_security_map() and not shn_has_role("MapAdmin"):
        unauthorised()

    resource = request.function
    tablename = module + "_" + resource
    table = db[tablename]

    # Model options
    table.url.comment = SPAN("*", _class="req")

    # CRUD Strings
    type = "New Layer Type"
    LAYERS = T(TYPE_LAYERS_FMT % type)
    ADD_NEW_LAYER = T(ADD_NEW_TYPE_LAYER_FMT % type)
    EDIT_LAYER = T(EDIT_TYPE_LAYER_FMT % type)
    LIST_LAYERS = T(LIST_TYPE_LAYERS_FMT % type)
    NO_LAYERS = T(NO_TYPE_LAYERS_FMT % type)
    s3.crud_strings[tablename] = Storage(
        title_create=ADD_LAYER,
        title_display=LAYER_DETAILS,
        title_list=LAYERS,
        title_update=EDIT_LAYER,
        title_search=SEARCH_LAYERS,
        subtitle_create=ADD_NEW_LAYER,
        subtitle_list=LIST_LAYERS,
        label_list_button=LIST_LAYERS,
        label_create_button=ADD_LAYER,
        label_delete_button = DELETE_LAYER,
        msg_record_created=LAYER_ADDED,
        msg_record_modified=LAYER_UPDATED,
        msg_record_deleted=LAYER_DELETED,
        msg_list_empty=NO_LAYERS)

    # Post-processor
    def user_postp(jr, output):
        shn_action_buttons(jr)
        return output
    response.s3.postp = user_postp

    output = shn_rest_controller(module, resource)

    if not "gis" in response.view:
        response.view = "gis/" + response.view

    return output
}}}

==== Module ====
{{{modules/s3gis.py}}}
OpenLayers code templates
{{{
def show_map():
}}}

----
[wiki:BluePrintGeographicInformationSystems]

[wiki:UserGuidelinesGIS]

DeveloperGuidelines