MediaWiki Extension - How to develop custom extension in MediaWiki


This tutorial is about custom extension development in MediaWiki and works for any mediawiki version above 1.23. If you know MediaWiki and want to learn extension development Then you shall look into this simple tutorial which introduces you with file structure and basics fundamental of Extension development.

This Article is a bit advance level and requires programming skills and knowledge of PHP. If you are a MediaWiki user and know PHP you are at right spot. Though this tutorial only covers a basic and the sample application created would be only a wireframe to what a real MediaWiki extension could be.

Before we jump start to coding, let me explain how MediaWiki extensions work. MediaWiki is a PHP based wiki software which stores wiki pages. One example of MediaWiki is well known Wikipedia, which is also the largest wiki in existance till date. Now MediaWiki is a very basic form of Wiki but as it is a framework it allows several plugins which are known as Extension to help a user extend its functionality. These extensions make use of Hooks, which are the event triggers occuring during lifecycle of a wiki page. So a user can use these hooks and insert custom function to be performed at some specific time of wiki page lifecycle.

We are going to breakdown this tutorial in four smaller modules In first we explain the file structure and extension setup, later on we describe localization, resource loader module and use of ajax.

MediaWiki Extension - How to Develop custom extension in MediaWiki
MediaWiki Extension - Localization of MediaWiki Extension
MediaWiki Extension - Using Resource Loader to inject JavaScript and CSS
MediaWiki Extension - Enabling use of ajax in Extension

We use these very same Hooks to create the extension, There could be several types of extension, but in this tutorial we will create only a very simple one to show how these extensions work. You can do everything in one single file(not a good idea) or you can use a well organised strcuture to manage the extension structure as suggested by MediaWiki experts. The key files are:

Extension.php - The file which keeps the set up information and initialization elements.
Extension.body.php - The main class file for the extension which should keep the logic.
Extension.alias.php - The alias file which may keep the localization stuff
and/or
i18n/<lang>.json - the localised file that keeps the system messages

So without further time wasting we shall get started. I am using NetBeans for the development you can use whichever IDE or code editor you prefer.

1. Create a Directory for your extension in "extensions" directory.

2. Create the extension files in that Directory. In our case we are creating files by name of DemoExtension.
DemoExtension.php
DemoExtension.body.php
i18n/en.json

3.Start with the setup file: "DemoExtension.php" to register the extension when it is included in "LocalSettings.php". First things first, we need to make sure nobody can access the extension page directly so, we place an entrypoint check for the same.


if(!defined('MEDIAWIKI')){
    die("This is a mediawiki extension and cannot be accessed directly.");
}

4. After that we need to register our extension with MediaWiki settings and mark its existance. The purpose is served with the associative array $wgExtensionCredits. It takes a few K-V pairs which are as shown in the following code snippet.


$wgExtensionCredits['DemoExtension']['other'] = array(
    'path'=>__FILE__, //path of the extension setup file
    'name'=>'DemoExtension', // name of extension
    'author'=>'Mayank Tiwari', //name of author
    'url'=>'http://www.examsmyantra.com', //extension url where a user can find details about the extension.
    'description'=>'This is only a Demo version, it will serve as wireframe for something really good.', //description of extension
	 'version'=>'1.0.0', //version of extension
    'licence-name'=>'', //name or url to the license under which the extension is released
);

The comments with each line of K-V should be good enough to give the basic idea of what they are for. The keys in the $wgExtensionCredits are first for unique registration name and second key is optional, you can define what type of extension is this, if not provided it takes "other" as default.

To verify if your extension worked on not, include your extension in LocalSettings.php by including the extension setup file at the end of LocalSettings.php.


require_once "$IP/extensions/DemoExtension/DemoExtension.php";

now you should be able to see your extension listed in Special:Version page of your wiki.

Extension Development - Installation of Extension displayon Special:Version

5. Now that the extension is registered you can carry on and put in your logics to make it useful, for that, we are going to use the Hooks, you could directly plug in the hooks and make functions in the same file but instead it is a good practice to create another file for the logical functions. And we can load this file using $wgAutoloadClasses array.


//autoload classes
$wgAutoloadClasses['DemoExtension'] = __DIR__.'DemoExtension.body.php';

Where the DemoExtension.body file contains the actual class body. and its function in this case we are creating a function that will be hooked in into the mediawiki edit page. Not just like that, but we are using the hook here.


//hook function
$wgHooks['EditPage::showEditForm:initial'][] = 'DemoExtension::injectHTMLInEditor';

This hook allows us to inject the html at the end of the edit form it provides serveral positions where you could inject the HTML you can look the complete detais on this Hook here.

Now that we have hooked the function it is time to define the function.


class DemoExtension {
    public static function injectHTMLInEditor(&$editPage,&$output) {
		$editPage->editFormTextAfterWarn .='<div id="demoDiv" class="highlight-green">****Hi This is HTML Injected via Demo Extension****</div>';
		return true;
    }
}

we have created a static method and we are only injecting the static html right now just to show that the extension works, the parameters in the method are from the signature of the Hook function.

If you try to edit any article or create a new article you should see the HTML content or text we intend to inject into the edit form. just like in following Image.

Hook In action - Result From Extension Action hook

yes This is the simplest way of writing an extension for MediaWiki. But there is lot more, in Extension development then only using Hooks, to learn how to localize your extension using the i18n Directory. please see Mediawiki Extension Localization.