Google Map View¶

Last Updated: August 10, 2015

class tethys_sdk.gizmos.GoogleMapView(height, width, maps_api_key='', reference_kml_action='', drawing_types_enabled=[], initial_drawing_mode='', output_format='GEOJSON', input_overlays=[None], attributes={}, classes='')¶

The Google Map View is powered by Google Maps 3. It has the drawing library enabled to allow geospatial user input. An optional background dataset can be specified for reference, but only the shapes drawn by the user are returned (see Retrieving Shapes reference section).

Shapes that are drawn on the map by users can be retrieved from the map in two ways. A hidden text field named 'geometry' is updated every time the map is changed. The text in the text field is a string representation of JSON. The geometry can be formatted as either GeoJSON or Well Known Text. This can be configured by setting the output_format parameter. If the Google Map View is embedded in a form, the geometry that is drawn on the map will automatically be submitted with the rest of the form via the hidden text field.

Alternatively, the data can be extracted directly using the JavaScript API (see below).

height¶

Height of map container in normal css units

Type: string, required

width¶

Width of map container in normal css units

Type: string, required

maps_api_key¶

The Google Maps API key. If the API key is provided in the settings.py via the TETHYS_GIZMOS_GOOGLE_MAPS_API_KEY option, this parameter is not required.

Type: string, required

reference_kml_action¶

The action that returns the background kml datasets. These datasets are used for reference only.

Type: url string

drawing_types_enabled¶

A list of the types of geometries the user will be allowed to draw (POLYGONS, POINTS, POLYLINES).

Type: list of strings

initial_drawing_mode¶

A string representing the drawing mode that will be enabled by default. Valid modes are: 'POLYGONS', 'POINTS', 'POLYLINES'. The mode used must be one of the drawing_types_enabled that the user is allowed to draw.

Type: string

output_format¶

A string specifying the format of the string that is output by the editable map tool. Valid values are 'GEOJSON' for GeoJSON format or 'WKT' for Well Known Text Format.

Type: string

input_overlays¶

A JavaScript-equivalent Python data structure representing GeoJSON or WktJSON containing the geometry and attributes to be added to the map as overlays (see example below). Only points, lines and polygons are supported.

Type: PySON

attributes¶

A dictionary representing additional HTML attributes to add to the primary element (e.g. {"onclick": "run_me();"}).

Type: dict

classes¶

Additional classes to add to the primary HTML element (e.g. "example-class another-class").

Type: str

Controller Default Example

from tethys_sdk.gizmos import GoogleMapView

google_map_view_options = GoogleMapView(height='600px',
                                        width='100%',
                                        reference_kml_action=reverse('gizmos:get_kml'),
                                        drawing_types_enabled=['POLYGONS', 'POINTS', 'POLYLINES'],
                                        initial_drawing_mode='POINTS',
                                        output_format='WKT')

context = {
            'google_map_view_options': google_map_view_options,
          }

Controller GeoJSON Example

geo_json = {'type':'WKTGeometryCollection',
    'geometries':[
                  {'type':'Point',
                   'wkt':'POINT(-111.5123462677002 40.629197012613545)',
                   'properties':{'id':1,'value':1}
                   },
                  {'type':'Polygon',
                   'wkt':'POLYGON((-111.50153160095215 40.63193284946615, -111.50101661682129 40.617210120505035, -111.48625373840332 40.623594711231775, -111.49123191833496 40.63193284946615, -111.50153160095215 40.63193284946615))',
                   'properties':{'id':2,'value':2}
                   },
                  {'type':'PolyLine',#
                   'wkt':'POLYLINE(-111.49123191833496 40.65003865742191, -111.49088859558105 40.635319920747456, -111.48127555847168 40.64912697157757, -111.48024559020996 40.634668574229735)',
                   'properties':{'id':3,'value':3}
                   }
                  ]
    }

google_map_view_options = GoogleMapView(height='700px',
                                        width='100%',
                                        maps_api_key='S0mEaPIk3y',
                                        drawing_types_enabled=['POLYGONS', 'POINTS', 'POLYLINES'],
                                        initial_drawing_mode='POINTS',
                                        input_overlays=geo_json)

context = {
            'google_map_view_options': google_map_view_options,
          }

Controller WKT Example

wkt_json = {"type":"GeometryCollection",
    "geometries":[
                  {"type":"Point",
                   "coordinates":[40.629197012613545,-111.5123462677002],
                   "properties":{"id":1,"value":1}},
                  {"type":"Polygon",
                   "coordinates":[[40.63193284946615,-111.50153160095215],[40.617210120505035,-111.50101661682129],[40.623594711231775,-111.48625373840332],[40.63193284946615,-111.49123191833496]],
                   "properties":{"id":2,"value":2}},
                  {"type":"LineString",
                   "coordinates":[[40.65003865742191,-111.49123191833496],[40.635319920747456,-111.49088859558105],[40.64912697157757,-111.48127555847168],[40.634668574229735,-111.48024559020996]],
                   "properties":{"id":3,"value":3}}
                  ]
    }

google_map_view_options = GoogleMapView(height='700px',
                                        width='100%',
                                        maps_api_key='S0mEaPIk3y',
                                        drawing_types_enabled=['POLYGONS', 'POINTS', 'POLYLINES'],
                                        initial_drawing_mode='POINTS',
                                        input_overlays=wkt_json)

context = {
            'google_map_view_options': google_map_view_options,
          }

Template Example

{% load tethys_gizmos %}

{% gizmo google_map_view_options %}

JavaScript API¶

For advanced features, the JavaScript API can be used to interact with the editable map. If you need capabilities beyond the scope of this API, we recommend using the Google Maps version 3 API to create your own map.

TETHYS_GOOGLE_MAP_VIEW.getMap()¶

This method returns the Google Map object for direct manipulation through JavaScript.

TETHYS_GOOGLE_MAP_VIEW.getGeoJson()¶

This method returns the GeoJSON object representing all of the overlays on the map.

TETHYS_GOOGLE_MAP_VIEW.getGeoJsonString()¶

This method returns a stringified GeoJSON object representing all of the overlays on the map.

TETHYS_GOOGLE_MAP_VIEW.getWktJson()¶

This method returns a Well Known Text JSON object representing all of the overlays on the map.

TETHYS_GOOGLE_MAP_VIEW.getWktJsonString()¶

This method returns a stringified Well Known Text JSON object representing all of the overlays on the map.

TETHYS_GOOGLE_MAP_VIEW.swapKmlService(kml_service)¶

Use this method to swap out the current reference kml layers for new ones.

kml_service (string) = URL endpoint that returns a JSON object with a property called 'kml_link' that is an array of publicly accessible URLs to kml or kmz documents

TETHYS_GOOGLE_MAP_VIEW.swapOverlayService(overlay_service, clear_overlays)¶

Use this method to add new overlays to the map dynamically without reloading the page.

overlay_service (string) = URL endpoint that returns a JSON object with a property called 'overlay_json' that has a value of a WKT or GeoJSON object in the same format as is used for input_overlays
clear_overlays (boolean) = if true, will clear all overlays from the map prior to adding the new overlays. Otherwise all overlays will be retained.