The map module allows you to browse and search for places and view them on a map. Places may be grouped by feed groups, category, and subcategory.
Each feed group corresponds to a base map, characterized by center location and background appearance. For organizations with multiple campuses, feed groups are a logical way to split up maps by campus.
Groups are configured in the SITE_DIR/config/map/feedgroups.ini file. There must be at least one entry that looks like the following:
[groupID]
title = "Title of my map"
subtitle = "Subtitle of my map"
center = "42.3584308,-71.0597732"
DEFAULT_ZOOM_LEVEL = 10
The base map used by default is Google Maps on compliant/tablet devices, and Google Static Maps on basic/touch devices. Kurogo also supports ArcGIS JavaScript maps on compliant/tablet devices, and ArcGIS static maps and WMS on basic devices. See the Advanced Configuration section for details.
Each data feed is represented as a category that a user may browse by from the home screen or within a campus.
For people who do not have any existing mapping infrastructure, we generally recommend creating feeds using Google Earth. Google Earth allows you to add pins to the map and export the result as a KML file.
To add feeds to a feed group, create an entry for it in the file SITE_DIR/config/map/feeds-GROUP.ini (where GROUP is the id of the group from feedgroups.ini). Each entry should look like the following:
[index]
TITLE = "Fun Places in Washington"
SUBTITLE = "These are places I like to check out on vacation"
BASE_URL = DATA_DIR"/washington.kml"
SEARCHABLE = 1
Note: if you use a feed in .kmz instead of .kml format, you must also specify the following in the entry:
RETRIEVER_CLASS = "KMZDataRetriever"
Kurogo also supports data from the ArcGIS REST API and the ESRI Shapefile format. If you use any of these formats, or are looking to change other aspects of the data feeds and base maps, see the Advanced Configuration section.
The following options appear by default in SITE_DIR/config/map/module.ini:
BOOKMARKS_ENABLED = 1
MAP_SHOWS_USER_LOCATION = 1
SHOW_DISTANCES = 1
DISTANCE_MEASUREMENT_UNITS = "Imperial"
In addition to title, subtitle, and center, each group may also specify the following:
Example configuration:
[honolulu]
title = "Honolulu Campus"
subtitle = "Our new satellite office that nobody knows about"
center = "21.3069444,-157.8583333"
JS_MAP_CLASS = "ArcGISJSMap"
DYNAMIC_MAP_BASE_URL = "http://myhost/MapServer"
STATIC_MAP_CLASS = ArcGISStaticMap
STATIC_MAP_BASE_URL = "http://myhost/MapServer"
NEARBY_THRESHOLD = 1609
NEARBY_ITEMS = 12
In addition to TITLE, SUBTITLE, and BASE_URL, each feed may also specify the following:
Some config values set for individual feeds can override the values in the associated feed group. For example, the “honolulu” feed group may use a nearby threshold of 1000 meters when searching, but we have a dense feed in where we only want items within 200 meters. In this case set NEARBY_THRESHOLD can be set on the individual feed. The overridable config parameters are DEFAULT_ZOOM_LEVEL, JS_MAP_CLASS, DYNAMIC_MAP_BASE_URL, STATIC_MAP_CLASS, STATIC_MAP_BASE_URL, NEARBY_THRESHOLD, and NEARBY_ITEMS.
KML is the default feed type in the map module. In other words, if the feed config does not specify MODEL_CLASS or RETRIEVER_CLASS, Kurogo will assume the feed is in KML format.
Kurogo only supports a subset of KML tags. Kurogo will ignore all unsupported tags except <MultiGeometry>, <Model>, <gx:Track>, <gx:Multitrack> – these tags will cause Kurogo to throw exceptions. Also, several tags are parsed but never shown in the UI.
The following tags are parsed and affect the UI:
<Folder>
<name>
<description>
<StyleMap>
<Pair>
<key>
<styleURL>
<Style>
<iconStyle>
<href>
<w>
<h>
<balloonStyle>
<bgColor>
<textColor>
<lineStyle>
<color>
<weight>
<polyStyle>
<fill>
<color>
<Placemark>
<address>
<name>
<description>
<Snippet>
<Point>
<coordinates>
<Polygon>
<outerBoundaryIs>
<innerBoundaryIs>
<LineString>
<coordinates>
<LinearRing>
The following tags are parsed but currently have no effect on the UI:
<Document>
<name>
<description>
<scale> (under iconStyle)
See Google’s KML documentation for more information.
To use ArcGIS Server, specify the following in feeds-<group>.ini:
MODEL_CLASS = "ArcGISDataModel"
If the service has multiple layers, Kurogo only uses one layer at a time. You may specify different layers for different feeds by specifying
ARCGIS_LAYER_ID = <number>
where <number> is the numeric ID of the layer. Sublayers are not currently supported.
See Esri’s ArcGIS Server documentation for more information.
To use shapefiles, specify the following in feeds-<group>.ini:
MODEL_CLASS = "ShapefileDataModel"
Shapefiles located across the network must be in a zip folder containing no directories (i.e. the contents are all .shp, .dbf, .shx, and .prj files). Note that to use zipped shapefiles, the ZipArchive extension must be enabled in PHP.
Larger shapefiles may be unzipped and stored locally in a subdirectory of DATA_DIR. In this case, the BASE_URL must be specified without the extension, e.g. the shapefile consisting of DATA_DIR”/myshapefile.shp” and DATA_DIR”/myshapefile.dbf” must be specified as:
BASE_URL = DATA_DIR"/myshapefile"
See Wikipedia’s entry on the Shapefile specification for more information.
Kurogo selects the base map following the configuration and these default rules:
If both JS_MAP_CLASS and STATIC_MAP_CLASS are left unspecified, Kurogo by default will select Google Static Maps for basic/touch devices and Google Maps for compliant/tablet devices. If both are specified, JS_MAP_CLASS will be used for compliant/tablet and STATIC_MAP_CLASS for touch/basic.
If only STATIC_MAP_CLASS is specified, both compliant/tablet and basic/touch devices will use the base map specified by STATIC_MAP_CLASS. If only JS_MAP_CLASS is specified, Google Static Maps will be chosen for basic/touch devices.
Acceptable options for JS_MAP_CLASS are as follows.
To explictly use Google Maps (rather than rely on it showing up by default), enter the configuration:
JS_MAP_CLASS = "GoogleJSMap"
See Google’s Maps documentation for more information.
To use tiles from an ArcGIS tile server, enter the configuration:
JS_MAP_CLASS = "ArcGISJSMap"
DYNAMIC_MAP_BASE_URL = "http://..."
Additional dynamic layers from an ArcGIS Dynamic Service Map may be added on top of the base map by specifying DYNAMIC_MAP_BASE_URL as an array, e.g.
DYNAMIC_MAP_BASE_URL[] = "http://my.tiled.service/MapServer"
DYNAMIC_MAP_BASE_URL[] = "http://my.dynamic.service/MapServer"
The first element of DYNAMIC_MAP_BASE_URL must be a tiled service. There must be one and only one tiled service.
See Esri’s ArcGIS JavaScript documentation for more information.
Acceptable options for STATIC_MAP_CLASS are as follows.
To explicitly use Google Static Maps (rather than rely on it being the default), enter the configuration:
STATIC_MAP_CLASS = "GoogleStaticMap"
Google Static Maps does not currently have support for polygon overlays.
See Google’s Static Maps documentation for more information
To use images from a WMS service, enter the configuration:
STATIC_MAP_CLASS = "WMSStaticMap"
STATIC_MAP_BASE_URL = "http://..."
Note that it is not possible to add overlays to WMS maps.
See the Open Geospatial Consortium’s WMS documentation for more information.
To use exported images from an ArcGIS server, enter the configuration:
STATIC_MAP_CLASS = "ArcGISStaticMap"
STATIC_MAP_BASE_URL = "http://..."
Note that it is not possible to add overlays to an exported image.
See Esri’s export API documentation for more information.
Map search is configured in module.ini. If this is not configured, Kurogo’s default behavior is to use the class MapSearch, which walks through all feeds in the selected feed group.
Optionally, the following parameters may be configured:
MAP_SEARCH_CLASS = "MyMapSearchSubclass"
MAP_EXTERNAL_SEARCH_CLASS = "GoogleMapSearch"
Searches initiated within the map module use the MAP_SEARCH_CLASS, which defaults to “MapSearch”. Searches initiated by modules other than the map module may use a different search class if the optional config parameter MAP_EXTERNAL_SEARCH_CLASS is configured to a different class.
The included class GoogleMapSearch uses uses either Google Places or the Google Geocoding service. Geocoding is selected by default. To use Places (assuming you have an API key from Google), add the following configurations to SITE_DIR/config/maps.ini:
[maps]
USE_GOOGLE_PLACES = 1
GOOGLE_PLACES_API_KEY = AbCDeFGH123789zzzzzzzzzzzzzzzzzzzxwycbA
Users of Google Maps and related products (which includes the majority of Kurogo installations) need to be aware that usage restrictions apply on all these products.
The Google Maps/Earth API terms of service is here.
Sites with heavy traffic should be aware of recent changes to usage limits on embedded Google Maps.