Wikibase/Installation/Advanced configuration

Introduction

This page describes advanced configuration for Wikibase's Client and Repository. If you haven't yet installed Wikibase, first consult the installation instructions.

Making changes to the client and repository configurations involves adding or changing $wgWBClientSettings or $wgWBRepoSettings lines (respectively) in the MediaWiki LocalSettings.php file. This document covers only some options; for an exhaustive list, consult full documentation (defaults: client settings file and repo settings file ).

Note that the prefix "wg" in $wgWBRepoSettings is distinct from that of other extensions, which may use the prefix $eg. The difference is important; your configuration will fail if you use a different prefix.

The parameters you set in LocalSettings.php override those found in the aforementioned files. Place any configuration settings you wish to override at the bottom of your LocalSettings.php file.

Example:

$wgWBRepoSettings['dataRightsUrl'] = 'https://creativecommons.org/publicdomain/zero/1.0/';

The line above sets the parameter dataRightsUrl of the Wikibase Repository (because $wgWBRepoSettings) to the value https://creativecommons.org/publicdomain/zero/1.0/.

Using only the client or the repository

Under some circumstances you may wish to use only the client or only the repository code.

Repository only

Versions 1.36 and above use extension registration:

wfLoadExtension( 'WikibaseRepository', "$IP/extensions/Wikibase/extension-repo.json" );
require_once "$IP/extensions/Wikibase/repo/config/Wikibase.example.php";
$wgWBRepoSettings['siteLinkGroups'] = [ 'mywikigroup' ];
$wgLocalDatabases = [ 'enwiki', 'fawiki' ];
$wgWBRepoSettings['localClientDatabases'] = [
	'en' => 'enwiki',
	'fa' => 'fawiki'
];

Use the snippet below only if using versions below 1.36:

$wgEnableWikibaseRepo = true;
$wgEnableWikibaseClient = false;
require_once "$IP/extensions/Wikibase/repo/Wikibase.php";
require_once "$IP/extensions/Wikibase/repo/ExampleSettings.php";
$wgWBRepoSettings['siteLinkGroups'] = [ 'mywikigroup' ];
$wgLocalDatabases = [ 'enwiki', 'fawiki' ];
$wgWBRepoSettings['localClientDatabases'] = [
	'en' => 'enwiki',
	'fa' => 'fawiki'
];

These configurations assume that your interwiki prefixes are en and fa. Adjust as needed.

Note that $wgWBRepoSettings wraps all the Wikibase repository configurations. See defaults in Wikibase.default.php.

Client only

Versions 1.36 and above use extension registration:

wfLoadExtension( 'WikibaseClient', "$IP/extensions/Wikibase/extension-client.json" );
require_once "$IP/extensions/Wikibase/client/config/WikibaseClient.example.php";
$wgWBClientSettings['repoUrl'] = 'https://pool.my.wiki';
$wgWBClientSettings['repoScriptPath'] = '';
$wgWBClientSettings['repoArticlePath'] = '/wiki/$1';
$wgWBClientSettings['entitySources'] = [
	'poolwiki' => [
		'repoDatabase' => 'poolwiki',
		'baseUri' => 'https://pool.my.wiki/entity',
		'entityNamespaces' => [
			'item' => 120,
			'property' => 122,
		],
		'rdfNodeNamespacePrefix' => 'wd',
		'rdfPredicateNamespacePrefix' => '',
		'interwikiPrefix' => '',
	],
];
$wgWBClientSettings['itemAndPropertySourceName'] = 'poolwiki';
$wgWBClientSettings['siteLinkGroups'] = [ 'mywikigroup' ];
$wgWBClientSettings['siteGlobalID'] = 'en';

For another lang-wiki client, like Farsi, change the siteGlobalID to:

$wgWBClientSettings['siteGlobalID'] = 'fa';

Use the snippet below only if using versions below 1.36:

