Extension:Semantic Google Maps

Semantic Google Maps is an extension that provides the ability to view and edit coordinate data stored through the Semantic MediaWiki extension, using Google Maps.

Overview
Semantic Google Maps provides a map interface to the Semantic MediaWiki Geographic coordinate property type, through the following features:

1. Display of coordinates. A parser function, '#semantic_google_map', that displays a Google Map that shows a single point, defined as a set of geographic coordinates.

2. Aggregation of coordinates. An output format for a Semantic MediaWiki query, named 'googlemap', that allows a set of pages that have coordinate data to be displayed together on a Google Map.

3. Insertion of coordinates. A custom Semantic Forms input type, also named 'googlemap'. This input type displays a map with a geocoder in a form to make the insertion of coordinates easy for users.

Download and installation
You can download the Semantic Google Maps code in either one of these two compressed files:


 * semantic_google_maps_0.5.tar.gz
 * semantic_google_maps_0.5.zip

You can also download the code directly via SVN from the MediaWiki source code repository, at http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/SemanticGoogleMaps/. From a command line, you can call the following:

svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/SemanticGoogleMaps/

You must also obtain a Google Maps API key for this wiki, if you don't already have one; a key can easily be obtained here. Note that use of the Google Maps API is free only if your site is accessible to the public; otherwise it costs money - read the Google Maps terms of service for further details.

Once you have downloaded the code, place the 'SemanticGoogleMaps' directory within your MediaWiki 'extensions' directory. Then add the following code to your LocalSettings.php file after the line that installs Semantic MediaWiki (and after the line that installs Semantic Forms, if you use it):

Important for the API-Key
When generating the API-Key it's better to specifie the subdirectory the pages are displayed in. Use http://domain.tld/wiki instead of just http://domain.tld/. Fact is that the alternative without the subdirectory may cause trouble and some users might not see pages with maps in it.

Display a single point
To include a map from within a template:

If a normal page holds:

Template:Location could contain something like:

Has coordinates::

Variables that the semantic_google_map function takes, and their default values, are:

$coordinates='1,1', $zoom = '14', $type = 'G_NORMAL_MAP', $controls = 'GSmallMapControl', $class = 'pmap', $width = '200', $height = '200', $style = ''

To make a large map for a page, for instance, your template could hold the following:

Geocoding addresses
You may not want to require users to enter a set of coordinates, but address instead. In that case, you could install and use the Google Geocoder extension to set the property of type Geographic Coordinates automatically. Has coordinates::

If they are already entering an address for that same location as template parameters, these parameters can be reused to avoid duplicate work for users. The code in the template could then look something like this: Has coordinates:: If you wanted to display the location in a map on the page, you could also call something like:

Display multiple points
Note: this functionality requires Semantic MediaWiki version 1.2g or higher to work.

You can set a Semantic MediaWiki #ask query to display its results in a Google Map, by setting "format=googlemap". One of the properties queried and displayed must be of type 'Geographic coordinate' for this query to work; this property is what will determine the location of each point on the map. Clicking on each point will display a label holding the name of the page, along with any other queried information; clicking on the page name will bring the user to that page. The zoom level of the map will be the closest one possible that shows all the points.

If you use this format, you can also add seven additional parameters to the query:
 * - the width of the map, in pixels; defaults to 400
 * - the height of the map, in pixels; defaults to 400
 * - the coordinates at the center of the map; defaults to the center of the current set of points
 * - the zoom level of the map; should be an integer greater than equal to 1 (a value of 1 shows the whole world, and for most areas, the maximum zoom is around 18). Defaults to whatever the closest zoom is that shows all the points selected
 * - can be either G_NORMAL_MAP, G_SATELLITE_MAP or G_HYBRID_MAP; defaults to G_NORMAL_MAP
 * - the map control class displayed to let the user zoom and navigate; defaults to GLargeMapControl
 * - the name of a local image file to use, in place of the default icon, to mark points

Here is an example of an #ask query that uses the 'googlemap' format:

Display multiple sets of points
If you're using MediaWiki version 1.13 or higher, you can display multiple sets of points, each with their own icon, within a Google Map, by using Semantic Google Maps in conjunction with the Semantic Compound Queries extension (if it's an older version of MediaWiki, you can still display mutliple sets of points, but they will all have the same icon). Once you have downloaded and installed that extension, you can call a compound query in the following way:

In this case, 'Fork.png', 'Wine glass.png' and 'Beer mug.png' must be the names of image files that have been uploaded to the wiki. For more explanation of the syntax of #compound_query, see the Semantic Compound Queries extension page.

Google Maps form input
Use this code in a Semantic Forms form, to include a geocoder in that form:

Coordinates:

You can add six additional parameters:
 * - defaults to 200
 * - defaults to 200
 * - only has an effect if no value exists for the field; defaults to 50° N, 5° W
 * - only has an effect if no value exists for the field; defaults to 1
 * - defaults to G_NORMAL_MAP
 * - defaults to GSmallMapControl

Version
The version history for this extension is:
 * 0.1 - September 2, 2007 - initial version
 * 0.2 - September 5, 2007 - Semantic Forms input changed to use SF's input-type hook
 * 0.3 - July 7, 2008 - overhaul; existing parser function and input type renamed, and #ask query format created
 * 0.3.1 - July 22, 2008 - changed setting of map size to use API instead of CSS style; improved padding around coordinates in query map; language support added for Dutch, French, Galician, Norwegian Bokmål, Slovak and Swedish
 * 0.3.2 - July 30, 2008 - fixed error in setting zoom level for query map; language support added for Arabic and German
 * 0.3.3 - August 13, 2008 - fixed handling of pages with quotes in their titles; Javascript fix for skins with unconventional form placement; language support added for Esperanto and Occitan
 * 0.3.4 - August 21, 2008 - added support for SMW 1.2.2
 * 0.4 - October 3, 2008 - added 'width', 'height', 'center', 'zoom', 'map type' and 'map control' parameters for both #ask queries and form inputs; changed default map control to GLargeMapControl; set marker in form input to no longer display if no value exists for the field; added support for SMW 1.3; language support added for Afrikaans, Egyptian Arabic, Interlingua and Ripuarian
 * 0.4.1 - October 5, 2008 - fixed PHP bug; improved code layout
 * 0.4.2 - October 30, 2008 - added support for 'icon' and, eventually, a 'legend label' parameter as well; fixed handling of multiple fields per point; language support added for Portuguese
 * 0.5 - January 1, 2009 - moved SGMUtils class into new file, SGM_Utils.php; class autoloading added; language support added for Breton, Simplified Chinese, Traditional Chinese, Hebrew, Japanese, Khmer, Luxembourgish, Norwegian Nynorsk, Polish, Lower Sorbian, Upper Sorbian and Tagalog

Bugs and feature requests
If you have bug reports or requests, please either send them to Yaron Koren, at yaron57 -at- gmail.com, or add them to the Talk page.

Contributing patches to the project
If you found some bug and fixed it, please create a patch by going to the "SemanticGoogleMaps" directory, and typing:

svn diff >descriptivename.patch

Then either send this patch, with a description, to Yaron Koren, or add it on the Talk page.

Sites that use this extension

 * EPSA - European Public Sector Award 2007
 * Tech Presentations
 * Verwaltungskooperation - Cooperation in Public Administration
 * Venicewiki.org The People's Guide to Venice
 * Web Community Wiki
 * hackerspaces - Directory of Hackerspaces around the world
 * Placeography-History, tours of places past and present

You can see an alternate listing of sites that use Semantic Google Maps on the Semantic MediaWiki Community Wiki, an SMW-based wiki that contains additional information on each wiki.