DeveloperGuidelines

= GIS Module =

== !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

== !MapFish ==
The map window is wrapped in an Ext GUI based on !MapFish client:
 * https://trac.mapfish.org/trac/mapfish/wiki/HowToUseWidgets

== 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)
}}}

=== Controller ===
New Layer Types & their Fields need adding to 2 places in the Controller:[[BR]]
{{{controllers/gis.py}}}
{{{
def layer_newlayertype():
    "RESTlike CRUD controller"
    return shn_rest_controller(module,'layer_newlayertype')

def map_viewing_client():
newlayertype=Storage()
    layers_newlayertype=db(db.gis_layer_newlayertype.enabled==True).select(db.gis_layer_newlayertype.ALL)
    for layer in layers_newlayertype:
        for subtype in gis_layer_newlayertype_subtypes:
            if layer.subtype==subtype:
                newlayertype['%s' % subtype]=layer.name
    
    # Add the Layers to the Return
    output.update(dict(newlayertype=newlayertype))
}}}
Note that these functions are now deprecated as of [changeset:,52]:
 * {{{layer()}}}
 * {{{shn_gis_create_layer()}}}
 * {{{shn_gis_update_layer()}}}

=== View ===
{{{views/gis/ol_layers_all.js}}}
{{{
{{if newlayertype:}}
    {{include 'gis/ol_layers_newlayertype.js'}}
{{pass}}
}}}
{{{views/gis/ol_layers_newlayertype.js}}}
{{{
{{if newlayertype.Satellite:}}
    var newlayertypesat = new OpenLayers.Layer.NewLayerType( "{{=newlayertype.Satellite}}" , {type: NewLayerType.Aerial, 'sphericalMercator': true } );
    map.addLayer(newlayertypesat);
{{pass}}
}}}
If loading custom JS files when the new Layer is active:[[BR]]
{{{views/gis/ol_js_loaders.html}}}
{{{
{{if virtualearth:}}
<script type="text/javascript" src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.1"></script>
{{pass}}
}}}
Note that these files are now deprecated as of [changeset:,52]:
 * {{{views/gis/form_*.html}}}
 * {{{views/gis/create_layer.html}}}:
 * {{{views/gis/list_create_layer.html}}}:
 * {{{views/gis/update_layer.html}}}:
 * {{{static/scripts/gis_layers.js}}}
----
DeveloperGuidelines