Extension:Maps/mapping service

Disclaimer: Contents of this page may not be accurate and outdated! The following should be replaced by semantic pages (one for each service) and a summary table.

Due to Maps modular build, modifying the mapping service of a map is as easy as changing a single map property! These mapping services include Google Maps, OpenLayers and Leaflet, since at least version 3.0 These allow you to display maps with Google Earth, Bing maps, OpenStreetMaps, and others. Some of them have restricted licences, others are completely open source.

Google Maps v3

Parameters

Parameter	Type	Default	Description
zoom	whole number	14	The zoom level for the map. For maps with markers this will default to the most zoomed in level that still shows all markers.
width	number and dimensional unit	auto	Allows setting the width of the map. By default pixels will be assumed as unit, but you can explicitly specify one of these units: px, ex, em, %.
height	number and dimensional unit	350	Allows setting the height of the map. By default pixels will be assumed as unit, but you can explicitly specify one of these units: px, ex, em.
centre	text	no	The location on which the map should be centered
title	text	empty	Allows setting text that will be displayed in the pop-ups of all markers that do not have a specific title. When used together with label, the title will be bold and underlined.
label	text	empty	Allows setting text that will be displayed in the pop-ups of all markers that do not have a specific label.
icon	text	empty	Allows setting the icon used for all markers.
lines	List of lines	empty	Lines to display
polygons	List of geographical polygons	empty	Polygons to display
circles	List of circles	empty	Circles to display
rectangles	List of rectangles	empty	Rectangles to display
maxzoom	whole number	no	The maximum zoom level
minzoom	whole number	no	The minimum zoom level
copycoords	yes/no	no	Show a dialog when clicking on a location from which its coordinates may be copied
static	yes/no	no	Make the map static
visitedicon	text	empty	The filename of an image to be used for marker icons after the original markers have been clicked
wmsoverlay	Web Map Service overlay	no	Use a WMS overlay
type	text	roadmap	The map type to initially show.
types	list of texts	roadmap, satellite, hybrid, terrain	The map types that will be available via the type control.
layers	list of texts	empty	Special layers to load onto the map.
controls	list of texts	pan, zoom, type, scale, streetview, rotate	The controls to place on the map.
zoomstyle	text	default	The style of the zoom control.
typestyle	text	default	The style of the type control.
autoinfowindows	yes/no	no	Automatically open all info windows after the page has loaded.
resizable	yes/no	no	Makes the map resizable by dragging at its lower right corner.
kmlrezoom	yes/no	no	Rezoom the map after the KML layers have been loaded.
poi	yes/no	yes	Show points of interest.
cluster	yes/no	no	Allows merging of multiple nearby markers into one marker
clustergridsize	whole number	60	The grid size of a cluster in pixels.
clustermaxzoom	whole number	20	The maximum zoom level where clusters may exist.
clusterzoomonclick	yes/no	yes	Whether the default behaviour of clicking on a cluster is to zoom into it.
clusteraveragecenter	yes/no	yes	Whether the center of each cluster should be the average of all markers in the cluster.
clusterminsize	whole number	2	The minimum number of markers to be in a cluster before the markers are hidden and a count is shown.
imageoverlays	List of image overlays	empty	Allows adding an image to be shown on the specified location on the map.
kml	list of texts	empty	KML files to load onto the map.
gkml	list of texts	empty	KML files hosted by Google to load onto the map.
searchmarkers	text	empty	Allows to search for specific markers via a field embedded into the map.
fullscreen	yes/no	no	Enable fullscreen button
scrollwheelzoom	yes/no	no	Indicates if mouse scrolling should be enabled or not.

Also take a look at the Category:Maps examples for Google Maps v3.

Settings

The following settings can be overridden in Localsettings.php and are supported by most of the features implementing this service.

Google Maps v3 API Key and Version

Due to changes to Google Maps, an API key now needs to be set. See the installation configuration instructions.

Default: $egMapsGMaps3ApiKey = ;
Default: $egMapsGMaps3ApiVersion = ;

Default map zoom

The default zoom of a Google Maps map. This value will only be used when the user does not provide one.

Default: $egMapsGMaps3Zoom = 14;

Default map types

