Extension:PageImages

From MediaWiki.org
Jump to: navigation, search
Translate this page; This page contains changes which are not marked for translation.

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

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.4+
Database changesTemplate:Extension#needs-updatephp No
LicenseTemplate:Extension#license WTFPL 2.0
Download
ParametersTemplate:Extension#parameters
  • $wgPageImagesBlacklist
  • $wgPageImagesBlacklistExpiry
  • $wgPageImagesExpandOpenSearchXml
  • $wgPageImagesNamespaces
Hooks usedTemplate:Extension#hook
ParserMakeImageParamsManual:Hooks/ParserMakeImageParams
AfterParserFetchFileAndTitleManual:Hooks/AfterParserFetchFileAndTitle
LinksUpdateManual:Hooks/LinksUpdate
OpenSearchXml

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

Check usage and version matrix.

IssuesPhabricator

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]

  • 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]

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.

Parameters:
piprop

Which information to return:

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

Maximum thumbnail dimension.

Type: integer
Default: 50
pilimit

Properties of how many pages to return.

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

Limit page images to a certain license type

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

When more results are available, use this to continue.

Type: integer
Example:
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]

Request page image for an article.

Configuration[edit]

$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
	array(
		'type' => 'db',
		'page' => 'MediaWiki:Pageimages-blacklist',
		'db' => false,
	),
	// Page on Wikimedia Commons, for other Wikimedia projects
	array(
		'type' => 'db',
		'page' => 'MediaWiki:Pageimages-blacklist',
		'db' => 'commonswiki',
	),
	// Page on Commons, for third-party sites using our web API
	array(
		'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]

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]

How does it select images?[edit]

All images in the page are collected and a score for each image is calculated. The image with the highest score is selected as the page image. If the wiki is configured such that images contain metadata that specifies images are not freely licensed, the image with the best score that is also freely licensed is also stored. If no suitable image is found or all the images score badly, the page will not have any images.

If $wgPageImagesLeadSectionOnly is true, only images in the lead section will be considered. Currently it is true for only Wikipedia projects, all other projects can pull images from outside the lead.

How are images scored?[edit]

The best possible page image on Wikimedia wikis is one of the first four images in an article which has a width/height between 400-600px and a height/width which is twice the value of the other dimension.

  • The algorithm is configurable.
  • Scores are calculated by a combination of:
    • Image widths as defined in $wgPageImagesScores['width']
      • In Wikimedia wikis, images smaller than 119 pixels are weighted highly negatively. Images with widths between 400px-600px are favoured, with a preference for the lower bound.
      • Images inside galleries are scored separately using $wgPageImagesScores['galleryImageWidth']
        • In Wikimedia wikis gallery images which are smaller than 100 are disregarded.
    • Position in document is also considered as defined in $wgPageImagesScores['position']
      • On Wikimedia wikis, only the first 4 images that appear in the document are considered.
    • The ratio of the image's width to height is considered $wgPageImagesScores['ratio']
      • On Wikimedia wikis the best possible images are images where the height is half the width or the height is double the width

Be more technical please...[edit]

Pageimages populates images whenever the LinksUpdate hook runs.

In PageImages this is executed in LinksUpdateHookHandler::doLinksUpdate

Can I exclude certain page images?[edit]

Yes! There is a blacklist on every wiki that administrators can edit, at MediaWiki:Pageimages-blacklist (example). Any images that appear here will not be page images for any article.

What about just for one particular article?[edit]

Sadly not at the current time. Please use the blacklist or move the image outside the lead section.

How can I see the page image for a page?[edit]

Using the Page information link in the sidebar (or adding ?action=info to the URL) you'll be able to see the current image choice.

How can I purge a bad image?[edit]

The pageimage only changes when a link in an article changes. For emergencies, please add/remove links from the page, reverting if necessary. Purging will not work. For larger emergencies please file a Phabricator ticket.

See also[edit]