Extension:Semantic Maps

Description
Semantic Maps is an extension that adds semantic capabilities to the Maps extension, and therefore provides the ability to add, view and edit coordinate data stored through the Semantic MediaWiki extension.

Due to it's unique structure, it allows you to use multiple mapping services to display your coordinates. These include Google Maps, Yahoo! Maps, OpenLayers, and also allow you to display maps with Google Earth, OpenStreetMaps, Bing maps and others. Modifying the mapping service of a map is as easy as changing a single parameter! Examples of how to use Semantic Maps can be found here.

Both Semantic Maps and Maps are based on Semantic Google Maps and Semantic Layers, and are meant to replace these extensions.

For this extension to work, you need to have both Semantic MediaWiki and Maps installed.

Functionality overview
Semantic Maps and Map provide a map interface to the Semantic MediaWiki Geographic coordinate property type, through the following features:


 * 1) Display of coordinates. See the usage of Maps for more info.
 * 2) Aggregation of coordinates. Each mapping service has it's own special output format, that can be used in Semantic MediaWiki queries, allowing a set of coordinate data stored on multiple pages to be displayed together on a single map.
 * 3) Insertion of coordinates. Semantic Maps provides custom Semantic Forms input types. These input types display a map with a geocoder in a form to make the insertion (and editing) of coordinates easy for users.

Downloads

 * SemanticMaps0.3.zip 41.26 KB
 * SemanticMaps0.3.7z 20.78 KB

You can find older versions in the legacy downloads section of the version history page.

Notice: Semantic Maps and Maps are currently always released together. It is highly recommended to use the version of maps released together with the version of Semantic Maps you have.

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

svn checkout http://svn.wikimedia.org/svnroot/mediawiki/tags/extensions/SemanticMaps/REL_0_3

Package downloads
Maps and Semantic Maps


 * MapsAndSemanticMaps0.3.zip 645.81 KB
 * MapsAndSemanticMaps0.3.7z 217.88 KB

Semantic Bundle

Semantic Bundle currently includes Maps and Semantic Maps 0.2, as well as some other very interesting Semantic MediaWiki related extensions. Get it here.

Installation instructions
Make sure you have Semantic MediaWiki and Maps successfully installed before proceeding with the installation. Once you have downloaded the code, place the 'SemanticMaps' directory within your MediaWiki 'extensions' directory. Then add the following code to your LocalSettings.php file after the lines that install Maps:

The inclusion of extensions should happen in this order: Semantic MediaWiki, Semantic Forms (if you use it), Semantic Maps. Note, again, that Maps should also precede Semantic Maps. See the installation instructions of Maps for info about the API keys.

Upgrading from Semantic Google Maps
If you have Semantic Google Maps installed, and want to upgrade to Semantic Maps, these are the steps you need to follow:


 * Remove the SemanticGoogleMaps directory from your extension directory.
 * Remove (when you use it) Google Geocoder in a similar fashion.
 * Upload both Maps and Semantic Maps to your extension directory.
 * Make sure your API keys are in the right place (the variable $wgGoogleMapsKey will need to be renamed, or copied, to $egGoogleMapsKey).
 * Change all #semantic_google_map parser functions with #display_point.
 * Add parameter names to the value of the #display_point calls.

After doing all these steps, you should be done. Maps and Semantic Maps are designed to be backward compatible with SGM, so all SGM code should work on Semantic Maps. If you encounter some problem though, please let the extension developers know.

Version
Semantic Maps is currently at version 0.3. It is still considered beta, since some small issues might be present. However, it has been tested quite thoroughly, and should not cause any big problems.

Planned features
Curious about the upcoming features in the next release? The future work page contains on overview of the planned features, and the proposals that have been turned down.

Change log
This list only contains the versions and their release dates. For a list of all changes made, view the change log section of the version history page.


 * Version 0.3 (2009-08-14)
 * Version 0.2.2 (2009-08-01)
 * Version 0.2.1 (2009-07-30)


 * Version 0.2 (2009-07-29)


 * Version 0.1 (2009-07-21)

Languages supported
Semantic Maps has support for English, Afrikaans, Arabic, Egyptian Spoken Arabic, Belarusian, Breton, Bosnian, Catalan, German, Lower Sorbian, Greek, Esperanto, Spanish, Basque, Finnish, French, Galician, Swiss German, Hebrew, Upper Sorbian, Interlingua, Indonesian, Italian, Japanese, Khmer, Ripoarisch, Luxembourgish, Macedonian, Dutch, Norwegian Nynorsk, Norwegian, Occitan, Polish, Portuguese, Brazilian Portuguese, Romanian, Tarandíne, Russian, Slovak, Serbian Cyrillic ekavian, latinica, Swedish, Tagalog, Vietnamese, Volapük, Simplified Chinese, Traditional Chinese and others.

Usage


If you are new to both Maps and Semantic Maps, it is highly recommended you read how to use Maps first.

Querying coordinate data
You can set a Semantic MediaWiki #ask query to display its results as a map, by setting "format=mapservice", in which 'mapservice' is the mapping service you want to use. You can use all of the available mapping services of Maps. See the Map formats list for the exact names of the formats. 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.

Both maps that result from the following code will have markers on the same locations, but will use different mapping services. To recreate such a result, you simply make a category with the name Locations, which has a property 'Has coordinates', of type Geographic coordinate. Demo with the example.

