 Release status: stable | |
|---|---|
| Implementation | API,Parser extension |
| Description | Stores information about images representing a page |
| Author(s) | Max Semenik (MaxSemtalk) |
| Latest version | continuous updates |
| Compatibility policy | Snapshots releases along with MediaWiki. Master is not backward compatible. |
| MediaWiki | 1.37+ |
| PHP | 7.3.19+ |
| Database changes | No |
| License | WTFPL 2.0 |
| Download | |
| |
| Translate the PageImages extension if it is available at translatewiki.net | |
| Issues | Open tasks ·Report a bug |
ThePageImages extension collects information about images used on a page.
It aims to return the single most appropriate thumbnail associated with an article.
PageImages also providesOpenGraph protocol metadata for articles on the wiki for 3rd parties like Facebook to extract.
PageImages folder to yourextensions/ directory.cdextensions/gitclonehttps://gerrit.wikimedia.org/r/mediawiki/extensions/PageImageswfLoadExtension('PageImages');
initImageData.php script from the extensions maintenance directory (/path/to/extensions/PageImages/maintenance/)
Done – Navigate toSpecial:Version on your wiki to verify that the extension is successfully installed.$wgPageImagesDenylist is an array of sources for image denylists. Listed images will never be selected as page images. Examples:
$wgPageImagesDenylist=[// Page on local wiki['type'=>'db','page'=>'MediaWiki:Pageimages-denylist','db'=>false,],// Page on Wikimedia Commons, for other Wikimedia projects using direct DB access['type'=>'db','page'=>'MediaWiki:Pageimages-denylist','db'=>'commonswiki',],// Page on Commons, for third-party sites using web access['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.
The denylist should contain wikilinks to files. The rest of the content is irrelevant (and can contain links to other pages).For example:
* [[:File:First denylisted file.png]]* [[:File:Second denylisted file.jpeg]]...
Remember that file links that result in images being added to the page will not work (these files are denylisted for a reason, right?), so don't forget the: in front of the links.
| Name | Description | Default |
|---|---|---|
| $wgPageImagesDenylistExpiry | determines how long the list will remain cached, in seconds. | 15 * 60 (15 minutes) |
| $wgPageImagesExpandOpenSearchXml | if set totrue, PageImages will override the image detection in theopensearch API module with its own, more accurate results. | false |
| $wgPageImagesNamespaces | an array of namespaces PageImages will be activated on. After the change, you'll have to runrefreshLinks.php to generate the Page image information for those namespaces (hopefully, you can use the | NS_MAIN |
| $wgPageImagesOpenGraph | enables or disables the OpenGraph meta tags (could be useful if other extensions manage these tags) (1.39+). | true |
| $wgPageImagesOpenGraphFallbackImage | a URL to a fallback image that will be shown when there is no image on a page. | false |
Since MediaWiki 1.37,$wgPageImagesBlacklist and$wgPageImagesBlacklistExpiry have been renamed to$wgPageImagesDenylist and$wgPageImagesDenylistExpiry, respectively.Since MediaWiki 1.37, the default page value for$wgPageImagesDenylist has been changed fromMediaWiki:Pageimages-blacklist toMediaWiki:Pageimages-denylist.
There is no backward compatibility code added to accept the old names, so you should change the variable names during the upgrade or define both variables in advance in preparation for the upgrade.If you've added content toMediaWiki:Pageimages-blacklist on your wiki, you should rename it to the new name.Also set$wgPageImagesBlacklist (the old variable name) to the new page name. The default value will be used when upgrading, which should match your previous change.
The PageImages extension provides image information by adding aprop=pageimages to theproperties API foraction=query.
Returns information about images on the page, such as thumbnail and presence of photos.
Which information to return:
Maximum width in pixels of thumbnail images.
Properties of how many pages to return.
Limit page images to a certain license type:
When more results are available, use this to continue. More detailed information on how to continue queriescan be found on mediawiki.org.
Code for the language the image is going to be rendered in if multiple languages are supported
{// piprop.name (and image exists)pageimage?:string// Source image filename (basename of original.source).// piprop.thumbnail (and image exists)thumbnail?:{source:string// Thumbnail image URL.width:number// Thumbnail image width in pixels.height:number// Thumbnail image height in pixels.}// piprop.original (and image exists)original?:{source:string// Source image URL.width:number// Source image width in pixels.height:number// Source image height in pixels.}}
| Result |
|---|
{"query":{"normalized":[{"from":"Lightbox_demo","to":"Lightbox demo"}],"pages":{"162510":{"pageid":162510,"ns":0,"title":"Lightbox demo","thumbnail":{"source":"https://upload.wikimedia.org/wikipedia/commons/thumb/e/e9/Crystal_Clear_app_korganizer.png/50px-Crystal_Clear_app_korganizer.png","width":50,"height":50},"pageimage":"Crystal_Clear_app_korganizer.png"}}}} |
When a page is saved with a local image, theparser runs thehooksParserMakeImageParams andLinksUpdate.The PageImages extension responds to these (and other hooks) and inserts a new property for the page into thepage_props table.The property names used arepage_image andpage_image_free; the value is the name of the image.If a page has both properties, then the values are different.
The extension only stores the chosen image name. Other features may display the image, such asPage information,Hovercards, and Mobile search while typing.
Page images will be listed on the?action=info page.
All images on 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 (i.e., have a negative score), the page will not have any images.
If$wgPageImagesLeadSectionOnly istrue, only images in the lead section will be considered.This is true for Wikipedia projects only; all other projects can pull images from outside the lead.
The best possible page image on Wikimedia wikis is one of the first four images in an article, with a width/height between 400-600px and a height/width twice the value of the other dimension.
$wgPageImagesScores['width']$wgPageImagesScores['galleryImageWidth']$wgPageImagesScores['position']$wgPageImagesScores['ratio']$wgPageImagesScores['ratio'] = ["3" => -100, "5" => 0, "20" => 5, "30"=> 0, "31"=> -100]; with the key representing the width divided by height, rounded to the tenths place, and the decimal shifted one position to the right. An image 400px wide by 300px high would have a value of 13. The key's value is the scoring multiple associated with that ratio. Keys are selected and increase from zero, with a new scoring multiple not taking effect until the key has met or exceeded its value but not exceeded the next key. Any other images will score negatively and be discarded.Pageimages populates images whenever theLinksUpdate hook runs, e.g. when a page is being edited.
Yes!
For an entire wiki, there is a page that administrators can edit at MediaWiki:Pageimages-denylist (example).Any images that appear here will not be used as page images for any article.
For specific pages, add|class=notpageimage to each image you want to exclude. For example,[[File:Example.png|class=notpageimage]]. More details are atphab:T301588.
From MediaWiki 1.44.0, you can mark an image that meets the criteria outlined in theHow does it select images? section by adding|class=pageimage to the image.Generally this is advised as a last resort, as this overrides the image scoring algorithm meaning the image may not be suitable for where it is displayed (e.g. resolution, license or position).
It is preferable where possible to add the preferred thumbnail as the first image in the article.
Using thePage information link in the sidebar (or adding?action=info to the URL) you'll be able to see the current image choice.
The page image only changes when a link in an article changes. Please add/remove links from the page for emergencies, reverting if necessary.Purging will not work.For larger emergencies please file a Phabricator ticket.
This likely relates to video content in your article.If a video file begins with a blank screen, that will become the default thumbnail for the video, and if used as the page image, it will become the page image.We are currently working on a fix for this that will allow you to change the default thumbnail of a video.See:phab:T92457 andphab:T22647 for further information.
 | This extension is being used on one or moreWikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia'sCommonSettings.php andInitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki'sSpecial:Version page. |
 | This extension is included in the following wiki farms/hosts and/or packages:This is not an authoritative list. Some wiki farms/hosts and/or packages may contain this extension even if they are not listed here. Always check with your wiki farms/hosts or bundle to confirm. |