YK: Chapter 7: Images and files

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, and they’re used when querying images in Semantic MediaWiki, with formats such as "table" and "gallery" (see here and here, respectively).

Troubleshooting uploading

It could be that, when you try to upload files on a wiki, you’re not allowed to. 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:

https://www.mediawiki.org/wiki/Manual:Configuring_file_uploads

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 = 30M

upload_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:

https://www.mediawiki.org/wiki/Extension:UploadWizard

There’s another extension, MultiUpload, that lets users upload more than one file at the same time; which can be useful when there’s a large set of images to be added. At the moment, this extension is somewhat unmaintained, and may have problems depending on your MediaWiki version, but when it works it’s quite useful:

https://www.mediawiki.org/wiki/Extension:MultiUpload

Finally, uploads are possible via Semantic 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 Chapter 17.

Image galleries

The built-in MediaWiki tag

• 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:
• Monkey.png
• Rhesus monkey.jpg

  This is a rhesus monkey

• Large monkey.gif

  This is a large monkey

Newlines here separate the names of the images.

In addition, if you’re using Semantic MediaWiki, the “gallery” query format defined in the extension Semantic Result Formats lets you display a similar result via a semantic 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 Javascript Slideshow, which also lets you include text within each slide:

https://www.mediawiki.org/wiki/Extension:Javascript_Slideshow

If you’re using Semantic MediaWiki, you can also display a slideshow using the Semantic Result Formats extension’s “gallery” format (see here).

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:

https://www.mediawiki.org/wiki/Extension:S5SlideShow

And similarly, Semantic Result Formats also offers a format that enables slideshow presentations: the “pagewidget” format.

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.