User:Xephyr826/Manual:Special Page Template

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:


 * &mdash;the setup file.
 * &mdash;the special page code.
 * &mdash;the .

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>Special:MyLanguage/Extension:Gadgets|Gadgets extension contains the file  .

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:

The setup file
Example setup file for MyExtension/extension.json:

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  ) 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   constructor because its first parameter names your special page.  </> is the main function called when someone accesses a special page. This function overloads the function <tvar|SpecialPage> </>. It passes the single parameter <tvar|par> </>, the subpage component of the current title. For example, if someone follows a link to Special:MyExtension/foo</>,  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.

The localisation file

 * See <tvar|1></> for how to get them translated.

All special pages specify a title, like <tvar|Myextension>'My Extension'</tt></>.


 * The title is used in the <tvar|title> </tt></> and <tvar|H1> <H1> </tt></> elements of the extension's page and on <tvar|SpecialPages>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, <tvar|myext>'myextension'</tt></>, must be all lowercase.

An example of a localisation file in <tvar|i18n> </>:

In <tvar|qqq> </>, the msgdoc>Special:MyLangauage/Localisation#Message documentation</>|message documentation:

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 <tvar|MyExtension> </> registers an alias so the page becomes accessible at <tvar|tt>.../Special:My Extension</tt></> and <tvar|tt1>.../Spezial:Meine_Erweiterung</tt></> in German.

Add your alias file to extension.json</tt>:

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

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 <tvar|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 <tvar|code> </>, assuming we consistently identified the extension as <tvar|tt2>my_extension</tt></> elsewhere.

Note that in the associative array for the English language, the string identifying our SpecialPage (<tvar|code1> </> in the example,) is also a valid title.

Also note, the first element of <tvar|specialPageAliases> </> must be the same as the key (<tvar|code2> </>)! Otherwise <tvar|special>Special:Specialpages</> will not list the page.

Special page group
You can set which group your special page appears under on <tvar|special>Special:SpecialPages</> by overriding SpecialPage::getGroupName in your subclass.

</> 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 <tvar|AllMessages> Special:AllMessages </> (search for specialpages-group) or browse the wiki using the pseudo language 'qqx' by going to <tvar|uselang> 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 <tvar|TheLocalisationFile></>).

The standard page groups that come with MediaWiki are listed in the localisation file. For example, the English messages are in <tvar|json> </>) and begin with <tvar|specialpagesgroup> </>.

If you want to categorize your special page under <tvar|users> </>, then the message is <tvar|msg> </>.

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

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 <tvar|messages> </> array.

In this example, we define the <tvar|gamification> </> group:

Now, assuming you set the return value for the method SpecialPage::getGroupName as gamification</tt> in your class definition, reload <tvar|special>Special:SpecialPages</> to see your new category.