The default Google Maps map types. This are the map types the user will be able to choose in the map type selector control. This value will only be used when the user does not provide one.

Default: $egMapsGMaps3Types = array( 'roadmap', 'satellite', 'hybrid', 'terrain' );

Default map type

The default map type, in other words: the one the map will show when the page is loaded. This value will only be used when the user does not provide one.

Default: $egMapsGMaps3Type = 'roadmap';

Controls

Default: $egMapsGMaps3Controls = array( 'pan', 'zoom', 'type', 'scale', 'streetview' );

These are all currently supported.

Layers

Supported: traffic, bicycling

Default: $egMapsGMaps3Layers = array();

Type control style

Supported: horizontal, vertical or default

Default: $egMapsGMaps3DefTypeStyle = 'default';

Zoom control style

Supported: small, large or default

Default: $egMapsGMaps3DefZoomStyle = 'default';

Auto windows

Open info windows on page load by default.

Default: $egMapsGMaps3AutoInfoWindows = false;

Default tilt

Default tilt when using Google Maps. Integer.

Default: $egMapsGMaps3DefaultTilt = 0;

OpenLayers

This mapping service defines several of it's own parameters that are supported by most of the features implementing this service.

Fatal error: Value not in whitelist

Also take a look at the Category:Maps examples for OpenLayers.

Layers

Parameter: layers=

Available values

• bing - All available Bing Maps (formerly known as Virtual Earth) map types
  • bing-normal - Bing streets
  • bing-satellite - Bing satellite
  • bing-hybrid - Bing hybrid

• yahoo - All available Yahoo! Maps map types
  • yahoo-normal - Yahoo! streets
  • yahoo-satellite - Yahoo! satellite
  • yahoo-hybrid - Yahoo! hybrid

• osm - All available OpenStreetMap map types
  • osmarender - OSM arender
  • osm-mapnik - OSM Mapnik
  • osm-cyclemap - OSM Cycle Map

• openlayers-wms - OpenLayers WMS
• nasa - NASA Global Mosaic

How it works

This parameter sets the available base layers of your OpenLayers map. You can add as many base layers as you want, by separating them with comma's. When you add a layer twice, only the first occurrence will be added. The google, bing, yahoo and osm short cuts allow you to add all their associated layers without having to type them individually. You can configure the default layers (the ones that will be added when no value is provided) in the settings file. The first layer will be loaded at start-up.

Extra dependencies

Adding certain layers will make the OpenLayers map dependent on other mapping API's. Those are listed below:

• All Google layers - require the Google Maps API. You must have a valid Google Maps API key entered for these layers to work!
• All Yahoo! layers - require the Yahoo! Maps API. You must have a valid Yahoo! Maps API key entered for these layers to work!

Examples

This is a simple example with 3 layers.

layers=google-hybrid,nasa,bing-hybrid

This example demonstrates the usage of the bundle short-cuts.

layers=google-hybrid,nasa,yahoo,google

This will result in the following order of layers:

Google hybrid, NASA Global Mosaic, Yahoo! streets, Yahoo! satellite, Yahoo! hybrid, Google streets, Google satellite maps, Google physical maps

Google Maps layers

Layers add extra information to a Map. Look at the Maps_examples/Google_Maps_layer_map example for inspiration.

