Extension:Semantic Google Maps

**MediaWiki extensions manual**
Semantic Google Maps; Release status: beta
Implementation	Parser function
Description	Allows users to add Google Maps to wiki pages based upon structured data.
Author(s)	Robert Buzink and Yaron Koren
Latest version	0.4.1 (October 2008)
MediaWiki	1.9.* or greater
Licence	GNU General Public License (any version)
Download	See here

Semantic Google Maps is an extension that provides Google Maps functionality to wikis that use the Semantic MediaWiki extension.

Overview

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

File:Ss parsermap.jpg

Semantic template map

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.

File:Ss inputmap.jpg

Form input 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:

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):

$wgGoogleMapsKey = "...enter your Google Maps API key here...";
require_once( "$IP/extensions/SemanticGoogleMaps/SemanticGoogleMaps.php" );

Dependencies

Usage

Display a single point

To include a map from within a template:

If a normal page holds:

{{Location
|Coordinates=50.85137811° N, 5.690781176° E
}}

Template:Location could contain something like:

[[Has coordinates::{{{Coordinates|}}}|]]{{#if:{{{Coordinates|}}}|{{#semantic_google_map:{{{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:

{{#semantic_google_map:{{{Coordinates}}}|8|G_NORMAL_MAP|GLargeMapControl|pmap|800|600}}

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::{{#geocode:Times Square, New York, NY}}]]

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::{{#geocode:{{{Street address}}}, {{{City}}}, {{{State}}}, {{{Country}}}}}]]

If you wanted to display the location in a map on the page, you could also call something like:

{{#semantic_google_map:{{#geocode:{{{Street address}}}, {{{City}}}, {{{State}}}, {{{Country}}}}}}}

To find the distance between two addresses, we can use the #geocode function to get the co-ordinates and then use the Geo_distance function.

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 six additional parameters to the query:

width= - the width of the map, in pixels; defaults to 400
height= - the height of the map, in pixels; defaults to 400
center= - the coordinates at the center of the map; defaults to the center of the current set of points
zoom= - 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
map type= - can be either G_NORMAL_MAP, G_SATELLITE_MAP or G_HYBRID_MAP; defaults to G_NORMAL_MAP
map control= - the map control class displayed to let the user zoom and navigate; defaults to GLargeMapControl

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

{{#ask:[[Category:Locations]][[Has coordinates::+]]|?Has coordinates|format=googlemap|width=800|height=600}}

Google Maps form input

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

'''Coordinates:''' {{{field|Coordinates|input type=googlemap}}}

As with the #ask query, you can add six additional parameters:

width= - defaults to 200
height= - defaults to 200
center= - only has an effect if no value exists for the field; defaults to 50° N, 5° W
zoom= - only has an effect if no value exists for the field; defaults to 1
map type= - defaults to G_NORMAL_MAP
map control= - 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

Contributing to the project

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
Placeography - Histories and stories about buildings and land
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

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