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.6.1.tar.gz
 * semantic_google_maps_0.6.1.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):

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
Instead of having users locate coordinates (which usually involves them entering an address), you may want to have them simply enter an address directly, and then find the coordinates automatically using geocoding. To do this, you can install and use the Google Geocoder extension, which can set a property of type Geographic Coordinates automatically.

If the address users are entering is split up into the standard fields (street address, city, etc.), a call to store the geocoded cooordinates of the address might look something like this: Has coordinates:: If you wanted to also display the location in a map on the page, you could also call something like:

Unfortunately, it appears that you cannot call #semantic_google_map and a semantic property declaration at the same time: if you want to both display a point and store it, you will have to use two separate calls.

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
 * 0.6 - February 12, 2009 - form input modified for user-friendliness; Google internationalization added to maps; language support added for Basque, Brazilian Portuguese, Swiss German and Volapük
 * 0.6.1 - March 4, 2009 - handling added for pages with more than one set of coordinates; language support added for Bosnian and Spanish

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.

Translating
Translation of Semantic Google Maps is done through Betawiki. The translation for this extension can be found here. To add language values or change existing ones, you should create an account on Betawiki, then request permission from the administrators to translate a certain language or languages on this page (this is a very simple process). Once you have permission for a given language, you can log in and add or edit whatever messages you want to in that language.

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.