Installation: Difference between revisions

From Maps for MediaWiki
(Created page with "Maps is installed and upgraded via Composer. For a detailed explanation see [https://www.mediawiki.org/wiki/Composer/For_extensions installing MediaWiki extensions with Compos...")
 
mNo edit summary
(9 intermediate revisions by the same user not shown)
Line 1: Line 1:
Maps is installed and upgraded via Composer. For a detailed explanation see [https://www.mediawiki.org/wiki/Composer/For_extensions installing MediaWiki extensions with Composer].
This page is for wiki administrators that want to install the Maps extension. This is only possible with server access.


'''In short:'''
== Installation ==


* Edit the "composer.local.json" file by adding <code>mediawiki/maps</code> to the <code>require</code> section
Maps is installed using [https://getcomposer.org/ Composer] with [https://www.mediawiki.org/wiki/Composer MediaWiki's built-in support for Composer].
* Choose the version constraint. Typically you want to pick <code>^x.y</code>, where <code>x.y</code> is the latest minor version of Maps receiving only backwards-compatible code changes
* Run <code>composer update --no-dev -o</code> in the MediaWiki root directory


=== Step 1/2: composer update ===


For upgrading, edit the "composer.local.json" file and update the version constraint.
On the command line, go to the base directory of your MediaWiki installation.


Example of a <code>require</code> section just with Maps:
If you are using MediaWiki 1.35 or later and PHP 7.4 or later, run the following two commands:


<syntaxhighlight lang="json">
<syntaxhighlight lang="bash">
    "require": {
COMPOSER=composer.local.json composer require --no-update mediawiki/maps:~9.0
        "mediawiki/maps": "^7"
 
    }
composer update mediawiki/maps --no-dev -o
</syntaxhighlight>
</syntaxhighlight>


If you would also like to make use of the semantic functionality Maps provides you also need to [[Help:Installation|install Semantic MediaWiki]]. In this case the example <code>require</code> section with both Maps and Semantic MediaWiki looks like this:
If you are using MediaWiki 1.35 or later with PHP 7.3, run the following two commands instead:
 
<syntaxhighlight lang="bash">
COMPOSER=composer.local.json composer require --no-update mediawiki/maps:~8.0


<syntaxhighlight lang="json">
composer update mediawiki/maps --no-dev -o
    "require": {
        "mediawiki/maps": "^7",
        "mediawiki/semantic-media-wiki": "^3.0"
    }
</syntaxhighlight>
</syntaxhighlight>


You will need a comma behind each version constraint except the last one.
If you are using an older version of MediaWiki or of PHP, then run these two commands instead:
 
Then run <code>composer update --no-dev -o</code>.


As of Maps version 6.0, you need to load the extension in your "LocalSettings.php" file. This is done using the standard MediaWiki extension loading method:
<syntaxhighlight lang="bash">
COMPOSER=composer.local.json composer require --no-update mediawiki/maps:~7.0


<syntaxhighlight lang="php">
composer update mediawiki/maps --no-dev -o
wfLoadExtension( 'Maps' );
require_once __DIR__ . '/extensions/Maps/Maps_Settings.php';
</syntaxhighlight>
</syntaxhighlight>


This is an example of what your "LocalSettings.php" file might look like:
=== Step 2/2: modify LocalSettings.php ===


<syntaxhighlight lang="php">
Add the following line to the end of your "LocalSettings.php" file:
## Maps
wfLoadExtension( 'Maps' );
require_once __DIR__ . '/extensions/Maps/Maps_Settings.php';
$egMapsDefaultService = 'leaflet'; // Not required, just an example for adding configuration
</syntaxhighlight>


This is an example of a "LocalSettings.php" file with both Maps and Semantic MediaWiki:
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="php">
## Maps
wfLoadExtension( 'Maps' );
wfLoadExtension( 'Maps' );
require_once __DIR__ . '/extensions/Maps/Maps_Settings.php';
$egMapsDefaultService = 'leaflet';
## Semantic MediaWiki
enableSemantics( 'example.org' );
</syntaxhighlight>
</syntaxhighlight>


== Verify installation success ==
=== Verify installation success ===


As final step, you can verify Maps got installed by looking at the Special:Version page on your wiki and verifying the Maps extension is listed.
Check the "Special:Version" page on your wiki. If it lists Maps, then installation was successful.


== Configuration ==
== Configuration ==


Maps works out of the box without any configuration work being required. Below are some key configuration options that you might want to change. For a comprehensive overview of all settings, see [[Maps/Configuration|Maps Configuration]].
Maps works out of the box without any configuration work being required. Below are some key configuration options that you might want to change. For a comprehensive overview of all settings, see [[Configuration|the configuration overview]].


=== Mapping service ===
=== Mapping service ===
Line 84: Line 66:
=== Geocoding service ===
=== Geocoding service ===


The Maps extension supports [[Maps/Geocoding|geocoding]], the conversion of human readable addresses to coordinates. This is done via a webservice used for each map displayed on your wiki. By default Maps uses [https://wiki.openstreetmap.org/wiki/Nominatim Nominatim]. To use a different geocoding service, use the <code>$egMapsDefaultGeoService</code>.
The Maps extension supports [[Geocoding|geocoding]], the conversion of human readable addresses to coordinates. This is done via a webservice used for each map displayed on your wiki. By default Maps uses [https://wiki.openstreetmap.org/wiki/Nominatim Nominatim]. To use a different geocoding service, use the <code>$egMapsDefaultGeoService</code>.


<syntaxhighlight lang="php">
<syntaxhighlight lang="php">
Line 90: Line 72:
</syntaxhighlight>
</syntaxhighlight>


== Upgrading ==
== Alternative installation methods ==
 
=== Semantic Bundle ===
 
Maps is included in Semantic Bundle, an extension package build around [[Semantic MediaWiki]]. To install Maps via Semantic Bundle, follow the [https://github.com/ProfessionalWiki/SemanticBundle#semantic-bundle Semantic Bundle installation instructions] rather than the ones on this page.
 
=== Installation without shell access ===
 
See https://www.mediawiki.org/wiki/Topic:Voivcvsg48plvx9u


When upgrading from Maps older than 6.0 to Maps 6.0 or later, you will need to load Maps in your "LocalSettings.php" file. This is done using the standard MediaWiki extension activation method. If you are using customized settings, you will also need to include the default settings. See [[Maps/Configuration|the configuration instructions]]. See the examples shown above for installing this extension.
This method is not officially supported.


== Platform compatibility ==
=== Professional Hosting ===


See the [https://github.com/JeroenDeDauw/Maps/blob/master/INSTALL.md#platform-compatibility-and-release-status compatibility table on GitHub].
The maintainers of the Maps extension provide commercial [https://professional.wiki/en/hosting fully managed MediaWiki hosting].

Revision as of 22:45, 29 July 2021

This page is for wiki administrators that want to install the Maps extension. This is only possible with server access.

Installation

Maps is installed using Composer with MediaWiki's built-in support for Composer.

Step 1/2: composer update

On the command line, go to the base directory of your MediaWiki installation.

If you are using MediaWiki 1.35 or later and PHP 7.4 or later, run the following two commands:

COMPOSER=composer.local.json composer require --no-update mediawiki/maps:~9.0

composer update mediawiki/maps --no-dev -o

If you are using MediaWiki 1.35 or later with PHP 7.3, run the following two commands instead:

COMPOSER=composer.local.json composer require --no-update mediawiki/maps:~8.0

composer update mediawiki/maps --no-dev -o

If you are using an older version of MediaWiki or of PHP, then run these two commands instead:

COMPOSER=composer.local.json composer require --no-update mediawiki/maps:~7.0

composer update mediawiki/maps --no-dev -o

Step 2/2: modify LocalSettings.php

Add the following line to the end of your "LocalSettings.php" file:

wfLoadExtension( 'Maps' );

Verify installation success

Check the "Special:Version" page on your wiki. If it lists Maps, then installation was successful.

Configuration

Maps works out of the box without any configuration work being required. Below are some key configuration options that you might want to change. For a comprehensive overview of all settings, see the configuration overview.

Mapping service

The Maps extension supports displaying maps using multiple mapping services, including Google Maps, Leaflet and OpenLayers. At present the default is Leaflet, while in older versions of the extension it was Google Maps.

If you do not wish to use the default, use the $egMapsDefaultService configuration parameter. Examples:

  • For Google Maps:
    $egMapsDefaultService = 'googlemaps3';
    
  • For Leaflet:
    $egMapsDefaultService = 'leaflet';
    

When using Google Maps, you will need to provide your Google API key:

$egMapsGMaps3ApiKey = 'your-api-key';

Geocoding service

The Maps extension supports geocoding, the conversion of human readable addresses to coordinates. This is done via a webservice used for each map displayed on your wiki. By default Maps uses Nominatim. To use a different geocoding service, use the $egMapsDefaultGeoService.

$egMapsDefaultGeoService = 'google';

Alternative installation methods

Semantic Bundle

Maps is included in Semantic Bundle, an extension package build around Semantic MediaWiki. To install Maps via Semantic Bundle, follow the Semantic Bundle installation instructions rather than the ones on this page.

Installation without shell access

See https://www.mediawiki.org/wiki/Topic:Voivcvsg48plvx9u

This method is not officially supported.

Professional Hosting

The maintainers of the Maps extension provide commercial fully managed MediaWiki hosting.