Islandora module that provides the ability to add a map to an object's display. You can see it in action here.
This module can use geographic coordinates and place names in MODS (or other) elements to populate a Google or OpenStreetMaps map that is then appended to the object's display or displayed in a block.
|API key||not required||required|
|multivalued coordinates||not supported (first coordinate/place name only)||supported|
|place names||supported||not supported *|
|collection maps||not supported||supported|
* You can write a custom place name lookup to make use of the hooks but this is not provided currently.
This module exposes two hooks to allow developers to write their own function to extract information and return coordinates for display on the map and to parse coordinates provided in various formats to decimal format for display.
See Configuration for instructions.
Install as usual, see this for further information.
Admin settings are available at
You can select which to use with the Choose map type drop down.
- Your API key (required).
- Disabling mouse wheel from causing map zoom.
- Additional enhanced options described below.
The Embed API only displays the first coordinate found.
The OpenStreetMap allows you to choose between 3 tile providers (OpenStreetMap, MapBox and Thunderforest)
Note: The OpenStreetMap tile provider is for testing and very small sites. Read the OpenStreetMap Tile Usage Policy for more information.
The other two providers will require you to register to get an API key.
The OpenStreetMap maps also provide additional enhanced options described below.
- Display all coordinates found and show multiple points on a map.
- Display a map in a block.
- Disable the map embed in the page. Useful if using the above map block.
- Collection maps.
Common configuration options
Common configuration options are:
- A delimiter to split multiple coordinates on.
- the XPath expressions to the MODS elements where your map data is stored
- the map's height, width, default zoom level, and whether or not the map is collapsed or expanded by default, and
- option to clean up the data before it is passed to the map provider.
- option to display maps for compounds (in addition to their first child).
Once you enable the module, any object whose MODS file contains coordinates in the expected element will have a Google map appended to its display.
There is also the Coordinates Solr field option if you index your object's coordinates. If you fill this in, then a Solr query will be done to retrieve the collections coordinates instead of parsing each collection member's MODS record.
Extract from MODS using XPath
Site admins can configure multiple MODS elements in a preferred order by entering XPath expressions in the admin setting's "XPath expressions to MODS elements containing map data" field. Data from the first element to match one of the configured XPath expressions is used to render the map. The module provide sensible default values that prefer
Using geographic coordinates to create maps
By default, the MODS element this module expects geographic coordintates to be in is
<subject><cartographics><coordinates>. Geographic coordinates must be in "decimal degrees" format with latitude listed first, then longitude.
Google Maps is fairly forgiving of the specific formatting of the values when using the Embed API. All of these work:
+49.05444,-121.985 +49.05444 -121.985 49.05444 N 121.985 W 49.05444N121.985w
If your data is not in that format, you can create a small module using the API to transform your data.
Semicolons separating the latitude and longitude are not allowed, resulting in a map with no points on it:
There is an admin option to "Attempt to clean up map data".
If this is enabled (which it is by default), a semicolon in the data will be replaced with a comma before it is passed to Google Maps.
This option can be enabled, but this cleaning occurs before splitting multiple coordinates. So if semi-colons are used to delineate multiple coordinates this can cause problems.
Then splitting on
; would fail.
Alternatively you can use multiple
<cartographic><coordinates></coordinates></cartographic> elements and
place one coordinate in each.
Using place names and other non-coordinate data to create maps
Embed API Only
If you configure this module to use MODS elements that do not contain coordinate data, such as
<subject><geographic>, Google Maps will attempt to generate a map based on whatever data it finds in the configured element. However, the results of using non-cartographic coordinates are not always predictable. For example, the following two values for
<subject><geographic> produce accurate maps, presumably because they are unambiguous:
Dublin, Ireland Dublin, Ohio
but a value of just
Dublin results in a map showing the Irish city. Another example that illustrates Google Maps' behavior when it is given ambiguous data is a
<subject><geographic> value of
City of Light, which results in a map showing a church by that name in the US Northwest, not Paris, France, probably because when I wrote this I was closer to that location than to Paris. From Europe, for example, you get a completely different location for a
<subject><geographic> value of
City of Light. Also, if Google Maps cannot associate the data with a geographic location (predictable from a user's perspective or not), it produces a map showing a large portion of the world (depending on the default zoom level in effect) with no points on it.
The XPath expressions used to retrieve map data are executed in the order they are listed in the admin settings. So, for best results, listing the expressions in decreasing likelihood they will contain reliable and unambiguous data is the best strategy. The defaults values do this.
Collection maps provide a single map with markers for all items directly in the collection (does not include sub-directories).
If you have checked the "Enable collection level maps?" option, you can then enable a map for each collection within the collection's Manage subtabs.
You can also cache collection points for anonymous users, this can significantly improve performance on maps with large numbers of points.
Check the "Display map of resources in this collection" checkbox and click Save. You can also un-check and Save to disable a collection's map.
Implementations of this hook should return an array of the format.
array( 'my_module_implementation' => array( 'function_name' => 'islandora_test_parse_coordinates', 'file' => drupal_get_path('module', 'islandora_simple_map') . 'includes/test_functions.inc', 'weight' => 100, ), );
function_nameis a function that accepts an array of coordinates of various formats and returns an associative array of coordinates that it could parse where the key is the original value and value is the parsed value.
fileis the file to include to access this function. (Optional)
weightis to order the hooks. Default is 100. (Optional)
- Add a Drupal permission to "View Islandora Simple Map maps".
Development and feedback
Pull requests are welcome, as are use cases and suggestions. For example, if your coordinate data results in maps with no points on them, please suggest some ways that the data could be normalized (and don't forget to include some sample data).