Extension:Maps

Maps is an extension that provides the ability to display coordinate data, using multiple mapping services, including Google Maps, Open Layers and Yahoo Maps, and allows users to geocode addresses. It can be used together with Semantic Maps, which adds semantic capabilities to the mapping services, but can also be used without it on non-semantic wiki's. Both Maps and Semantic Maps are based on Semantic Google Maps and Semantic Layers, and are meant to replace those extensions. Maps contains all functionality of Google Geocoder, and so also replaces this extension.

Download and installation
Once you have downloaded the code, place the 'Maps' directory within your MediaWiki 'extensions' directory. Then add the following code to your LocalSettings.php file after the line that installs Semantic MediaWiki:

For using Google Maps or Yahoo! Maps, you must enter their API keys in the settings file. If you don't already have them, you can obtain them at the Google Maps API page and Yahoo Maps API page. Note that the Google Maps API key is required for both displaying maps AND for geocoding (and therefore also required when you use display_address with a Yahoo! Map). Also note that use of the Google Maps API is free only if your site is accessible to the public; otherwise it costs money - read the Google Maps terms of service for further details.

Display a single point
You can display a map with a marker on it with the #display_point parser function. The following code will display a marker on the default map type (Google Maps), at the provided coordinates.

Geocoding
To make it easier to display a marker on an address, geocoding functionality is included in Maps. Note that currently this is done with the Google Geocoding service, but more geocoding services will be added after the initial release, which you will then be able to specify with a  parameter. You can geocode an address with the #geocode parser function. The underneath code will return the coordinates of Moscow.

This can be easily nested in the #display_point parser function, like demonstrated below.

To avoid this nesting, another parser function, #display_address, is also available. This parser function is completely identical to #display_point, except for the parameter address, which replaces coordinates, and automatically does the geocoding for you. This code is completely synonymous to the previous example.

Map services
Maps provides multiple mapping services. The map service for a certain map can be set with the  parameter. The underneath list contains the available mapping services. When no service is provided, the default service will be used.
 * or  - Google Maps service.
 * or  - Yahoo Maps service.
 * or  - Open Layers service.

'''Each service has it's own unique functionality. Click the service name above for an overview of these features.''' See the list below for the common properties.

Map properties
Both the #display_point and #display_address parser functions accept the following list of map properties, which can be altered to change the appearance and usage of the resulting map. This list contains only the common properties, in other words, the properties that can be used for every mapping service. For the specific properties, see the map services.
 * - (display_point only) the coordinates to display a marker and also the centre of the map - you can set the default
 * - (display_address only) the address to display a marker and also the centre of the map
 * - the width of the map, in pixels - you can set the default
 * - the height of the map, in pixels - you can set the default
 * - the zoom level of the map - you can set the default

Example of a Yahoo! Map:

Settings
Maps allows you to configure a variety of settings, and so affect how the extension works. All settings are located in Maps_Settings.php, in the root of the extension. Here you have a list of the common settings (the ones that affect all mapping services). For the specific settings, see the map services. Note that the settings file is documented, and should provide you with sufficient information to understand the working of all settings.

Available mapping services
Array containing all the services that will be made available to the user. Currently Maps provides the following services: googlemaps, yahoomaps, openlayers.

Default mapping service
The default mapping service, which will be used when no service is provided by the user. This service needs to be enabled, if not, the first one from the available services will be taken.

Default map coordinates
The default coordinates of the marker. This value will only be used when the user does not provide one.

Default map width
The default width of a map. These values will only be used when the user does not provide them

Default map height
The default height of a map. These values will only be used when the user does not provide them.

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

Version
Maps is currently at version 0.1, the first public release. It should still be considered beta, since issues are to be expected. However, it has been tested quite thoroughly, and should not cause any big problems. An update to this version can be expected within a few weeks, adding more functionality, fixing bugs and improving the overall extension structure.

Changelog
Version 0.1 (2009-07-20)


 * Initial release, featuring Google Maps (+ Google Earth), Yahoo! Maps and Open Layers mapping services

Bugs and feature requests
If you have bug reports or requests, please add them to the Talk page. You can also send them to Jeroen De Dauw, jeroendedauw -at- gmail.com, and Yaron Koren, at yaron57 -at- gmail.com.

Who's using Maps?
Are you using Maps? Then be sure to add your wiki to the top of this list, and feel free to link your favourite Maps-using articles!
 * BN's dev wiki Development wiki with some demo data