$wgEnableWikibaseRepo = false;
$wgEnableWikibaseClient = true;
require_once "$IP/extensions/Wikibase/client/WikibaseClient.php";
require_once "$IP/extensions/Wikibase/client/ExampleSettings.php";
$wgWBClientSettings['repoUrl'] = 'https://pool.my.wiki';
$wgWBClientSettings['repoScriptPath'] = '';
$wgWBClientSettings['repoArticlePath'] = '/wiki/$1';
$wgWBClientSettings['repositories']['']['repoDatabase'] = 'poolwiki';
$wgWBClientSettings['repositories']['']['changesDatabase'] = 'poolwiki';
$wgWBClientSettings['siteLinkGroups'] = [ 'mywikigroup' ];
$wgWBClientSettings['siteGlobalID'] = 'en';

You can look also the official complete description of the configurations options.

Note that $wgWBClientSettings wraps all the Wikibase client configurations. See defaults in WikibaseClient.default.php.

Wikibase repository

Define links for external identifiers

In order to add links for external identifiers in the main interface (as seen in this Wikidata example Q85#P214 and config P214#P1630):

1. Create a property of type "String" (just like the property "formatter URL" in Wikidata). The property that we are creating in this step will be the one used for storing the link formatter in other properties (e.g. usage of "formatter URL" in "VIAF ID"). Properties that use this property should be of type "External identifier".
2. Get the ID of the property we created in the previous step (e.g., P5).
3. Configure in LocalSettings.php:

   $wgWBRepoSettings['formatterUrlProperty'] = 'P5';
   

4. If adding the setting does not work on its own, run the following command

   php extensions/Wikibase/repo/maintenance/rebuildPropertyInfo.php --rebuild-all --force
   

5. Now users can use this property (in the example above P5) in properties whose type is "External Identifier". The value must contain $1 in the URL formatter (e.g. https://viaf.org/viaf/$1/), $1 will then be replaced by the identifier provided in the items that use the property that we set in the option $wgWBRepoSettings['formatterUrlProperty'].

Canonical URIs can be similarly configured in RDF dumps (prefixes wdtn:, psn:, pqn:, prn:), as seen on Wikidata with the property P1921 and used on the property P214#P1921). The configuration is similar to the parameter $wgWBRepoSettings['canonicalUriProperty'].

Optional settings

propertyOrderUrl

propertyOrderUrl allows custom ordering of properties using the LUA function mw.wikibase.orderProperties as explained in Manual:Interface/Wikibase-SortedProperties

$wgWBRepoSettings['propertyOrderUrl'] = $wgServer. $wgScriptPath . '/index.php?title=MediaWiki:Wikibase-SortedProperties&action=raw&sp_ver=1';

statementSections

statementSections allows a Wikibase administrator to customise statement display and grouping in Wikibase.

In LocalSettings.php, define wmgWikibaseRepoStatementSections with separate sections for each wiki on your instance. For identifiers and constraints, you can define a type which filters certain elements out into their own section.

The syntax options for identifiers and constraints are:

• null — no elements are placed in a separate section
• 'type' => 'dataType' — elements with the specified data type/s appear in a separate section
  • 'dataTypes' => [ 'exampleDataType1' ] — specify the data type/s to filter on
• 'type' => 'propertySet'] — elements with the specified property/ies appear in a separate section
  • 'propertyIds' => [ 'exampleProperty1' ] — specify the property/ies to filter on

For instance, to replicate how Wikidata separates External identifiers from the rest of its properties, set:

$wgWBRepoSettings['statementSections'] = [
	'item' => [
		'statements' => null,
		'identifiers' => [
			'type' => 'dataType',
			'dataTypes' => [ 'external-id' ],
		],
	],
];

You can customise the name of the label using the MediaWiki:Wikibase-statementsection-identifiers page.

See also:

• A Phabricator ticket requesting statement sections
• Wikidata's own config
• Example from the Wikibase code repo

Available configuration settings

All available configuration settings are noted in the master configuration document.

Maintenance scripts

Wikibase provides a few maintenance scripts which can be found in the maintenance subdirectory. Wikibase must be installed in MediaWiki's extensions directory, extensions/Wikibase. If it's installed elsewhere, you can set the MW_INSTALL_PATH environment variable to the path of your MediaWiki installation and the scripts will use it.

Repo

A common way to set the environment for scripts called in cron jobs: env 'MW_INSTALL_PATH=/var/www/repo' php /path/to/php/script

populateSitesTable.php

This script will load the wiki matrix from meta.wikimedia.org and use that information to populate the local sites table. This provides Wikibase with the information it needs to connect to other wikis, such as for the purpose of suggesting or normalising page titles when creating site links.

From the MediaWiki install folder, run:

php extensions/Wikibase/lib/maintenance/populateSitesTable.php

To insert a new Wikibase client without using the wiki matrix, see Manual:Sites table.

dispatchChanges.php

As of version 1.38, this script has been deprecated and will no longer work with the corresponding version of Wikibase (see Phabricator ticket phab:T277027).

This script updates the client wiki's local items cache.

1. Provide the script with the information it needs about the client wiki databases.

LocalSettings.php:

$wgLocalDatabases = $wgWBRepoSettings['localClientDatabases'] = [ 'enwiki', 'fawiki' ];

2. Run the dispatch changes script.

php extensions/Wikibase/repo/maintenance/dispatchChanges.php

Note that this script performs the synchronisation; the repo and the client will remain in sync only so long as this script is running.

pruneChanges.php

This script allows you to prune the Wikibase changes table. When run with no parameters, it will delete all changes older than 7 days. You may specify the number-of-days flag for periods of other lengths:

php repo/maintenance/pruneChanges.php --number-of-days 1
11:07:46 pruning entries older than 2020-12-11T11:07:46Z
11:07:47 151 rows pruned
11:07:47 done, exiting

Features and usage

After Wikibase is installed, interlanguage links are automatically obtained from the repo and added to client wiki pages as long as the polling script is running. The extension then sorts the links (as defined by the local wiki), displays them and saves them to the database exactly as they are defined on the page. The extension is robust and retains existing links when the central wiki is down.

By default the extension works only in the main namespace, but this can be changed using the namespaces configuration option.

Mixing Wikidata and local interlanguage links

The extension doesn't affect how interlanguage links work; they can be used in parallel with the extension. There are several use cases:

• Links on pages in namespaces not configured to use the extension will work as if the extension were not installed.
• If you want to add links in addition to the links stored in Wikidata, simply add new links in wikitext; your links and the Wikidata links will be displayed together.
• To exclude one or more Wikidata links, use noexternallanglinks with the desired language(s). Other links will work normally.
• To supersede one or more Wikidata links, use noexternallanglinks and add the new links in wikitext.
• To turn off Wikidata links altogether, use noexternallanglinks on its own. Links you provide will work as if the extension were not installed.

noexternallanglinks

noexternallanglinks is a magic word and a parser function which can turn this extension off for a specific page, or suppress some of the interlanguage links produced by the extension.

When used on its own ({{noexternallanglinks}}), Wikibase is effectively disabled on the given page. Only interlanguage links present in the wikitext are used. The word works the same when used as a function, with an asterisk: {{noexternallanglinks:*}} (the asterisk "matches" all the languages).

When invoked as a function with parameters, links to the specified languages will be removed. For example, {{noexternallanglinks:fr|id}} removes links to French and Indonesian languages. You may also invoke the function more than once: {{noexternallanglinks:fr}} {{noexternallanglinks:id}}. It is safe to remove links to languages that don't exist.

Data transclusion

WikibaseClient allows data inclusion from the Wikibase repo using the {{#statements:…}} parser function along with Lua.

Lua

• Lua documentation

Parser functions

• Lookup by property ID (e.g., P2), to include data from a Wikibase item connected by sitelink. For example, {{#statements:P2}}.
• Lookup by property label. For example, {{#statements:country}}.
• With arbitrary access enabled, it can be applied to any item. For example, {{#statements:P31|from=Q460679}}.
• In addition to {{#statements:…}}, which outputs linked wikitext, you can use {{#property:…}}, which outputs unlinked labels.
• See How to use data on Wikimedia projects for further documentation.

Other projects sidebar

See also Interproject links interface for the current status for Wikimedia projects.

The configuration option otherProjectsLinks creates an "Other projects" sidebar section with links to other projects from the item linked to the current page. It currently supports exactly one link per project and does not yet override links in wikitext using a parser function (though current JavaScript hacks may be easily adapted).

Configuration sample (links will be displayed in the order specified):

$wgWBClientSettings['otherProjectsLinks'] = [ 'frwiki', 'frwikiquote', 'commonswiki', 'frwikivoyage' ];

The sidebar's id is "wikibase-otherprojects". You can use it to customise the section's position in the sidebar using Sidebar.

Each link has a the label containing the i18n messages "wikibase-otherprojects-ID" with ID the id of the linked site group (like "wikipedia", "wikisource" or "commons").

Sample page: Village pump.

commaseparatedlist

commaseparatedlist is a parser function that can be used in edit summaries for text formatting. It returns its list of arguments separated by the given language's proper separator. For example, {{#commaseparatedlist:word1|word2|word3}} results in word1, word2, word3.

Enabling sitelinks

Sitelinks are special links with a site and a title, linking from individual items to pages on other wikis. In Wikidata these go to other Wikimedia sites such as Wikipedia, Wikisource and Wikivoyage. Among other things, sitelinks allow referencing an Item's property on the linked page in the client wiki, a feature known as Direct access.

Configuring your sitelink groups

First, consider how to group the client wikis you want to see in your sitelinks area for the Items in your repo wiki.

Defining custom groups

In your repo wiki, replace the content of $wgWBRepoSettings['siteLinkGroups'] in LocalSettings.php with the groups you would like to see there.

For example, consider the following line in LocalSettings.php:

$wgWBRepoSettings['siteLinkGroups'] = [ 'wikipedia', 'mywikigroup', 'anothergroup' ];

This would create three groups in the Item page's sitelinks box:

• the standard defined wikipedia for the global Wikipedia sites
• two custom wiki groups (here named mywikigroup and anothergroup)

The names defined here will relate to the site_group field in the sites table, as specified below.

In your client wiki, add a similar configuration line with your siteLinkGroups:

$wgWBClientSettings['siteLinkGroups'] = [ 'wikipedia', 'mywikigroup', 'anothergroup' ];

Deactivating the sitelinks feature

If you do not want your installation to make use of sitelinks at all, you can deactivate them by setting the configuration to an empty array:

$wgWBRepoSettings['siteLinkGroups'] = [];

$wgWBClientSettings['siteLinkGroups'] = [];

Localise your groups

To show the correct heading for your groups, you must create the page MediaWiki:Wikibase-sitelinks-mywikigroup with the desired heading as text.

You can create subpages to set headings for different languages, e.g., create MediaWiki:Wikibase-sitelinks-mywikigroup/de to create a German heading.

Add the wikis to the sites table

In order to add sitelinks to Items in your repo wiki, you must add the client wikis to the sites table. Group names must match the group names you added to your configuration. Following the example above, you would have one or more sites with mywikigroup and anothergroup as text in the site_group field.
You must set both the file path and the page path, and each must include the $1 placeholder.

Example

To add your wiki (with an id ending with wiki) to the group mywikigroup, run:

cd maintenance
php addSite.php --pagepath=https://mw.wiki/wiki/\$1  --filepath=https://mw.wiki/w/\$1 --language en --interwiki-id en en mywikigroup
php addSite.php --pagepath=https://fa.mw.wiki/wiki/\$1  --filepath=https://fa.mw.wiki/w/\$1 --language fa --interwiki-id fa fa mywikigroup

Be sure to do this on the repo wiki and all client wikis so that the "Add links" functionality in the other languages section works correctly.

For further details on how to add sites to the table, please see these instructions.

Inform the repo wiki of the other client wiki databases

$wgLocalDatabases = [ 'enwiki', 'fawiki' ];
$wgWBRepoSettings['localClientDatabases'] = [
    'en' => 'enwiki',
    'fa' => 'fawiki'
];

localClientDatabases — An array of locally accessible client databases, for use by the change dispatching mechanism. This setting specifies which wikis to directly push changes to. It must be specified either as an associative array (mapping global site IDs to logical database names) or as a list of databases (if the database names match the site IDs). The default is an empty array, indicating no local client databases.

Verify that you can add sitelinks

1. Go to the Special:SetSiteLink page in your repo wiki and try to link an existing Item (field "ID") to one of the sites configured above (field "Site ID") by specifying an existing page on that wiki (field "Sitelink"). If it fails, it should provide a useful error message.
2. On the page you added above, check that Direct access works by referencing a property of the Item in a parser function.

Troubleshooting

There are no sites I can link pages to in an item.

One or more of the following may help:

php lib/maintenance/populateSitesTable.php

php repo/maintenance/rebuildItemsPerSite.php