4,000
edits
Changes
Extension:Kartographer (view source)
Revision as of 14:59, 28 November 2020
, 14:59, 28 November 2020Created page with " The '''Kartographer''' extension lets you display maps (based around OpenStreetMap) in wiki pages. It was specifically designed in order to run on..."
The '''Kartographer''' extension lets you display maps (based around [[wikipedia:OpenStreetMap|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.
'''Note:''' the tile server used by default by the Wikimedia Foundation is not available to 3rd parties. Please use your own tileserver.
== Usage ==
Kartographer defines the wikitext tags <code><mapframe></code> and <code><maplink></code>, which both display a map on the page. See [[Help:Extension:Kartographer]] for how to call these tags.
== Example ==
<mapframe text="Map of [[wikipedia:London|London]]" latitude="51.505" longitude="-0.126" zoom="8" width="300" height="300" align="left">
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"title": "[[wikipedia:London|London]] is the capital of [[wikipedia:United Kingdom|United Kingdom]]",
"description": "[[File:Houses_of_Parliament.jpg|Houses of Parliament|280px]]",
"marker-symbol": "town-hall",
"marker-size": "large",
"marker-color": "f00"
},
"geometry": {
"type": "Point",
"coordinates": [
-0.1226806780323386,
51.515268213580114
]
}
}
]
}</mapframe>
<br style="clear: both;" clear="all" />
== Installation ==
{{ExtensionInstall
|composer=yes
|custom-steps0=* Install the [[Extension:JsonConfig|"JsonConfig" extension]] as described in its documentation which is required to run this extension.
|custom-steps=* [[#Configuration|Configure as required.]]
|registration=yes
}}
== Configuration ==
{| class="wikitable"
|+
Configuration settings
!parameter
!default
!comment
|-
| $wgKartographerWikivoyageMode
|<syntaxhighlight lang="php">false</syntaxhighlight>
| Enables Wikivoyage mode.
|-
| $wgKartographerUseMarkerStyle
|<syntaxhighlight lang="php">false</syntaxhighlight>
| href="wikipedia:OpenStreetMap" |Allows Kartographer to extract CSS style to be used by the link from the GeoJSON.
|-
| href="Maps#Production maps cluster" |$wgKartographerStaticMapframe
|<syntaxhighlight lang="php">false</syntaxhighlight>
|Defines if the map will be a static image.
|-
| $wgKartographerEnableMapFrame
|<syntaxhighlight lang="php">true</syntaxhighlight>
| Enables the <nowiki><mapframe></nowiki> tag to be used to create static or interactive maps.
|-
| $wgKartographerMapServer
|<syntaxhighlight lang="php">"https://maps.wikimedia.org"</syntaxhighlight>
| Server providing the map tiles
|-
| $wgKartographerStyles
|<syntaxhighlight lang="json">["osm-intl", "osm"]</syntaxhighlight>
| Available map styles on $wgKartographerMapServer
|}
== Implementation ==
* [[Help:Extension:Kartographer/Developer_guide|Kartographer developer guide]]
* [https://doc.wikimedia.org/Kartographer/master/js/ API documentation]
Kartographer makes use of a suite of open-source, open-data tools for displaying maps:
* On the client side (within the browser):
** [[wikipedia:Leaflet (software)|Leaflet]], a JavaScript mapping library
* On the server side:
** [https://github.com/kartotherian/kartotherian#readme Kartotherian], a map tile service developed by the Wikimedia Foundation, which itself contains code from [[wikipedia:Mapbox|Mapbox]]. Third party installations should use non-Wikimedia tile servers listed on https://wiki.openstreetmap.org/wiki/Tile_servers
* Generating the data in advance:
** [https://github.com/kartotherian/tilerator/blob/master/README.md Tilerator], a tile pre-generation service also developed by the Wikimedia Foundation
** [[wikipedia:OpenStreetMap|OpenStreetMap]], an open map data source, the source for the map data as well as for most of the points of interest (POIs).
For more information on these, see [[Maps#Production maps cluster]]. For more information on the production aspects of running these services, see the Wikitech [https://wikitech.wikimedia.org/wiki/Maps 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. wmflabs. 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 points of interest (POIs), such as museums and restaurants, listed on a page (see [[voy:Salzburg#Get_around|example]] and scroll down to the "See" section). 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 <sup>[1]</sup> on the page, and map would show POI as a clickable <sup>[1]</sup> 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 [https://phabricator.wikimedia.org/project/board/1127/ complete list of bugs].
=== Conflict with FlaggedRevs ===
Because of technical issues, some Wikipedias that implement a specific setting of [[Extension:FlaggedRevs]] cannot show the mapframe tag.
See [[phab:T191585]] and [[phab:T151665]] for more information.
{{OnWikimedia}}
[[Category:Map extensions]]
[[Category:Discovery]]