Extension:Kartographer - MediaWiki
Jump to content
From mediawiki.org
Translate this page
Languages:
Bahasa Indonesia
polski
čeština
русский
فارسی
MediaWiki extensions manual
Kartographer
Release status:
stable
Implementation
Tag
Description
Allows to add maps to pages as a frontend to
mapping services
Author(s)
Yuri Astrakhan (
yurik
talk
Compatibility policy
Snapshots releases along with MediaWiki. Master is not backward compatible.
MediaWiki
1.39+
Database changes
No
Parameters
$wgKartographerSimpleStyleMarkers
$wgKartographerSrcsetScales
$wgKartographerStaticFullWidth
$wgKartographerUsePageLanguage
$wgKartographerStaticMapframe
$wgKartographerDfltStyle
$wgKartographerFallbackZoom
$wgKartographerParsoidVersion
$wgKartographerMapServer
$wgKartographerWikivoyageMode
$wgKartographerMediaWikiInternalUrl
$wgKartographerStyles
$wgKartographerUseMarkerStyle
$wgKartographerNearby
Tags
mapframe
maplink
Hooks used
ParserAfterParse
ParserFirstCallInit
ParserTestGlobals
Licence
MIT License
Download extension
Git
Browse repository
GitHub
Gerrit code review
Git commit log
Download source tarball
Help
Help:Extension:Kartographer
Example
See below on this page
Translate the Kartographer extension
if it is available at translatewiki.net
Issues
Open tasks
Report a bug
The
Kartographer
extension lets you display maps (based around
OpenStreetMap
) in wiki pages.
It was specifically designed in order to run on Wikimedia sites such as Wikivoyage and Wikipedia, although it can be used on any wiki.
The tile server at maps.wikimedia.org is not available to 3rd parties. Please use your own tileserver. If you are a
Wikimedia affiliate
, see
Maps/External usage
instead.
Usage
Kartographer defines the wikitext tags
‎<
mapframe
...
‎mapframe
and
‎<
maplink
, which display a map and a link to a map on the page respectively.
See
Help:Extension:Kartographer
for how to call these tags.
Example
Map of
London
Installation
Install the
JsonConfig
extension as described in its documentation which is required to run this extension.
and move the extracted
Kartographer
folder to your
extensions/
directory.
Developers and code contributors should install the extension
from Git
instead, using:
cd
extensions/
git
clone
Only when installing from Git, run
Composer
to install PHP dependencies, by issuing
composer install --no-dev
in the extension directory.
(See
T173141
for potential complications.)
Add the following code at the bottom of your
LocalSettings.php
file:
wfLoadExtension
'Kartographer'
);
Configure as required.
Done
– Navigate to
Special:Version
on your wiki to verify that the extension is successfully installed.
Configuration
Configuration settings
parameter
default
comment
$wgKartographerMapServer
null
Server providing the map tiles. This is the only setting that doesn't have a default. You must provide a value. Note that the Wikimedia tile server
can't be used outside of the Wikimedia cluster. See
openstreetmap:Tile servers
for tile servers.
$wgKartographerStyles
"osm-intl"
"osm"
Available map styles users can request from your $wgKartographerMapServer via
mapstyle="…"
$wgKartographerDfltStyle
"osm-intl"
Default map style to be used. Must be one of the values from $wgKartographerStyles.
$wgKartographerSrcsetScales
1.3
1.5
2.6
Set of allowed high-DPI pixelratios supported by your $wgKartographerMapServer, to be used in

