Manual:HTMLForm Tutorial

HTMLForm is a powerful and easy helper to build forms within MediaWiki. This tutorial will help Manual:Special pages developers to get started with HTMLForm.

(HTMLForm being a front-end helper, it's assumed that you are developing a front-end extension. ie: a special page)

The rest of this page is about the basics of creating a generic special page extension called MyForm. This is not directly related to this tutorial, but it won't hurt to show how the extension should look like. At the bottom of the page the Special:MyForm displays "Hello World".

Skip the newbie part and directly go to the HTMLForm stuff

Otherwise, let's get started...

Files and environment

This explanation applies to MediaWiki version 1.23 and later.

HTMLForm classes are located at /mediawiki/includes/HTMLForm.php. The code is pretty clean and well-documented enough, that should make MW Hackers happy.

Your SpecialPage is in an extension called MyForm. You'll find it by accessing Special:MyForm.

Your SpecialPage's front-end code can be at: /mediawiki/extensions/MyForm/MyForm_body.php This previous file enclosing both View/Controller, the Model (main file of your extension) can be at: /mediawiki/extensions/MyForm/MyForm.php The i18n files can be found in the folder: /mediawiki/extensions/MyForm/i18n Then .hooks, .alias... etc.

MyForm.php

New extensions should use Extension registration instead.

<?php
/**
 * Necessary description of @file, @authors and license
 * @FILLME!
 * Always good to remind that important part
 */
 
// Avoid illegal processing, doesn't cost much, but unnecessary on a correct installation
if ( !defined( 'MEDIAWIKI' ) ) { 
	die( -1 ); 
} 

// Extension Declaration
$wgExtensionCredits['specialpage'][] = [
	'path' => __FILE__,
	'name' => 'MyForm',
	'author' => 'My Name',
	'version' => '0.1.0',
	'url' => 'https://www.mediawiki.org/',
	'descriptionmsg' => 'myf-desc',
];

// A var to ease the referencing of files
$dir = __DIR__ . '/';

// i18n file referencing
$wgExtensionMessagesFiles['MyForm'] = $dir . 'MyForm.i18n.php';
// View file referencing
$wgAutoloadClasses['SpecialMyForm'] = $dir . 'MyForm_body.php';
// SpecialPage referencing
$wgSpecialPages['MyForm'] = 'SpecialMyForm';

// The Logic for your extension should be somewhere around here.

// NO PHP Closing bracket "? >". This is pure code.

LocalSettings.php

Do not forget to install your extension by adding: require_once( "$IP/extensions/MyForm/MyForm.php" );. When using extension registration, use wfLoadExtension( 'MyForm' ); instead.

MyForm.i18n.php

This file will hold all the messages used within your form. Be careful with the messages' IDs, they will be specified later in this tutorial.

<?php
// Internationalisation for MyForm extension
// @FILLME!

$messages = [];

// English
$messages['en'] = [
    'myf-desc' => 'A generic extension used by the HTMLForm tutorial'
];

// Message documentation (Message documentation)
$messages['qqq'] = [
	'myf-desc' => '{{desc}}'
];

// French
$messages['fr'] = [
    'myf-desc' => 'Une extension générique utilisée par le tutoriel d\'HTMLForm'
];

// More langages…

// NO PHP Closing bracket "? >". This is pure code.

MyForm_body.php

Finally, the file that interests us the most.

<?php
/**
 * Necessary description of @file, @authors and license
 * @FILLME!
 * Always good to remind that important part
 */
 
// Avoid illegal processing, doesn't cost much, but unnecessary on a correct installation
if ( !defined( 'MEDIAWIKI' ) ) { 
	die( -1 ); 
}  

// Our SpecialPage
class SpecialMyForm extends SpecialPage {
    public function __construct() {
        // The first argument must be the name of your special page
        // A second argument "right" can be added to restrict access to the SpecialPage
        parent::__construct( 'MyForm' );
    }

    /**
     * Special page entry point
     * @param string|null $par
     */
    public function execute( $par ) {
        $this->setHeaders();
        $this->getOutput()->addHTML( 'Hello World' );
    }

    protected function getGroupName() {
        return 'other';
    }
}

// NO PHP Closing bracket "? >". This is pure code.

Manual:HTMLForm Tutorial 2