Semantic Maps

From Mapping on MediaWiki
Revision as of 21:14, March 30, 2010 by Jeroen De Dauw (Talk | contribs)$7

(diff) ← Older revision | Approved revision (diff) | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Crystal Clear action run.png
Semantic Maps

Release status: beta

SemanticMaps.png
Description Allows users to edit and display semantic coordinate data using multiple mapping services.
Author(s) Jeroen De Dauw, Yaron Koren and others
Last Version 0.6.6 (2010-08-26)
MediaWiki 1.15.* or greater
License GPL
Download MapsAndSemanticMaps0.5.5.zip

Description

Semantic Maps is an extension that adds semantic capabilities to the Maps extension. This includes the ability to add, edit, aggregate and visualize coordinate data stored through the Semantic MediaWiki extension.

Since Semantic Maps uses the Maps API, you can use multiple mapping services. These include Google Maps (with Google Earth support), Yahoo! Maps, OpenLayers and OpenStreetMap.

Both Semantic Maps and Maps are based on Semantic Google Maps and Semantic Layers, and are meant to replace these extensions. Having Semantic MediaWiki and Maps installed is a prerequisite for the Semantic Maps extension; the code will not work without it.

Help
Available languages
English


Functionality overview

Semantic Maps displaying the result of a compound query with Google Maps.

Semantic Maps and Maps 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. Semantic handling of coordinates. Semantic Maps adds a Geographical Coordinate data type to Semantic MediaWiki.
  3. 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.
  4. 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.

Download and installation

Download

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

Notice: Semantic Maps and Maps are always released together. This means you should always use the same version of Maps as the one of Semantic Maps you have. For example Maps 0.3.4 and Semantic Maps 0.3.4, but not Maps 0.2 and Semantic Maps 0.3.
Attention: To use Maps and SemanticMaps 0.5.4, you also need to upgrade to Validator 0.2.2.

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_5_5. From a command line, you can call the following:

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

Package downloads

Template:Maps and SM

Semantic Bundle

Template:SB Extension

Installation instructions

Semantic Maps 0.5.5 dependencies
Name Required Recommended Version Supported Versions
MediaWiki Yes 1.15 or above 1.15 or above, possibly older ones
Maps Yes 0.5.5 0.5.5
Validator Yes 0.2.2 0.2.2
Semantic MediaWiki Yes 1.5 (no newer ones!) 1.4.2 to 1.5, possibly older ones
Semantic Forms No 1.9 or above 1.9 or above, possibly older ones

Make sure you have Semantic MediaWiki, Maps and Validator 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:

require_once( "$IP/extensions/SemanticMaps/SemanticMaps.php" );

The placement of the inclusion of Maps and Semantic Maps needs to be at a certain position. Hold the following rules into account:

  • Maps needs to be included before Semantic Maps.
  • Semantic MediaWiki needs to be included before Maps.
  • Semantic Forms (if used) needs to be included before Maps (after SMW).

An example of a typical inclusion order: ..., SMW, ..., SF, ..., Maps, SM, ...

Once you have successfully installed Semantic Maps, please add your wiki to the sites that use Semantic Maps section.

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.6.6 (2010-08-26). 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.2 (2009-07-29)
    • Version 0.2.1 (2009-07-30)
    • Version 0.2.2 (2009-08-01)

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, Hungarian, Interlingua, Indonesian, Italian, Japanese, Khmer, Ripoarisch, Luxembourgish, Macedonian, Dutch, Norwegian Nynorsk, Norwegian, Occitan, Polish, Piedmontese, Portuguese, Brazilian Portuguese, Romanian, Tarandíne, Russian, Slovak, Serbian Cyrillic ekavian, Serbian Latin ekavian, Swedish, Telugu, Tagalog, Veps, Vietnamese, Volapük, Simplified Chinese, Traditional Chinese and others.

Usage

File:Sm-ymap-qp-sattelite.gif
Semantic Maps showing a Yahoo! Maps map with markers representing queried coordinate data.

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

Querying coordinate data

Semantic Maps provides the ability to aggregate coordinate data stored semantically via the Semantic MediaWiki extension by adding 'result formats' to it. This means that you are able to specify the mapping service you want to use with a parameter in an #ask query. If you do not know how #ask queries work, please read the manual. If you have any problems with your #ask queries in Semantic Maps, please try using the 'table' format instead of a mapping service to see which results are actually returned by your query.

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.

You can find a list of all map properties you can set in #ask queries in the ask queries sub in the map properties section. You can find a list of all mapping services you can use with queries in the map services section.