and $wgKartographerMapServer URLs. Must be in incremental order. Doesn't need to start with 1, this happens automatically. Note that most tile servers don't support this at all and thus require setting this to an empty array.
$wgKartographerUseMarkerStyle
false
Allows Kartographer to extract marker styles from the GeoJSON to style a
‎<
maplink
accordingly. Currently only the
marker-color
is considered.
$wgKartographerWikivoyageMode
false
Enables the group feature where different
‎<
maplink
and
‎<
mapframe
tags can access each others data via
group="…"
and
show="…"
attributes. See
Groups
. Disabled by default. Meant to be enabled on
Wikivoyage
$wgKartographerStaticMapframe
false
Disables the module that turns
‎<
mapframe
tags into interactive mini-maps that can be panned and zoomed without leaving the page. Static maps are recommended on high-traffic wikis where your KartographerMapServer couldn't keep up. Clicking
‎<
maplink
and
‎<
mapframe
tags to open a fullscreen interactive map is always possible. Requires a static map renderer like
Kartotherian
$wg KartographerStaticFullWidth
1024
The actual width of static map images when a
‎<
mapframe
uses the special value
width="full"
. Relevant on wikis in static mode or when JavaScript is disabled. It's recommended to use one of the $wgImageLimits widths for consistency.
$wgKartographerUsePageLanguage
true
Use the language of the page instead of that of the language of the territory mapped. This sets the
lang
parameter of the tiles requested.
$wgKartographerFallbackZoom
13
Fallback zoom value when no
zoom="…"
is given. Must be an integer between 0 (map shows the entire earth) and 19 (as close as possible). Currently only works with dynamic maps.
$wgKartographerSimpleStyleMarkers
true
Use an api to generate markers using the simplestyle-spec for features. Should be set to
false
for most applications outside WMF. Otherwise images of markers are assumed to be hosted on the map server.
$wgKartographerNearby
false
Enable the
Show nearby articles
button when in fullscreen
API
This extension provides two internal APIs.
Query mapdata
Action sanitise mapdata
Implementation
Kartographer developer guide
API documentation
Kartographer makes use of a suite of open-source, open-data tools for displaying maps:
On the client side (within the browser):
Leaflet
, a JavaScript mapping library
On the server side:
Kartotherian
, a map tile service developed by the Wikimedia Foundation, which itself contains code from
Mapbox
. Third party installations should use non-Wikimedia tile servers listed on
openstreetmap:Tile servers
Generating the data in advance:
Tilerator
- a tile pre-generation service also developed by the Wikimedia Foundation
OpenStreetMap
- an open map data source, the source for the map data as well as for most of POIs.
For more information on these, see
Wikimedia Maps
For more information on the production aspects of running these services, see the
Wikitech Maps
page.
Goals
General goals
A simple method to insert a map into an article without requiring common.js code changes
Ability to add extra information (marks, area, popups, text, links) to the map
Ability to gather map usage statistics (KPI) to better gauge how and what should be improved.
TBD:
experimentation - if the user is aware of the privacy implications, the map should be able to show external data from non-production source, e.g. Static, server-side rendered images will not include the extra data added via this method until the extra data source is hosted in the secure production environment and can be shown without the user action.
Wikivoyage goals
Wikivoyage tends to have a large number of POIs listed on a page
(see
example
).
Each POI is usually added with a template, but all of them should appear on the same map.
Also, each POI should be referable by showing an icon with a number, both in the text of the article, and on the map:
Ability to incrementally add features to the map. For example, each usage of the
restaurant
template adds a single POI
, and the map shows all of them.
Added features need to be indexable. E.g. the first
restaurant
template would show
[1]
on the page, and map would show POI as a clickable
[1]
element. There could be multiple index counters at the same time, each for its own type of POIs.
Known problems
See the corresponding project(s) in
Phabricator
for a
complete list of bugs
See also
Extension:Maps
- Extension to visualise and work with geographical information.
Semantic Result Formats
- Various visualisation formats for
Extension:Semantic MediaWiki
Extension:GeoData
- Allows articles to specify their geographical coordinates and publishes these coordinates via the HTTP API.
Extension:MultiMaps
- Allows users to display maps and coordinate data using multiple mapping services
Extension:VisualData/Geolocation
- Allows displaying
Maptiler
maps in forms with reverse geocoding and draggable markers
References
1.0
1.1
1.2
POI – points of interest such as museums, restaurants...
This extension is being used on one or more
Wikimedia projects
. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia's
CommonSettings.php
and
InitialiseSettings.php
configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki's
Special:Version
page.
This extension is included in the following wiki farms/hosts and/or packages:
Miraheze
Retrieved from "
Categories
Stable extensions
Tag extensions
ParserAfterParse extensions
ParserFirstCallInit extensions
ParserTestGlobals extensions
MIT licensed extensions
Extensions in Wikimedia version control
All extensions
Extensions requiring Composer with git
Extensions used on Wikimedia
Extensions included in Miraheze
Map extensions
Discovery
Extensions with VisualEditor support
Hidden categories:
Extensions with release branches compatibility policy
Extensions with manual MediaWiki version
Pages using the Kartographer extension
Extension
Kartographer
Add topic