Map formats
Semantic Maps adds multiple result formats to the ones made available by Semantic MediaWiki. The result format for a certain query map can be set with the  parameter in your #ask query. The underneath list contains the available result formats. You can also specify the service by adding the  parameter.
 * - the default mapping service will be used.
 * - Google Maps service. View example demo's.
 * - Yahoo Maps service. View example demo's.
 * - Open Layers service. View example demo's.

Some examples:

Each service has it's own unique functionality. Click the service name above for an overview of these features. See the map properties below for the common parameters.

Map properties
You can add seven additional parameters to the query, to change the appearance and usage of the resulting map.

To make it really easy for you, Semantic Maps uses the same names as Maps (see Map's map properties) where possible. There are however some differences.

Result formats


 * - (display_point only) the coordinates to display a marker and also the centre of the map - you can set the default
 * - (display_address only) the address to display a marker and also the centre of the map
 * - the width of the map, in pixels - you can set the default
 * - the height of the map, in pixels - you can set the default
 * or  - the coordinates of the map's centre. When not provided in a query, the map will centre itself to show all points.
 * - the map's zoom level. When not provided in a query, this will default to the maximal zoom that allows all points to be displayed.

Here is an example of an #ask query that uses the 'googlemaps' format (view demo's):

Form inputs


 * - the width of the map, in pixels - you can set the default
 * - the height of the map, in pixels - you can set the default
 * - the zoom level of the map. When not provided, this will default to a view of the entire planet - you can set the default
 * or  - the coordinates of the map's centre. When not provided, the map will centre itself on the current location (when no location is set yet, on coordinates 0,0).

Querying non-coordinate data


Semantic Maps supports the display of queried non-coordinate data. All queried properties that are not coordinates will be displayed in a pop-up balloon that will appear when clicking the marker representing the location of their corresponding coordinates. If there is a page associated with one of the non-coordinate values, the value will be linked to it.

Form Inputs


Semantic Maps provides multiple form inputs. Form inputs are hooks for Semantic Forms. Every mapping service has it's own form input. The form input type is determined with the  parameter.
 * - the default mapping service will be used.
 * - Google Maps service.
 * - Yahoo Maps service.
 * - OpenLayers service.

Each service has it's own unique functionality. Click the service name above for an overview of these features. See the map properties below for the common parameters.

Geocoding locations in the form input
This feature is only available for maps using the Google Maps or Yahoo! Maps mapping services. OpenLayers form inputs will not have it.

Settings
Semantic Maps allows you to configure a variety of settings, and so affect how the extension works. All settings are located in Maps_Settings.php, in the root of the Maps extension. Currently, Semantic Maps does not add any settings to the ones of Maps. Please refer to the Maps Settings for an overview of these settings, and instructions of how to modify them.

Extending Semantic Maps
Maps and Semantic have been designed to be very extendible. Due to their modular structure, it's possible to add a completely new mapping service without changing a thing in any of the core code, or even the extension's files. Adding a new mapping service has a whole list of advantages against creating your own extension to handle that service. Some of the most noteworthy are listed below.


 * Less work to create: The Maps and Semantic Maps code already handles the common features, and only requires mapping service specific code, sparing you the need to write code to handle problems other people have solved before. As a developer, you will also be able to take advantages of improvements made to Maps itself, without having to implement them over and over again in your own code.


 * Follows convention: By using the central Maps and Semantic Maps code, your not creating similar, but different code, which makes it easier for people to discover, locate and fix problems, and to add new functionality. This also makes usage for end user a lot easier, since the wiki code will always be similar to the extend possible.


 * Ease of installation: Installing two extensions (possibly bundled with 3rd party mapping service implementations) is far easier then installing a dozen for an end user. It also solves issues with incompatibility between multiple mapping services, which can cause extensions to break.


 * More publicity and usage: Since Maps is the only mapping extension for MediaWiki that handles a true mapping service independent platform, and cause of that provides multiple mapping services and a variety of both common and specific features, users are far more likely to choose Maps (and Semantic Maps) instead of multiple individual extensions.

How to extend Semantic Maps
You can learn how to create your own extension for Semantic Maps by looking at the source code and doing some experimenting, or you can read the manual, that goes through all the required steps.

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

svn diff >descriptivename.patch

Then add the patch to the bugs section of the future work page. Bug reports should also be added here. You can also send them to Jeroen De Dauw, jeroendedauw -at- gmail.com, and Yaron Koren, at yaron57 -at- gmail.com.

Feature requests
Feel free to add feature requests to the new proposals section of the future work page.

Translating
Translation of Semantic Maps is done through translatewiki.net. The translation for this extension can be found here. To add language values or change existing ones, you should create an account on translatewiki.net, 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.

Getting support
If you have any Semantic Maps related questions, you can add them to the Talk page. You can alternatively also place any questions on the Semantic MediaWiki mailing list, semediawiki-user. If possible, add "[SM]" at the beginning of the subject line, to clarify the subject matter. Please contact the extensions authors only directly for urgent matters. Placing your questions on the talk page will create useful references for other people with similar problems.

Who's using Semantic Maps?
Are you using Semantic Maps? Then be sure to add your wiki to the top of this list, and feel free to link your favourite Semantic Maps-using articles!


 * BN's dev wiki Development wiki with some demo data
 * Semantic MediaWiki community wiki
 * Food Finds