User:Xephyr826/Manual:Special Page Template/en

Basic special page template

This page provides a basic special page template you can use to start new special page extensions.

Most special page extensions require three files:

• Small setup file, which loads every time MediaWiki starts
• Localisation file
• File with the special page code

MediaWiki coding conventions define the three files like this:

• MyExtension/extension.json—the setup file.
• MyExtension/SpecialMyExtension_body.php—the special page code.
• i18n/*.json—the localisation file .

Place all of the files in a new directory inside your MediaWiki extensions/ directory.

You should name the special page file after the extension. For example, the Gadgets extension contains the file SpecialGadgets.php.

In the examples below, the special page's name is MyExtension.

After creating the your special page extension, add the following line to LocalSettings.php to enable your extension:

wfLoadExtension( 'MyExtension' );

The setup file

Example setup file for MyExtension/extension.json:

{
	"name": "MyExtension",
	"version": "0.0.0",
	"author": [
		"Your Name"
	],
	"url": "https://www.mediawiki.org/wiki/Extension:MyExtension",
	"descriptionmsg": "myextension-desc",
	"license-name": "MIT",
	"type": "other",
	"AutoloadClasses": {
		"SpecialMyExtension": "SpecialMyExtension_body.php"
	},
	"SpecialPages": {
		"MyExtension": "SpecialMyExtension"
	},
	"MessagesDirs": {
		"MyExtension": [
			"i18n"
		]
	},
	"manifest_version": 1
}

This file registers several important and mandatory things:

• The location of the SpecialMyExtension class
• The location of the localisation files
• The new special page and its class name

The special page file

The body file MyExtension/SpecialMyExtension_body.php) should contain a subclass of SpecialPage or one of its subclasses. This file loads automatically when someone requests the special page. The example below implements the subclass SpecialMyExtension.

You need the __construct() constructor because its first parameter names your special page. execute() is the main function called when someone accesses a special page. This function overloads the function SpecialPage::execute(). It passes the single parameter $par, the subpage component of the current title. For example, if someone follows a link to Special:MyExtension/foo, $par contains foo.

You should run Wikitext and HTML output through $wgOut. Do not use 'print' or 'echo' directly when working within the wiki's user interface.

<?php
class SpecialMyExtension extends SpecialPage {
	function __construct() {
		parent::__construct( 'MyExtension' );
	}

	function execute( $par ) {
		$request = $this->getRequest();
		$output = $this->getOutput();
		$this->setHeaders();

		# Get request data from, e.g.
		$param = $request->getText( 'param' );

		# Do stuff
		# ...
		$wikitext = 'Hello world!';
		$output->addWikiText( $wikitext );
	}
}

The localisation file

See Localisation for how to get them translated.

All special pages specify a title, like 'My Extension'.

• The title is used in the <title> and <H1> elements of the extension's page and on Special:SpecialPages.
• It can be anything, but should describe the special page and extension.
• The title is specified through a message. The structure of the message is a key-value pair. The key, 'myextension', must be all lowercase.

An example of a localisation file in MyExtension/i18n/en.json:

{
    "@metadata": {
        "authors": [
            "<your username>"
        ]
    },
    "myextension": "My Extension",
	"myextension-desc": "Adds the MyExtension functionality.",
	"myextension-summary": "On this special page, do this simple thing and earn wonders."
}

In i18n/qqq.json, the message documentation:

{
    "@metadata": {
        "authors": [
            "<your username>"
        ]
    },
    "myextension": "The name of the extension's entry in Special:SpecialPages",
    "myextension-desc": "{{desc}}",
    "myextension-summary": "Description appearing on top of Special:MyExtension."
}

Note that IDs should not start with an uppercase letter, and that a space in the ID should be written in the code as an underscore.

The -summary message is optional. It's created automatically by the parent class and shown on top of the special page, usually for a concise description of what the user can do on the special page. If you don't define summary content, the summary will only show when wiki administrators customize the summary on the wiki.

The aliases file

You can also internationalize the name of the special page by creating aliases for it. The example below uses the file "i18n/MyExtension.i18n.alias.php". In this example, the special page MyExtension registers an alias so the page becomes accessible at .../Special:My Extension and .../Spezial:Meine_Erweiterung in German.

Add your alias file to extension.json:

...
	"ExtensionMessagesFiles": {
		"MyExtensionAlias": "i18n/MyExtension.i18n.alias.php"
	},
...

Add special page aliases to i18n/MyExtension.i18n.alias.php:

<?php
/**
 * Aliases for myextension
 *
 * @file
 * @ingroup Extensions
 */

$specialPageAliases = array();

/** English
 * @author <your username>
 */
$specialPageAliases['en'] = array(
	'MyExtension' => array( 'MyExtension', 'My Extension' ),
);

/** Deutsch
 * @author <your username>
 */
$specialPageAliases['de'] = array(
	'MyExtension' => array( 'MeineErweiterung', 'Meine Erweiterung' ),
);

Again, you should write a space in the ID should as an underscore in the code.

For the page header and linking, the usual rules for page names apply.

If $wgCapitalLinks is true, a lowercase letter is converted to uppercase, and an underscore is displayed as a space.

For example, instead of the above, we could use 'my_extension' => 'My extension', assuming we consistently identified the extension as my_extension elsewhere.

Note that in the associative array for the English language, the string identifying our SpecialPage (MyExtension in the example,) is also a valid title.

Also note, the first element of $specialPageAliases['en']['MyExtension'] must be the same as the key ('MyExtension')! Otherwise Special:Specialpages will not list the page.

Special page group

You can set which group your special page appears under on Special:SpecialPages by overriding SpecialPage::getGroupName() in your subclass.

    /**
     * Override the parent to set where the special page appears on Special:SpecialPages
     * 'other' is the default. If that's what you want, you do not need to override.
     * Specify 'media' to use the <code>specialpages-group-media</code> system interface message, which translates to 'Media reports and uploads' in English;
     * 
     * @return string
     */
    function getGroupName() {
	return 'media';
    }

Some common values are 'login', 'maintenance', 'media', 'other', 'pagetools', 'redirects', 'users'.

You can see the accepted values at Special:AllMessages (search for specialpages-group) or browse the wiki using the pseudo language 'qqx' by going to Special:SpecialPages?uselang=qqx) and looking at the headings.

Specify the word 'media' to use the interface message 'specialpages-group-media'.

If your special page doesn't fit into any of the preconfigured headings, you can add a new heading by adding it to your localisation file, see The localisation file ).

The standard page groups that come with MediaWiki are listed in the localisation file. For example, the English messages are in languages/i18n/en.json) and begin with specialpages-group-.

If you want to categorize your special page under users, then the message is specialpages-group-users.

The value for this key is the text that appears as the name of that category, for example, Users and rights.

If your special page does not seem to fit under any of the existing categories, you can always make a new one.

In your extension's localisation file simply insert a new key for the messages array.

In this example, we define the gamification group:

{
    "myextension": "My Extension",
	"myextension-desc": "Adds the MyExtension functionality.",
	"myextension-summary": "On this special page, do this simple thing and earn wonders",
	"specialpages-group-gamification": "Gamification"
}

Now, assuming you set the return value for the method SpecialPage::getGroupName() as gamification in your class definition, reload Special:SpecialPages to see your new category.