The result formats provided by Semantic Maps can also be used in some extensions that extend Semantic MediaWiki's querying capabilities. The following list includes a few of them, but not all.

  • Semantic Compound Queries: Defines a parser function, #compound_query, that can make multiple Semantic MediaWiki queries at the same time.
  • Semantic Drilldown: Provides a page for drilling down into the category-based and semantic data of a site, using easily-created filters.

Querying non-coordinate data

Semantic Maps displaying a Google Maps map with Google Earth map type and a marker with pop-up representing queried 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 Forms showing a Google Maps map and geocoding features provided by a hook of Semantic Maps.

Semantic Maps provides multiple form inputs. These form inputs are hooks for the Semantic Forms extension. They allow users to add, edit and query data using forms, instead of wiki code. For more info on how to work with form inputs, please read how to define them. Every mapping service has it's own form input.

Once you have defined a form with one or more fields using an input type provided by Maps, you can insert and edit data with it. When you create new data, a text field for coordinates and a map of the chosen mapping service will be shown. You can either simply enter the coordinates and ignore the map, or you can use the map to determine your coordinates. This is simply done by clicking on the location you want to add, which will result in the corresponding coordinates to be displayed into the coordinate text field.

You can find a list of all map properties you can set in #ask queries in the form inputs sub in the map properties section. You can find a list of all mapping services you can use with queries in the map services section.

Geocoding locations in the form input

Semantic Maps has live geocoding capabilities in several of it's form inputs. This feature is present in the form of an extra text field underneath the coordinate field, where you can enter an address, and a 'look up coordinates' button. It's used by entering your address into the address field, and then clicking the related button. Once you've done this, the marker on the map will move to the correct location (or be placed there when it's not yet on the map), and the coordinates in the coordinate field will be updated.

This feature is only available for maps using the Google Maps or Yahoo! Maps mapping services. OpenLayers form inputs does not have it.

Map services

Semantic Maps current supports all mapping services of Maps, as listed below. Every service, and all of it's aliases are made available as result formats in #ask queries, and as input types for forms. Template:Maps Extension Services Table

Example of the usage of the format parameter in an #ask query:

{{#ask:[[Category:Locations]]|?Has coordinates|format=googlemaps}}

Example of the usage of the input type parameter in a coordinate form field:

{{{field|The coordinates|input type=googlemaps}}}

Both the #ask queries and the input types for forms support the 'map' value for their result format and input type, respectively. When you use this value, the default mapping service will be used. You can also, optionally add a 'service' parameter, which will then determine the mapping service that will be used. Note that the 'service' parameter will only be held into account when using the 'map' format or input type.

Example demonstrating the usage of the 'map' value in an #ask query. The default mapping service will be used.

{{#ask:[[Category:Locations]]|?Has coordinates|format=map}}

Map properties

You can add seven additional parameters to the definition of #ask queries and form inputs, 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. The sections below list all properties you can use for the feature discussed in them.

Ask queries

This table contains all common map properties you can place in #ask queries.

Property Usage Aliases Default Version
format Allows to set the mapping service that will be used to generate the map. Do not use a 'service=' parameter for this, like in Maps. - configurable -
geoservice Allows to set the geocoding service used to turn addresses into coordinates. - configurable Added in 0.4.1
width Allows to set the width of the map, in pixels. - configurable -
height Allows to set the height of the map, in pixels. - configurable -
zoom Allows to set the zoom level of the map. When not provided and multiple markers are present on the map, the best fitting zoom will be taken, not the configurable default. - configurable or auto-detect Changed in 0.2
centre Allows to set the coordinates of the map's centre. When this parameter is not provided, the map will centre itself on the provided markers. center auto-detect Changed in 0.2
forceshow Enables you to force a map to be shown even when there are no query results. force show off Added in 0.5.1
showtitle Enables you to hide the title in the marker pop-ups. show title on Added in 0.5.2
template Allows you to define the content and it's layout of marker pop-ups. The template will receive the queried property values as nameless parameters ({{{1}}}, {{{2}}}, ect), and 3 named parameters: {{{title}}}, {{{latitude}}} and {{{longitude}}}. - none Added in 0.5.2
icon Allows you to set the icon used for all markers. - Default mapping service marker Added in 0.5.2
Semantic Maps showing queried data using a template for formatting.

This example demonstrates the use of properties and custom formatting using the template and showtitle parameters. (view demo's):

{{#ask: [[Category:City]]
| ?coordinates
| ?population 
| ?area#km²
| format=map
| width=800
| zoom=10
| template=City Popup
| showtitle=off
| icon=Blue_marker.png
}}

Form inputs

This table contains all common map properties you can place in coordinate field definitions of forms. For non Semantic Maps specific properties, review the Semantic Forms form markup language.

Property Usage Aliases Default Version
input type Allows to set the mapping service that will be used to generate the map. Do not use a 'service=' parameter for this, like in Maps. - configurable -
geoservice Allows to set the geocoding service used to turn addresses into coordinates. - configurable Added in 0.4.1
width Allows to set the width of the map, in pixels. - configurable -
height Allows to set the height of the map, in pixels. - configurable -
zoom Allows to set the zoom level of the map. When not provided , the zoom will be set so you can see the entire planet. - configurable or auto-detect Changed in 0.2
centre Allows to set the coordinates of the map's centre. When this parameter is not provided, the map will centre itself on the current location, or when not set, to coordinates 0,0. center auto-detect Changed in 0.2

Here is an example of a definition of a coordinate field definition in a form that uses the 'googlemaps' format:

{{{
field
|The coordinates
|input type=googlemaps
|width=800
|height=500
|zoom=8
|autozoom=off
}}}

Settings

Semantic Maps allows you to configure a variety of settings, and so affect how the extension works. All settings are located in SM_Settings.php, in the root of the extension. You can modify a setting by copying it's code and placing it with the adapted value in LocalSettings.php, after the inclusion of Semantic Maps. Here you have a list of the common settings (the ones that affect all mapping services). For the specific settings, see the map services. Note that the settings file is documented, and should provide you with sufficient information to understand the working of all settings.

Since Semantic Maps extends Maps, most settings are actually part of Maps. If you want to change such settings, which include things like default map height and zoom level, review Maps settings.

Available mapping services

Semantic Maps adds data to this setting, but it belongs to Maps. See Maps available mapping services for more info.

Default:

include_once $smgIP . '/GoogleMaps/SM_GoogleMaps.php';     // Google Maps
include_once $smgIP . '/OpenLayers/SM_OpenLayers.php';     // OpenLayers
include_once $smgIP . '/YahooMaps/SM_YahooMaps.php';       // Yahoo! Maps
include_once $smgIP . '/OpenStreetMap/SM_OSM.php';         // OpenLayers optimized for OSM

When not using a service, you might consider removing it's inclusion. Doing this will cause Maps to completely ignore it for Semantic Maps features, and so improve performance.

Default mapping service

Semantic Maps adds data to this setting, but it belongs to Maps. See Maps default mapping service for more info.

Default:

$egMapsDefaultServices['qp'] = 'googlemaps';
$egMapsDefaultServices['fi'] = 'googlemaps';

This list contains all available features, and their feature identifier, which Semantic Maps should add to the $egMapsDefaultServices array.

  • qp - Query Printer - This default will be used for all semantic queries. Query printers handle semantic result formats.
  • fi - Form Input - This default will be used for all form input maps. Form inputs define Semantic Forms input types.

Available mapping features

Semantic Maps adds data to this setting, but it belongs to Maps. See Maps available mapping features for more info.

Default:

$egMapsAvailableFeatures['qp'] = array(
                            'name' => 'Query Printer',
                            'class' => 'SMQueryPrinters',
                            'file' => 'SemanticMaps/QueryPrinters/SM_QueryPrinters.php',
                            'local' => false
                            );
 
$egMapsAvailableFeatures['fi'] = array(
                            'name' => 'Form input',
                            'class' => 'SMFormInputs',
                            'file' => 'SemanticMaps/FormInputs/SM_FormInputs.php',
                            'local' => false
                            );

Contributing to the project

Supporting further development

Are you using Semantic Maps, and want to show a sign of gratitude? You can make a donation to support further development.

Extending Semantic Maps

Semantic Maps is a hook to Maps, which has been designed to be very extendible. It has several hooks that enable you to add support for new mapping services, geocoding services or entirely new features (such as parser functions) to it without having to change anything to the code of Maps. This enables you to add things to Maps in your own extension, or simply create a new extension to Maps. Semantic Maps is an example of an extension to Maps.

There are multiple important reasons why you should consider creating an extension to Maps, versus creating your own mapping extension. You can find these reasons, and how to extend Maps (or Semantic Maps) here.

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.

Work for hire

The following people can be hired to set up a wiki that uses Maps and Semantic Maps, along with other MediaWiki components.

  • Jeroen De Dauw - You can also hire me to develop new features for Maps or it's extensions, or do optimizations for your specific needs. Just send me an email.

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.

Sites that use 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!

External links

See also

Template:Maps Extension Services

Facts about "Semantic Maps"RDF feed
Has version0.6.6 (2010-08-26) +