Changes

Jump to: navigation, search

Maps

14,288 bytes removed, 07:48, March 31, 2010
Maps has support for English, Afrikaans, Arabic, Belarusian, Bulgarian, Breton, Bosnian, Catalan, German, Lower Sorbian, Greek, Spanish, Basque, Finnish, French, Friulian, Galician, Swiss German, Hebrew, Croatian, Upper Sorbian, Hungarian, Interlingua, Indonesian, Japanese, Ripoarisch, Luxembourgish, Macedonian, Dutch, Occitan, Polish, Piedmontese, Portuguese, Brazilian Portuguese, Romanian, Tarandíne, Russian, Slovak, Swedish, Thai, Vietnamese and others.
 
== Usage ==
 
=== Coordinates ===
 
Maps supports several coordinate notations, which you can use to display points, set the centre of maps, and more:
 
* Floats: <code>55.7557860, 37.6176330</code>
* DMS: <code>55°45′06″N 37°37′04″E</code>
* DD: <code>55.7557860°, 37.6176330°</code> or <code>55.7557860° N, 37.6176330° E</code>
* DM: <code>55°45.34716', 37°37.05798'</code>
 
=== Geocoding ===
 
Since people work with addresses instead of coordinates, [http://en.wikipedia.org/wiki/Geocoding geocoding] functionality is included in Maps. This means Maps will convert a human readable address to a set of coordinates. This functionality is based on the [[Extension:Google_Geocoder|Google Geocoder]] extension, which, if installed, you will need to un-install before using Maps.
 
You can geocode an address with the #geocode parser function. The underneath code will return the coordinates of Moscow.
 
<pre>{{#geocode:Moscow, Russia}}</pre>
 
Result:
 
<pre>55.7557860, 37.6176330</pre>
 
For more examples, see [http://wiki.bn2vs.com/wiki/Geocode here].
 
In most cases, you will want to do something like displaying a map of New York, or indicating a couple of streets somewhere. Maps has build in support for those, and will automatically recognize addresses from coordinates, allowing automatic geocoding, without the need for the #geocode parser function. This behaviour is explained further in the relevant sections of the documentation.
 
==== Geocoding service ====
 
Maps allows you to use multiple geocoding services. Both the [[#Available_geocoding_services|available geocoding services]] as the [[#Default_geocoding_service|default geocoding service]] are settings, and can be modified. If you don't want to use the default service, you can specify it in the parser function.
 
The #geocode parser function accepts a second argument, like shown below:
<pre>
{{#geocode:Moscow, Russia|yahoo}}
</pre>
 
In some cases, the default geocoding service will be overridden with another value.
* In a display_map/display_point(s) Google Maps map: google will be used as the default
* In a display_map/display_point(s) Yahoo! Maps map: yahoo will be used as the default
 
This only overrides the default geocoding service that's used when no service is provided in the parser function.
 
====Legal warning====
Both the Google and Yahoo! geocoding services have a licence that ''prohibits their use for anything that is not directly related to their associated mapping services'', unless you have written permission. You are encouraged to read the service's licences ([http://code.google.com/apis/maps/documentation/geocoding/#Geocoding Google], [http://info.yahoo.com/legal/us/yahoo/maps/mapsapi/mapsapi-2141.html Yahoo!]) before using them.
 
The underneath examples are in violation of the relevant licences in most cases:
 
<pre>
{{
#display_point:
Moscow, Russia
|service=google
|geoservice=yahoo
}}
</pre>
 
<pre>
{{
#display_point:
{{geocode:Moscow, Russia|google}}
|service=yahoo
}}
</pre>
 
=== Displaying a map ===
 
* [http://ext.bn2vs.com/screencasts/maps_display_map.htm Watch display_map screencast (1.27MB)]
 
Maps enables you to display a map by using the #display_map [[Parser_function|parser function]]. Such a map will centre itself around a provided location, which can be a set of coordinates, or an address. In the later case, it will be automatically geocoded. You do not need to specify if the provided value is a set of coordinates or an address, this will be automatically determined.
 
The following code will result in a map of moscow.
 
<pre>{{#display_map: Moscow}}</pre>
Or
<pre>{{#display_map: 55°45′06″N 37°37′04″E}}</pre>
 
The above examples demonstrate the use of addresses and DMS coordinates. You can also use the other supported [[#Coordinates|coordinate notations]].
 
You can further customize your map by adding additional [[#Map_properties|map properties]].
 
=== Displaying points ===
 
* [http://ext.bn2vs.com/screencasts/maps_display_point.htm Watch display_point screencast (4,24MB)]
 
==== One point ====
 
[[File:Maps-3d-small.png|thumb|right|Maps indicating Moscow on a Google Earth map.]]
 
You can display a map with a marker on it with the #display_point or #display_points [[Parser_function|parser functions]]. By default, the map will centre itself around the provided point, which can be a set of coordinates, or an address. In the later case, it will be automatically geocoded. You do not need to specify if the provided value is a set of coordinates or an address, this will be automatically determined. The underneath code will result in a map on which the city centre of Moscow is indicated.
<pre>
{{#display_point: Moscow}}
</pre>
Or
<pre>
{{#display_point: 55.7557860, 37.6176330}}
</pre>
 
The above examples demonstrate the use of addresses and floating point coordinates. You can also use the other supported [[#Coordinates|coordinate notations]]. Also note that there is no difference between the use of display_point and display_points. These functions are completely synonymous.
 
The usage of display_address has been deprecated since version 0.4. For backward compatibility, it is currently synonymous to display_point, but this will be removed at some point.
 
You can further customize your map by adding additional [[#Map_properties|map properties]].
 
==== Multiple points ====
 
[[File:Maps-pf-ol-osm-cycle-multimarker.jpg|thumb|400px|right|An OpenLayers map with multiple markers on the OpenStreetMap cycle layer.]]
 
When you want to display multiple points on a Map, you can do this by adding them to a #display_point or #display_points [[Parser_function|parser function]]. Both accept a list of points, that can contain both coordinates and addresses, in which each item is separated by a ';'. Underneath example demonstrates how you can create a map with multiple points indicated:
 
<pre>
{{#display_points:55°45′06″N 37°37′04″E; New York; 40.446195, -79.948862}}
</pre>
 
The usage of display_addresses has been deprecated since version 0.4. For backward compatibility, it is currently synonymous to display_points, but this will be removed at some point.
 
You can further customize your map by adding additional [[#Map_properties|map properties]].
 
==== Point specific data ====
 
[[File:Maps0.5.2-google-earth-colored-pins.gif|thumb|400px|right|A Google Earth map with several markers using custom icons.]]
 
Maps allows you to specify point specific data. In other words, you can have different po-pups and icons for different markers.
 
There are 3 marker specific parameters. They are unnamed, meaning you notate them as ''value'', not ''name=value'', and therefore have a '''fixed order'''. Each parameter is separated by '~'. This is the correct order of the 3 parameters: coordinates or address, (optional) title, (optional) label, (optional) icon. Both title and label will use the value of their general, non marker specific, parameter, when it's set . This example demonstrate the parameters usage:
 
<pre>
{{
#display_points:
Moscow, Russia~Moscow~A city in Russia; New York~New York city; London~London~Capital of England~green-marker.png;Brussels
}}
</pre>
 
* <code>Moscow, Russia~Moscow~A city in Russia</code>: The address is followed by a title (Moscow), and a label (A city in Russia), and will therefore display a marker with both values.
* <code>New York~New York city</code>: This address only has a title parameter (New York city), and will not have any label, unless either <code>title=</code> or <code>label=</code> parameters are provided.
* <code>London~London~Capital of England~green-marker.png</code>: This address has all 3 parameters, and will display a pop-up with it's own title, it's own text, and will have it's own marker (an image with the name green-marker.png).
* <code>Brussels</code>: This address does not have any specific parameters, and therefore will use the default marker icon, and won't display any pop-up, unless either <code>title=</code> or <code>label=</code> parameters are provided.
 
This is a stripped down example of one point and it's related data:
 
<pre>
Address~Title~Label~Icon
</pre>
 
=== Static maps ===
 
As of version 0.5, Maps supports static maps. Static maps are maps in the form of plain images, in contrast to dynamic maps, which reside in a JavaScript mapping API, and allow you to interact in various ways. Working with static maps has several advantages over dynamic maps, including the fact that users don't need to have a client that support JavaScript to view the map.
 
You can specify whether a map should be static with the 'static' parameter, and if the user should be able to activate it by clicking it, so it turns into a dynamic map, with the 'activatable' parameter. You can find several examples of static maps [http://wiki.bn2vs.com/wiki/Static_map here].
 
At the moment, only this functionality is only supported for display_map with the OSM service. See the [[Extension:Maps/OSM#OpenStreetMap_specific_properties|OSM specific map properties]] for more info.
 
=== Map services ===
 
[[File:Maps-openlayers-multilayer-with-marker.gif|thumb|400px|right|Maps displaying an OpenLayers map with multiple base layers.]]
 
Maps provides multiple mapping services. The map service for a certain map can be set with the <code>service</code> parameter. When the service is omitted, [[#Default_mapping_service|the default service]] will be used. The underneath list contains the available mapping services.
{{Maps Extension Services Table}}
 
[[File:Maps-gmap-physical-marker-popup-text.gif|thumb|400px|right|Maps displaying a Google Maps map with physical map type and a marker with pop-up.]]
 
When no service is provided, [[#Default_mapping_service|the default service]] will be used.
 
=== Map properties ===
 
All map-display parser functions in Maps (display_map and display_point(s)) accept a number of map properties (also referred to as parameters). These properties can be altered to change the appearance and usage of the resulting map. Each property has a specific usage, as listed in the underneath table.
 
Both display_map and display_point(s) have a default property. This is the only value you can pass along without specifying the property name (like width=300). For display_map this is the coordinate or address representing the maps centre. For display_point(s) this is the list of points.
 
Some of the properties have aliases. This means they can be set using multiple names. An example for this is the ''center'' alias, which will have the exact same result as when using ''centre''. All aliases are listed in the underneath table.
 
{| class="wikitable sortable" style="margin: 1em auto 1em auto"
! width=90px | Property || Usage || Aliases || Default || width=90px | Version
|-
| coordinates, address(es), 'nameless' || Holds the maps centre for display_map or the list of points for display_point(s). Depending on which name you provide for this parameter, the values will be treated differently.
* Default (nameless) parameter: Maps will determine if a value is a coordinate or not. When it isn't a coordinate, it'll be geocoded.
* Coordinates: Maps will only accept valid coordinates, and reject all addresses.
* Address(es): Maps will treat every value as an address, and geocode it, even when it's an address.
|| coords, location, locations || align="center" | [[#Default_map_coordinates|configurable]] || align="center" | Changed in 0.4.2
|-
| service || Allows to set the mapping service that will be used to generate the map. || align="center" | - || align="center" | [[#Default_mapping_service|configurable]] || align="center" | -
|-
| geoservice || Allows to set the geocoding service used to turn addresses into coordinates in the display_map and display_point(s) parser functions. || align="center" | - || align="center" | [[#Default_geocoding_service|configurable]] || align="center" | Added in 0.2
|-
| width || Allows to set the width of the map, in pixels. || align="center" | - || align="center" | [[#Default_map_width|configurable]] || align="center" | -
|-
| height ||Allows to set the height of the map, in pixels. || align="center" | - || align="center" | [[#Default_map_height|configurable]] || align="center" | -
|-
| 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. || align="center" | - || align="center" | [[#Default_map_zoom|configurable]] or auto-detect || align="center" | Changed in 0.3
|-
| centre || Allows to set the coordinates of the map's centre for display_point(s). Accepts both addresses and coordinates. When this property is not provided, the map will centre itself on the provided marker, or between the provided markers. || align="center" | center || align="center" | [[#Default_map_coordinates|configurable]] or auto-detect || align="center" | Changed in 0.4
|-
| title || Allows to set text that will be displayed in the pop-ups of all markers that do not have a specific title. When used together with <code>label</code>, the title will be bold and have a line under it. || align="center" | - || align="center" | empty || align="center" | Changed in 0.4
|-
| label || Allows to set text that will be displayed in the pop-ups of all markers that do not have a specific label. || align="center" | - || align="center" | empty || align="center" | Changed in 0.4
|-
| icon || Allows you to set the icon used for all markers. || align="center" | - || align="center" | Default mapping service marker || align="center" | Added in 0.5.2
|}
 
Example of a Yahoo! Maps map with several optional parameters.
<pre>
{{
#display_points:
service=yahoomaps
|address=Moscow, Russia; New York City
|zoom=7
|width=800
|height=500
}}
</pre>
 
Since each mapping service has it's own unique features, they also have properties specific to them. See the relevant sub page of this article for the list of a service's specific properties.
 
{{Maps Extension Services}}
 
==== Property validation ====
 
As of 0.5, Maps supports error feedback. There is a setting, located in [[Extension:Validator|Validator]], that indicates in which situations errors should be shown, and how extensive they should be, see [[Extension:Validator#Error_level|Validator error levels]].
==Settings==