From MediaWiki.org
Jump to: navigation, search

Other languages:
English • ‎日本語 • ‎polski • ‎русский • ‎中文
MediaWiki extensions manualManual:Extensions
Crystal Clear action run.png

Release status:Extension status stable

ImplementationTemplate:Extension#type API, Parser extension
DescriptionTemplate:Extension#description Stores information about images representing a page
Author(s)Template:Extension#username Max Semenik (MaxSemtalk)
Latest versionTemplate:Extension#version continuous updates
MediaWikiTemplate:Extension#mediawiki 1.20+
PHPTemplate:Extension#php 5.3+
Database changesTemplate:Extension#needs-updatephp No
LicenseTemplate:Extension#license WTFPL 2.0
  • $wgPageImagesBlacklist
  • $wgPageImagesBlacklistExpiry
  • $wgPageImagesExpandOpenSearchXml
  • $wgPageImagesNamespaces
Hooks usedTemplate:Extension#hook

Translate the PageImages extension if it is available at translatewiki.net

Check usage and version matrix.


Open tasks · Report a bug

The PageImages extension collects information about images used on a page.

Its aim is to return the single most appropriate thumbnail associated with an article.

Installation[edit source]

  • Download and place the file(s) in a directory called PageImages in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
    wfLoadExtension( 'PageImages' );
  • YesY Done - Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

To users running MediaWiki 1.27 or earlier:

The instructions above describe the new way of installing this extension using wfLoadExtension() If you need to install this extension on these earlier versions (MediaWiki 1.27 and earlier), instead of wfLoadExtension( 'PageImages' );, you need to use:

require_once "$IP/extensions/PageImages/PageImages.php";

API[edit source]

The PageImages extension provides image information by adding a prop=pageimages to the propertiesAPI:Properties API for action=query.

prop=pageimages (pi)

(main | query | pageimages)
  • This module requires read rights.
  • Source: PageImages
  • License: WTFPL

Returns information about images on the page, such as thumbnail and presence of photos.


Which information to return:

URL and dimensions of thumbnail image associated with page, if any.
URL and original dimensions of image associated with page, if any.
Image title.
Values (separate with | or alternative): thumbnail, name, original
Default: thumbnail|name

Maximum thumbnail dimension.

Type: integer
Default: 50

Properties of how many pages to return.

No more than 50 (100 for bots) allowed.
Type: integer or max
Default: 1

Limit page images to a certain license type

One of the following values: free, any
Default: free

When more results are available, use this to continue.

Type: integer
Get name and 100-pixel thumbnail of an image on the Albert Einstein page.
api.php?action=query&prop=pageimages&titles=Albert%20Einstein&pithumbsize=100 [open in sandbox]

Sample request[edit source]

Request page image for an article.

Configuration[edit source]

$wgPageImagesBlacklist is an array of sources for image blacklists. Blacklisted images will never be selected as page images. Examples:

$wgPageImagesBlacklist = array(
	// Page on local wiki
		'type' => 'db',
		'page' => 'MediaWiki:Pageimages-blacklist',
		'db' => false,
	// Page on Wikimedia Commons, for other Wikimedia projects
		'type' => 'db',
		'page' => 'MediaWiki:Pageimages-blacklist',
		'db' => 'commonswiki',
	// Page on Commons, for third-party sites using our web API
		'type' => 'url',
		'url' => 'http://commons.wikimedia.org/w/index.php?title=somepage&action=raw',

More than one source can be used at the same time.

$wgPageImagesBlacklistExpiry determines how long the blacklist will remain cached, in seconds. Default: 15 * 60 (15 minutes).

$wgPageImagesExpandOpenSearchXml if set to true, PageImages will override the image detection in the opensearchApi:Opensearch API module with its own, more accurate results. Default: false.

$wgPageImagesNamespaces is an array of namespaces PageImages will be activated on. Default: NS_MAIN.

The blacklist itself should contain a wikilinks to blacklisted files, the rest of content is irrelevant (and can contain links to other pages). For example:

* [[:File:First blacklisted file.png]]
* [[:File:Second blacklisted file.jpeg]]

Remember that file links that result in images being added to the page will not work (these files are blacklisted for a reason, right?), so don't forget the : in front of the links.

How it works[edit source]

When a page is saved with a local image, the parser runs the hooks ParserMakeImageParams and LinksUpdate. The PageImages extension responds to these (and other hooks) and inserts a new property for the page into the page_propsManual:page_props table table. The property name is page_image and its value is the name of the image.

The extension only stores the chosen image name. Other features may display the image, such as Page information, Hovercards, and Mobile search while typing.

Image choice[edit source]

The page image is chosen based on a number of criteria with limited documentation. It attempts to return only meaningful images, e.g. not those from maintenance templates, stubs or flag icons. Non-free images may be skipped for copyright reasons. Images with very different width and height may be skipped due to poor display in features using the image. The first image satisfying certain criteria may be chosen. No image will be chosen on some pages.

See also[edit source]