HTMLForm/tutorial

HTMLForm is a powerful and easy helper to build forms within MediaWiki. This tutorial will help SpecialPages 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 SpecialPage Extension called MyForm. This is not directly related to this tutorial, but I guess 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 Environment

HTMLForm Classes are at

/mediawiki/includes/HTMLForm.php

Code is pretty clean and well-documented enough, that should make MW Hackers happy.

Your SpecialPage is in an extension called MyForm. You'll call 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 file can be at:

/mediawiki/extensions/MyForm/MyForm.i18n.php

Then .hooks, .alias...

MyForm.php

<?php
# Here the necessary description of file, authors and license
# @FILLME!
# Always good to remind that important part
 
# Avoids illegal processing, doesn't cost much, but unnecessary on a correct installation
if (!defined('MEDIAWIKI')) { die(-1); } 
 
# Extension Declaration
$wgExtensionCredits['specialpage'][] = array(
	'path' => __FILE__,
	'name' => 'MyForm',
	'author' => 'My Name',
	'version' => '0.1.0',
	'url' => 'http://www.mediawiki.org/',
	'descriptionmsg' => 'myf-desc',
);
 
# A var to ease the referencing of files
$dir = dirname(__FILE__) . '/';
 
# i18n file referencing
$wgExtensionMessagesFiles['MyForm'] = $dir . 'MyForm.i18n.php';
# View file referencing
$wgAutoloadClasses['SpecialMyForm'] = $dir . 'MyForm_body.php';
# SpecialPage referencing
$wgSpecialPages['MyForm'] = 'SpecialMyForm';
# SpecialPage category
$wgSpecialPageGroups['MyForm'] = 'other';
 
# 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" );

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 = array();
 
# English
$messages['en'] = array(
        'myf-desc' => 'A generic extension used by the HTMLForm tutorial'
);
 
# Message documentation (Message documentation)
$messages['qqq'] = array(
	'myf-desc' => '{{desc}}'
);
 
# French
$messages['fr'] = array(
        '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
# Here the necessary description of file, authors and license
# @FILLME!
# Always good to remind that important part
 
# Avoids illegal processing, doesn't cost much, but unnecessary on a correct installation
if (!defined('MEDIAWIKI')) { die(-1); } 
 
# Our SpecialPage
class SpecialMyForm extends SpecialPage {
 
    /**
     * Constructor : initialise object
     * Get data POSTed through the form and assign them to the object
     * @param $request WebRequest : data posted.
     */
    public function __construct($request = null) {
        parent::__construct('MyForm');   #The first argument must be the name of your special page
                             #A second argument "right" can be added to restrict access to the SpecialPage.
    }
 
    /**
     * Special page entry point
     */
    public function execute($par) {
        $this->setHeaders();
        $this->getOutput()->addHTML("Hello World");
    }
 
}
 
# NO PHP Closing bracket "? >". This is pure code.

NEXT PAGE OF THE TUTORIAL