{{#display_map:new york city|layers=traffic, bicycling}}

To be able to use Google Maps layers, you need to add the following lines to your LocalSettings file, after the inclusion of Maps, and any API keys.

# Google Maps layers for OpenLayers
$egMapsOLAvailableLayers['google-normal'] = array('OpenLayers.Layer.Google( "Google Streets", {"sphericalMercator":true} )', 'google');
$egMapsOLAvailableLayers['google-satellite'] = array('OpenLayers.Layer.Google( "Google Satellite", {type: G_SATELLITE_MAP , "sphericalMercator":true} )', 'google');
$egMapsOLAvailableLayers['google-hybrid'] = array('OpenLayers.Layer.Google( "Google Hybrid", {type: G_HYBRID_MAP , "sphericalMercator":true} )', 'google');
$egMapsOLAvailableLayers['google-physical'] = array('OpenLayers.Layer.Google( "Google Physical", {type: G_PHYSICAL_MAP , "sphericalMercator":true} )', 'google');
$egMapsOLLayerGroups['google'] = array('google-normal', 'google-satellite', 'google-hybrid', 'google-physical');
$egMapsOLLayerDependencies['google'] = "<script src='http://maps.google.com/maps?file=api&amp;v=2&amp;key=$egGoogleMapsKey&amp;hl={}' type='$wgJsMimeType'></script><script type='$wgJsMimeType' src='$egMapsScriptPath/GoogleMaps/GoogleMapFunctions.min.js?$egMapsStyleVersion'></script><script type='$wgJsMimeType'>window.unload = GUnload;</script>";

This will make these values available:

• google - All available Google Maps map types
  • google-normal - Google streets
  • google-satellite - Google satellite
  • google-hybrid - Google hybrid
  • google-physical - Google physical

Defining your own layers

Since Maps 0.5.4, you can define your own layers. This is done by adding extra values to $egMapsOLAvailableLayers, $egMapsOLLayerGroups and $egMapsOLLayerDependencies in your LocalSettings file. See the demo's for several examples and a collection of already defined custom layers you can use. Please add your own layers there, so other people can also use them. They might even end up in Maps core if they are requested by multiple users.

In most cases, you'll just need to add a single line, setting a new value for egMapsOLAvailableLayers. This line can be obtained by looking at the source of the page containing a map that has the layer you also want to use. It'll contain an assignment, like for example

somevar = new OpenLayers.Layer.OSM("Öpnv Deutschland", "http://tile.xn--pnvkarte-m4a.de/tilegen/${z}/${x}/${y}.png", {numZoomLevels: 19,displayInLayerSwitcher:false,buffer:0});

You need this part from it (basically the thing that's being assigned, without the 'new' keyword and semicolon at the end)

OpenLayers.Layer.OSM("Öpnv Deutschland", "http://tile.xn--pnvkarte-m4a.de/tilegen/${z}/${x}/${y}.png", {numZoomLevels: 19,displayInLayerSwitcher:false,buffer:0})

Your layer definition in LocalSettings should then look similar to this, where 'german-layer' is the layer name you'll need to enter to get this layer on your map.

$egMapsOLAvailableLayers['german-layer'] = array('OpenLayers.Layer.OSM("Öpnv Deutschland", "http://tile.xn--pnvkarte-m4a.de/tilegen/${z}/${x}/${y}.png", {numZoomLevels: 19,buffer:0})');

As you can see, I removed displayInLayerSwitcher:false, which would prevent the layer from showing up in the layer switcher. You can of course retain this if it's the desired effect. Also note that you can change the name of the layer (as displayed in the layer switcher), by changing the value which is here "Öpnv Deutschland".

If you want to create more complex custom layers, and do not have the JS/PHP experience to figure out how yourself, or otherwise have problems creating your own custom layers, just give me a poke, and I'll help you out -- Jeroen De Dauw

Controls

Parameter: controls=

Available values: See the OpenLayers docs (the items in the menu on the left).

This parameter sets the controls that will be added to your OpenLayers map. You can add as many of the controls you want, by separating them with comma's. You can also configure the default controls (the ones that will be added when no value is provided) in the settings file.

See the OpenLayers docs for a list of available controls and their descriptions. Note that the value of the controls parameter is case insensitive, so it doesn't matter if you use capitals or only lower case letters.

Since 0.4, Maps supports the 'autopanzoom' control. When you specify this control, Maps will automatically determine if panzoom, panzoombar, or no control should be used, depending on the maps height.

Example of how to use this parameter:

controls=autopanzoom,scaleline,overviewmap,keyboarddefaults

OpenLayers layers

The default layers for OpenLayers. This value will only be used when the user does not provide one. See the layers parameter for the available values.

Default: $egMapsOLLayers = array('openlayers');

OpenLayers controls

The default controls for OpenLayers. This value will only be used when the user does not provide one. See the controls parameter for the available values.

Default: $egMapsOLControls = array('layerswitcher', 'mouseposition', 'panzoombar', 'scaleline', 'navigation');

Default map zoom

The default zoom of an OpenLayers map. This value will only be used when the user does not provide one.

Default: $egMapsOpenLayersZoom = 10;

Map name prefix

The OpenLayers map name prefix. It can not be identical to the one of another mapping service. Unless you know what you are doing, it's discouraged to modify this value.

Default: $egMapsOpenLayersPrefix = 'open_layer';

Leaflet

Parameters

Parameter	Type	Default	Description
zoom	whole number	no	The zoom level for the map. For maps with markers this will default to the most zoomed in level that still shows all markers.
width	number and dimensional unit	auto	Allows setting the width of the map. By default pixels will be assumed as unit, but you can explicitly specify one of these units: px, ex, em, %.
height	number and dimensional unit	350	Allows setting the height of the map. By default pixels will be assumed as unit, but you can explicitly specify one of these units: px, ex, em.
centre	text	no	The location on which the map should be centered
title	text	empty	Allows setting text that will be displayed in the pop-ups of all markers that do not have a specific title. When used together with label, the title will be bold and underlined.
label	text	empty	Allows setting text that will be displayed in the pop-ups of all markers that do not have a specific label.
icon	text	empty	Allows setting the icon used for all markers.
lines	List of lines	empty	Lines to display
polygons	List of geographical polygons	empty	Polygons to display
circles	List of circles	empty	Circles to display
rectangles	List of rectangles	empty	Rectangles to display
maxzoom	whole number	no	The maximum zoom level
minzoom	whole number	no	The minimum zoom level
copycoords	yes/no	no	Show a dialog when clicking on a location from which its coordinates may be copied
static	yes/no	no	Make the map static
defzoom	whole number	14	Allows setting the default zoom level of the map.
layers	list of texts	OpenStreetMap	The layers that will be available in the layer selector. The first layer will be shown when the map loads.
image layers	list of texts	empty	Image base layers. The first layer will be shown by default. If any images are specified, they will be used instead of the regular map layers.
overlays	list of texts	empty	The overlay layers that will be shown when the map loads.
resizable	yes/no	no	Makes the map resizable by dragging at its lower right corner.
fullscreen	yes/no	no	Enable fullscreen button
scrollwheelzoom	yes/no	yes	Indicates if mouse scrolling should be enabled or not.
cluster	yes/no	no	Allows merging of multiple nearby markers into one marker
clustermaxzoom	whole number	20	The maximum zoom level where clusters may exist.
clusterzoomonclick	yes/no	yes	Whether the default behaviour of clicking on a cluster is to zoom into it.
clustermaxradius	whole number	80	The maximum radius that a cluster will cover.
clusterspiderfy	yes/no	yes	When you click a cluster at the bottom zoom level we spiderfy it so you can see all of its markers.
geojson	text	empty	URL of a file or name of the page containing GeoJSON data
clicktarget	text	empty	When clicking on the map you will be send to this URL. %lat% is replaced by the latitude and %long% by the longitude

Also take a look at the Category:Maps examples for Leaflet.

Settings

Default map zoom

The default zoom of a Leaflet map. This value will only be used when the user does not provide one.

Default: $GLOBALS['egMapsLeafletZoom'] = 14;

Default Layer

The default layer to be used for a Leaflet map. This value will only be used when the user does not provide one. Supported Layers are defined in Available Layers.

Default: $GLOBALS['egMapsLeafletLayer'] = 'OpenStreetMap';

Default overlay Layers

The default overlay Layers to be used for a Leaflet map. This value will only be used when the user does not provide one. Supported overlay Layers are defined in Available overlay Layers.

Default: $GLOBALS['egMapsLeafletLayer'] = 'OpenStreetMap';

Available Layers

The available layers that can be set in Default Layer Setting or via layer parameter for a Leaflet map. Layers can be deactivated by setting them to false or removing them. This list of layers comes from the Leaflet extension leaflet-providers, to extend it leaflet-providers needs to be extended.

Default: $GLOBALS['egMapsLeafletAvailableLayers'] = [ 'OpenStreetMap' => true, 'OpenStreetMap.DE' => true, 'OpenStreetMap.BlackAndWhite' => true, 'OpenStreetMap.HOT' => true, 'OpenTopoMap' => true, 'Thunderforest.OpenCycleMap' => true, 'Thunderforest.Transport' => true, 'Thunderforest.TransportDark' => true, 'Thunderforest.SpinalMap' => true, 'Thunderforest.Landscape' => true, 'Thunderforest.Outdoors' => true, 'Thunderforest.Pioneer' => true, 'OpenMapSurfer.Roads' => true, 'OpenMapSurfer.Grayscale' => true, 'Hydda.Full' => true, 'Hydda.Base' => true, //'MapBox' => false, // todo: implement setting api key 'Stamen.Toner' => true, 'Stamen.TonerBackground' => true, 'Stamen.TonerHybrid' => true, 'Stamen.TonerLines' => true, 'Stamen.TonerLabels' => true, 'Stamen.TonerLite' => true, 'Stamen.Watercolor' => true, 'Stamen.Terrain' => true, 'Stamen.TerrainBackground' => true, 'Stamen.TopOSMRelief' => true, 'Stamen.TopOSMFeatures' => true, 'Esri.WorldStreetMap' => true, 'Esri.DeLorme' => true, 'Esri.WorldTopoMap' => true, 'Esri.WorldImagery' => true, 'Esri.WorldTerrain' => true, 'Esri.WorldShadedRelief' => true, 'Esri.WorldPhysical' => true, 'Esri.OceanBasemap' => true, 'Esri.NatGeoWorldMap' => true, 'Esri.WorldGrayCanvas' => true, 'MapQuestOpen' => true, //'HERE' => false, // todo: implement setting api key 'FreeMapSK' => true, 'MtbMap' => true, 'CartoDB.Positron' => true, 'CartoDB.PositronNoLabels' => true, 'CartoDB.PositronOnlyLabels' => true, 'CartoDB.DarkMatter' => true, 'CartoDB.DarkMatterNoLabels' => true, 'CartoDB.DarkMatterOnlyLabels' => true, 'HikeBike.HikeBike' => true, 'HikeBike.HillShading' => true, 'BasemapAT.basemap' => true, 'BasemapAT.grau' => true, 'BasemapAT.overlay' => true, 'BasemapAT.highdpi' => true, 'BasemapAT.orthofoto' => true, 'NASAGIBS.ModisTerraTrueColorCR' => true, 'NASAGIBS.ModisTerraBands367CR' => true, 'NASAGIBS.ViirsEarthAtNight2012' => true, 'NLS' => true ];

Available overlay Layers

The available overlay layers that can be set in Default overlay Layers Setting or via overlaylayers parameter for a Leaflet map. Layers can be deactivated by setting them to false or removing them. This list of layers comes from the Leaflet extension leaflet-providers, to extend it leaflet-providers needs to be extended.

Default: $GLOBALS['egMapsLeafletAvailableOverlayLayers'] = [ 'OpenMapSurfer.AdminBounds' => true, 'OpenSeaMap' => true, 'OpenWeatherMap.Clouds' => true, 'OpenWeatherMap.CloudsClassic' => true, 'OpenWeatherMap.Precipitation' => true, 'OpenWeatherMap.PrecipitationClassic' => true, 'OpenWeatherMap.Rain' => true, 'OpenWeatherMap.RainClassic' => true, 'OpenWeatherMap.Pressure' => true, 'OpenWeatherMap.PressureContour' => true, 'OpenWeatherMap.Wind' => true, 'OpenWeatherMap.Temperature' => true, 'OpenWeatherMap.Snow' => true, 'Hydda.RoadsAndLabels' => true, 'NASAGIBS.ModisTerraLSTDay' => true, 'NASAGIBS.ModisTerraSnowCover' => true, 'NASAGIBS.ModisTerraAOD' => true, 'NASAGIBS.ModisTerraChlorophyll' => true ];

Layers API Keys

Some Layers are only available with the use of API keys.

Default: $GLOBALS['egMapsLeafletLayersApiKeys'] = [ 'MapBox' => , 'MapQuestOpen' => , ];

Layers Dependencies

Some Layers are only available with a layer dependency loaded.

Default: $GLOBALS['egMapsLeafletLayerDependencies'] = [ 'MapQuestOpen' => 'https://open.mapquestapi.com/sdk/leaflet/v2.2/mq-map.js?key=', ];