Help:Extension:Kartographer/Developer guide

From MediaWiki.org
Jump to: navigation, search

Kartographer for developers[edit]

Creating a map frame[edit]

Example:

mw.loader.using( [ 'ext.kartographer.box' ], function () {

	var kartoBox = mw.loader.require( 'ext.kartographer.box' ),
		map;

	map = kartoBox.map( {
		container: $( '#bodyContent' ).empty().css( { height: 400 } )[ 0 ],
		center: [ 37.7868, -122.3995 ],
		zoom: 11,
		allowFullScreen: true,
		data: [ {
			"type": "Feature",
			"properties": {
				"marker-color": "#3366cc",
				"marker-size": "medium",
				"marker-symbol": ""
			},
			"geometry": {
				"type": "Point",
				"coordinates": [
					-122.39951848983763,
					37.78687738310861
				]
			}
		} ]
	} );
} );

Creating a map link[edit]

Developer documentation[edit]

Links to API documentation[edit]

Wikivoyage customization[edit]

How it works[edit]

The Wikivoyage projects have use cases that do not apply to all projects and require to customize Kartographer. This extension of the Kartographer code is contained within the ResourceLoader module ext.kartographer.wv. Wikivoyage projects, such as the English one, may load the module and configure it by creating a MediaWiki:Kartographer.js script file (see English MediaWiki:Kartographer.js). A custom CSS, MediaWiki:Kartographer.css, also gets loaded to allow styling customizations. These two files, grouped in the ResourceLoader module ext.kartographer.wv, are loaded on each page that contain a <maplink> or a <mapframe>.

What it does[edit]

Typically, MediaWiki:Kartographer.js will define an additional list of tile layers and overlays for Kartographer. The code listens to a Kartographer extension hook wikipage.maps and adds a few features onto the map:

  • Adds a control (top right) to select a different tile layer and toggle overlays
  • Adds a control (top left) to show the Nearby Articles from Wikivoyage.

You can see a live example at California#See.

List of Kartographer modules[edit]

These are the list of ResourceLoader modules implemented by the extension. See the online API documentation for more details.

Client-side modules[edit]

Resource name JS CSS i18n Description Public APIs
ext.kartographer.box x x Kartographer's extension of Leaflet/Mapbox

Use this module to create maps in your projects.

Classes:

  • OpenFullScreenControl
  • CloseFullScreenControl
  • ScaleControl
  • Map
  • Link
Constructors:
  • link( options )
  • map( options )
ext.kartographer.dialog x x Module managing the dialog required to open a map in full screen mode.

Classes:

  • Dialog
Methods
  • render( map )
  • close
ext.kartographer.frame x Once the page is loaded and ready, turn all <mapframe> tags into embed interactive maps.
ext.kartographer.link x Once the page is loaded and ready, turn all <maplink> tags into a link that opens the map in full screen mode.
ext.kartographer.editing x Methods useful when editing a map:
  • getKartographerLayer gets (or creates) the "editable" GeoJSON layer on the map.
  • updateKartographerLayer updates the "editable" GeoJSON layer once sanitized.
Methods
  • getKartographerLayer
  • updateKartographerLayer
ext.kartographer.editor Modules required for the map editor within ext.kartographer.visualEditor:
  • leaflet.draw
  • ext.kartographer.live
ext.kartographer.preview x Module listening to wikipage.maps hook and adding a right-click handler to the map to show the corresponding coordinates.
ext.kartographer.settings x Module configuring mapbox.
ext.kartographer.site x x Loads:
  • {your_wiki}/Mediawiki:Kartographer.js
  • {your_wiki}/Mediawiki:Kartographer.css
ext.kartographer.style x Client-side stylesheets for Kartographer
ext.kartographer.visualEditor x x x VisualEditor implementation:
  • Resize a <mapframe> tag inline.
  • Edit a <mapframe> tag in a dialog.
  • Edit a <maplink> tag in a dialog.
ext.kartographer.wv x x x Client-side module containing Wikivoyage customizations.
  • NearbyArticles: A submodule to fetch nearby articles.
  • wikivoyage: A set of utility methods.
  • WVMap: The Wikivoyage Map class to customize an interactive MWMap map.

Note: This may move to its own extension.

  • NearbyArticles
  • wikivoyage
  • WVMap

Server-side modules[edit]

Resource name PHP CSS i18n Description
ext.kartographer x Server-side module providing extra data to the client.

External libraries[edit]

Note: Do not use. You should require our client-side modules rather than the original libraries. These are made available as single resources for performance and caching reasons.

Resource name JS CSS i18n Description
mapbox x x x Mapbox.js

Mapbox JavaScript API, a Leaflet Plugin. http://mapbox.com/mapbox.js/

leaflet.draw x x x Leaflet.Draw

Vector drawing and editing plugin for Leaflet.

ext.kartographer.lib.prunecluster x x PruneCluster

Fast and realtime marker clustering for Leaflet.

ext.kartographer.lib.topojson TopoJSON

TopoJSON is an extension of GeoJSON that encodes topology.