Chapter 7 Images and files
MediaWiki should never be mistaken for a real document-management system, but it does have a reasonable amount of support for managing files. True document-management systems have integration with the file system of the computer or network they're on, and usually let you edit documents inline – neither of which MediaWiki allows. (Though there's discussion about enabling the latter for MediaWiki, for SVG and some video formats, in the future.) MediaWiki does, however, let you upload files, and display them within other pages in a variety of ways – and it keeps a version history for each file, which is a very useful feature.
Uploading
The standard interface for uploading files to MediaWiki is the page Special:Upload, which lets you upload one file at a time.
Figure 7.1: Special:Upload page
When you upload a file, you are asked to select its name on the wiki, which, by default, is the file's name on the local system. You can also provide a summary of the file, and finally you are asked to specify a copyright type for that file, based on the set of allowed copyrights for the wiki (more on this later). The copyright choice assumes that the person doing the uploading was responsible for generating the file; or, at the very least, knows the copyright wishes of the person who generated the file – and often, neither of these is the case. This book will not get into issues of copyright, legal or otherwise; but you should know that there are a lot of options for allowed copyright type, and the best solution may depend on a variety of circumstances, including whether the wiki is public or private.
Once a file is uploaded, several things happen: the file gets placed in the wiki's images/ directory (the directory is called “images”, even though it can hold uploaded files of all types); a page in the “File:” namespace is created for that file (the full name of the page will be “File:page-name”, like “File:Cat.png”); and, if it's an image, and the image is bigger than the standard thumbnail size, a thumbnail is created for that file and is placed in the directory /images/thumb.
The images/ directory
The images/ directory can take two structures. By default, the directory is subdivided into two levels of subdirectories, where the first level consists of folders whose name is a single hexadecimal digit, from “0” to “f”; and the second level has folder names whose name consists of the parent folder's number or letter, plus a second hexadecimal digit. In other words, a file can be placed in a directory like “/images/8/8b” within the MediaWiki directory. There are 16 * 16 = 256 such possible sub-subdirectories. This default approach is also known as the “hashed” approach. It is used to try to prevent directories from getting too large – some file systems have a limit on the number of files any one directory can contain.
The other approach is to simply store every file in the images/ directory. This approach has the advantage of simplicity, and for smaller wikis it's just as good a solution. To enable this approach, add the following to LocalSettings.php:
$wgEnableHashedUploads = false;
If you're going to use this setting, you should ideally do it before any files are uploaded. If, however, you want to change this setting for a wiki that already has uploaded files, you'll probably have to re-import the files (see here).
Thumbnails
A thumbnail is a small image meant to represent an uploaded file. For files that are images, these are simply smaller versions of the original image (or, for images that are already small, versions of the same size). For non-image files, these tend to just be an icon: for PDF files, for instance, it's the Adobe Acrobat logo.
Thumbnails are used to represent images in various places within the wiki. Most importantly, they can be used to display the image on wiki pages – we'll get to the syntax and options for displaying images later in this chapter. Thumbnails are also used to show the version history of each file, within its own page. They are also used in the Special:ListFiles page (see here), in image galleries, and in category pages.
Troubleshooting uploading
It could be that, when you go to upload files on a wiki, you find that you're not able to do it. That could be for any of the following reasons:
- PHP on the server is blocking uploads
- The images/ directory is not writable by MediaWiki
- MediaWiki itself has uploading disabled
- your user account is not allowed to upload.
If it looks like PHP is blocking uploads, add the following line in php.ini:
file_uploads = On
If the images directory is not writable, the solution depends on the web server and file system in question – this page holds more information:
Uploading also needs to be enabled in MediaWiki itself – make sure that you have the following line in LocalSettings.php:
$wgEnableUploads = true;
By default, every logged-in user is allowed to upload files, but unregistered users aren't. This can be changed in LocalSettings.php, via the 'upload' permission. (There's also a second relevant permission type, 'reupload', for uploading files that already exist on the wiki and thus overwriting their contents.) To prevent regular users from uploading, for instance, you could add the following to LocalSettings.php:
$wgGroupPermissions['user']['upload'] = false;$wgGroupPermissions['sysop']['upload'] = true;
And it may be that you're allowed to upload files in general, but the specific file you have can't be uploaded. That could be for two reasons: the file's size, or its file type.
Every wiki has a limit on the allowed size of uploaded files, which is set by a combination of four PHP and MediaWiki settings. Essentially, the smallest of these dictates what is allowed to go through, so you may need to change all four to increase the allowed limit on file sizes. There are two PHP settings: “post_max_size” and “upload_max_filesize”, both of which would need to be changed in php.ini. The two MediaWiki variables are $wgUploadSizeWarning and $wgMaxUploadSize – both represent a number of bytes. $wgUploadSizeWarning sets only what file size results in a warning to the user, so it doesn't actually affect which files go through and which don't – but it should be made consistent with what the actual limits are. So, to change the allowed file size to 30 megabytes, you would change the following in php.ini:
post_max_size = 30Mupload_max_filesize = 30M
...and add the following to LocalSettings.php:
$wgUploadSizeWarning = 30 * 1024 * 1024;$wgMaxUploadSize = 30 * 1024 * 1024;
File type restrictions
As for file types: only a limited set is allowed by default, because certain file types, like
Microsoft Office documents (Word, Excel and the rest) can contain viruses, which unsuspecting users can end up installing on their systems if they download the file. The default set of file extensions allowed is very short: only “png”, “gif”, “jpg” and “jpeg” (with the last two both representing JPG files).
What if someone tries to upload a .doc file simply by renaming the file's extension to, say, “.gif”? Thankfully, MediaWiki guards against that by looking at the file's internal file type, which the web server determines – the allowed set of file suffixes is really just shorthand for the allowed set of file types.
To add to or change the allowed set of file types, use the “$wgFileExtensions” variable in LocalSettings.php. The most common addition is allowing PDF files – to do that, you would add the following line:
$wgFileExtensions[] = 'pdf';
Extensions for uploading
A MediaWiki extension, UploadWizard
, provides a nicer approach to uploading than the standard one, by guiding users on a step-by-step process that explains all the different options, like the copyright license used. It was developed for use on Wikimedia Commons (the wiki that holds the uploaded files for Wikipedia and other Wikimedia projects), but it can also be used on standard wikis; though some of the wording is unfortunately Wikimedia-specific, and can't easily be customized away. You can read more about the extension here:
MsUpload
is a popular extension that displays, in conjunction with the WikiEditor extension (here), a button that makes uploading a file and displaying it on a particular page easy to do:
Another extension, SimpleBatchUpload
, presents a very simple interface – just a single button on the page Special:BatchUpload – which lets users quickly upload one or many files. It doesn't provide options like letting you rename files or setting the license on each file, but if you just want a fast, very simple upload process, it's a great tool:
Finally, uploads are possible via Page Forms. Uploading from within a form has the advantage that the name of the file gets automatically placed on the page after it's uploaded, so that users don't need to do the second step of inserting a tag to display the image/file on the wiki page after they've uploaded it. For more on this option, see here.
Displaying images
Images are generally displayed by simply linking to the image – which is a somewhat unexpected syntax. Let's say there's an image on the wiki called “Easter Island.png”. The simplest way to display it is to just have the following:
[[Image:Easter Island.png]]
Alternatively, you could have this instead, since “Image” and “File” are aliases for the same namespace:
[[File:Easter Island.png]]
For the rest of this example, we'll just use “Image”.
There are various additional settings you can apply to images: the height and width, the horizontal and vertical alignment, the caption, where the image links to, whether to place a border, etc. These are all parameters that can be added to the image tag, separated by pipes. Some are named, while others are unnamed.
Here's an example of an image display with more parameters set:
[[Image:Easter Island.png|100px|x150px|right|link=Easter Island info|This is Easter Island.]]
The parameters can be passed in in any order, so the parser determines what parameter each value corresponds to, based on the specific text in each (except for a few named parameters like “link=”). A “px” value without an “x” at the beginning sets the width, while one with an “x” at the beginning sets the height. “right” here controls the horizontal alignment of the image – the other options are “left”, “center” and “none”.
The “link=” parameter sets the location that the image links to – it can be either a wiki page or a URL. By default, an image links to its own page.
The last parameter, unless it's obviously something else, sets the caption for the image.
The only other very important setting for images is being able to display a thumbnail
– most of the time, when images are displayed, it's actually a thumbnail that's shown, rather than the full-size image. To display an image as a thumbnail, just add the parameter “|thumb” to the image tag.
What if you just want to link to an image, rather than display it? You can either link to the wiki page for the image, or to the image itself. To link to the image's wiki page, just add a colon at the beginning of the link, so it looks like:
[[:Image:Easter Island.png]]
If instead you want to link directly to the image, use the “Media” namespace instead, which exists just for this purpose. You could do:
[[Media:Easter Island.png|Click here to see a great picture.]]
There's more customization that can be done of image display. This page has all the details, as well as a lot of helpful demos:
Image galleries
The built-in MediaWiki tag <gallery> lets you display a group of images in one place. It takes in a group of image names and, optionally, their captions (which can include wikitext); a call to it would look like the following:
<gallery>Image:Monkey.pngImage:Rhesus monkey.jpg|This is a [[rhesus monkey]]Image:Large monkey.gif|This is a ''large'' monkey</gallery>
Newlines here separate the names of the images.
In addition, if you're using Cargo, the “gallery” query format it defines lets you display a similar result via a query, so that you don't have to hard-code the image names; see here.
Slideshows
You can also display images in a JavaScript “slideshow”, which is an interface where a series of images and/or text appear one after another in the same spot. The switching from one display to the next can be done manually, using links or arrows so that the user can flip through the images, or by simply cycling through them automatically. There are several extensions that do this; the most reliable standalone extension currently seems to be JavascriptSlideshow, which also lets you include text within each slide:
This slideshow functionality should not be confused with a PowerPoint-style slideshow presentation. There actually is an extension that lets you turn wiki pages into individual slides, suitable for a presentation – S5SlideShow:
The capability to run a slideshow presentation directly from the wiki is nice, because it lets you create a presentation collaboratively, in the manner of
Google Docs.
Audio and video
You may want to let users upload and view audio and video files directly in the wiki, rather than using outside services like SoundCloud or YouTube. You can do that with the TimedMediaHandler extension, which uses VideoJS, a popular open-source JavaScript library, to display both audio and video files. One nice aspect of TimedMediaHandler is that you don't even have to call a parser function: you can simply use the standard “File:” syntax, like [[File:Fishing tutorial.ogv]], and a video or audio player will be displayed for that file. The supported formats include Ogg and its variations, as well as MIDI and the better-known MP3 and MP4/M4A.
For more information, see:
Displaying outside images
By default, images from outside the wiki cannot be displayed. That's for several reasons, the most important of which is that a malicious user can place an external image on a wiki page, then collect information about all the visitors to that page; which would be a violation of privacy. You can change this default by adding the following to LocalSettings.php:
$wgAllowExternalImages = true;
If this is set, placing the URL of an external image in a page will display that image there.
You can also, instead, use the variable $wgAllowExternalImagesFrom to only allow images from certain trusted domains. Here is one example:
$wgAllowExternalImagesFrom = ['https://upload.wikimedia.org', 'https://i.imgur.com'];
However, if you're planning to use images from Wikimedia Commons (whose URL always starts with upload.wikimedia.org), the best approach is to use the “InstantCommons
” feature – which lets you directly use the standard image syntax to display images found on Wikimedia Commons. If you have InstantCommons enabled, and have a call that looks like “[[Image:Rocking horse.jpg|...]]”, MediaWiki will first look for an image named “Rocking horse.jpg” on your wiki; and, if it doesn't find one, will look for that file name on Wikimedia Commons, and display that one if it finds it there. You can enable InstantCommons just by adding the following to LocalSettings.php:
$wgUseInstantCommons = true;
Displaying PDF files
For uploaded PDF files (and, as noted earlier in this chapter, you need to manually configure the wiki to allow for uploading PDF files), you can provide an interface for letting users click back and forth to view all the pages within the file, via the PdfHandler extension
:
This is one of the extensions that comes bundled in with MediaWiki.