Installing and Customizing MediaWiki

If you have ever used Wikipedia, navigating through a MediaWiki site will be extremely familiar to you. If not, the basic rules are as follows: clicking on a link within a page brings you to another page within the MediaWiki site. The exception is when the link is followed by an arrow icon, which indicates that the link will open a site on another server. All pages on the site are not only viewable by the general public, but they also are editable. If you want to change the contents of a page, click on the Edit link (at the top of each MediaWiki screen), modify the contents as you see fit, and then click on the Save button when you are done.

MediaWiki tries to make it as easy as possible for users to participate without having to understand the technical side of things. It's thus unnecessary for end users to know HTML; they instead can click on a variety of buttons (and use a simplified formatting system) to format postings they make to the system. For example, entering [[Foo]] creates a link to the page Foo, regardless of whether it already exists. And, entering a link of the form [[Foo | This leads to Foo]] inserts a link to the Foo page, but with the text “This leads to Foo”.

More important than MediaWiki's simple markup language is the fact that every change made to the system is kept in an easy-to-use version-control system. By clicking on the History link on a given page, even a nontechnical user can view previous versions of a page, see who has made a given change or compare two versions of a particular document. In addition, users can set up watch lists, such that the user receives an e-mail message every time a page is modified. This allows users with particular interests and expertise to keep up with the latest updates to a given page and to monitor the content for potential damage.

By default, the left side of every page contains a short menu of commonly accessed links, including the main page (home page) of the wiki, a list of recent changes, a random existing page and the documentation. There is also a search box on the left side. Entering a text string and clicking on the Search button brings up a list of documents whose titles and/or contents match the target string. Because MediaWiki contents are all in the MySQL database, and because modern versions of MySQL have built-in text-indexing routines, such searches are relatively speedy.

Each page in a MediaWiki site has a URL that begins with the overall site URL (in my case, that would be http://wiki.lerner.co.il), followed by index.php/, and then the title of the page. Page titles may contain spaces, in which case the URL replaces each space with an underscore character. The page named Reuven Lerner on my server would thus have a complete URL of http://wiki.lerner.co.il/index.php/Reuven_Lerner. Somewhat frustratingly, MediaWiki URLs are case-sensitive, which means that entering an incorrectly capitalized word can result in the creation of a new page. Remember, a wiki never produces a true “not found” error, because you (the visitor) might well be interested in starting that very page.

There is no hierarchy to pages in a MediaWiki site. There is a single namespace, which can potentially lead to confusion. To reduce ambiguity, pages may contain additional information in parentheses (which are then part of the URL). Or, users can create a disambiguation page, which contains links to a number of pages with similar or identical names.

If you want to allow users to upload images, you need to modify the LocalSettings.php file that should now exist in your server's DocumentRoot directory. In the version I installed, line 73 of LocalSettings.php (just beneath a relevant comment in the PHP code) contains a commented-out definition of $wgEnableUploads, setting it to true. By uncommenting this line, you allow users to upload images to the server. These uploads will be, by default, in the images subdirectory (www/images), whose permissions must be writable by the Apache process.

Once you have turned on the uploading of images, logged-in users will be able to upload them with a two-step process. First, they click on the insert image button when editing a wiki page, or manually insert tags of the form [[Image:Example.gif]]. (Images all have the Image: prefix in MediaWiki, but there is a single, flat namespace for images, as is the case for textual content pages.) Once users have finished editing the page, they can then click on the missing image link. This will bring them to an HTML form allowing the missing image to be uploaded via the user's browser. Other types of documents can be uploaded in a similar way.

Wikis are a specialized form of content-management system (CMS). As such, they are programs whose goal is to display the most recent version of a generally static document. This contrasts with many other server-side programs, whose content changes for each user and invocation. Of course, MediaWiki must scan each document as it is published, in order to generate the different URLs needed for the existing and new links mentioned within the body of the text. But for the most part, MediaWiki specializes in the easy creation and distribution of static content, rather than programmatic pages.

However, MediaWiki's authors recognized that they and others probably will want to create dynamically generated pages, and thus was born the Special: designation. Any page whose name begins with Special: is treated—well, it's treated differently, populating the document body with the output of a PHP function. In order to create our own special page, we need to write a PHP function and then register that function with MediaWiki.

The first step is to create a new MediaWiki extension, putting it in the extensions directory just under the MediaWiki DocumentRoot. (The basic MediaWiki distribution includes this directory, but it is normally empty after a fresh install.) We will create the file extensions/SpecialHello.php, which looks like this:

<?php
$wgExtensionFunctions[] = "wfExtensionSpecialHello";

function wfExtensionSpecialHello()
{
    global $wgMessageCache;
    $wgMessageCache->addMessages(array('hello' => 'Hello page'));

    require_once('includes/SpecialPage.php');
    SpecialPage::addPage(new SpecialPage('Hello'));
}

?>

The first line appends our function's name (“wfExtensionSpecialHello”) to the global array $wgExtensionFunctions, putting this function in the directory of extensions. Many MediaWiki extensions change the output from certain tags; in this case, we are looking to create an entire page, rather than modify the behavior of a tag. Nevertheless, we are creating an extension.

Next, we define our function. The first thing that we do is modify $wgMessageCache, such that our extension will look like a special page rather than a tag-modifying extension. The special page will continue to work if we fail to include these initial two lines, but its listing on Special:Specialpages will look odd, with the title coming between < and > brackets as if it were a tag. Note that the page name must begin with a lowercase letter in the call to addMessages, even when it is capitalized in the call to SpecialPage::addPage. Failing to note this quirk of capitalization will result in strange page titles.

The final two lines import the code specific for special pages, and then create an instance of such a special page, adding it to the directory.

Just what our special page does depends on another file of the same name (that is, SpecialHello.php), located in the includes directory that is parallel to extensions, just under the MediaWiki DocumentRoot. This directory contains a large number of standard special pages that come with MediaWiki, including SpecialNewpages.php, SpecialUserrights.php and SpecialImagelist.php. These functions can access the back-end MySQL database, perform calculations and access external sites—and then pipe the results back into a standard MediaWiki output page.

Here is a simple version of what we might put into our includes/SpecialHello.php file:

<?php
function wfSpecialHello() {
global $wgOut;
$wgOut->addHTML('Hello, world');
}
?>

The above function, which is invoked whenever we go to the Special:Hello page, adds the HTML “Hello, world” to the output. Notice that we don't have to begin, end or otherwise modify the HTML file that is sent to the user. Nor do we need to worry about choosing a skin, setting up menus or other details. However, we do need to be careful about whitespace, as is often the case with PHP programs—failing to trim whitespace before the initial <?php tag might well produce odd error messages from PHP about modified headers.

Finally, we register our extension and special page in the LocalSettings.php file, adding the following line:

require_once("extensions/SpecialHello.php");

Once you have put the above in place, your site should now have a Special:Hello page, listed as Hello when you visit Special::Specialpages.