HTMLForm/tutorial

From MediaWiki.org
Jump to: navigation, search

HTMLFormHTMLForm is a powerful and easy helper to build forms within MediaWiki. This tutorial will help SpecialPages developers to get started with HTMLFormHTMLForm.

(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 StuffHTMLForm/tutorial2

Otherwise, let's get started...

Files and environment[edit]

This explanation applies to MediaWiki version 1.23 or thereabouts.

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 i18ni18n files can be found in the folder:

/mediawiki/extensions/MyForm/i18n

Before MediaWiki 1.25, the i18n file could be found in:

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

Then .hooks, .alias...

MyForm.php[edit]

<?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';

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

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


LocalSettings.php[edit]

Do not forget to install your extension by adding:

require_once( "$IP/extensions/MyForm/MyForm.php" );

MyForm.i18n.php[edit]

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[edit]

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");
    }


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

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

NEXT PAGE OF THE TUTORIAL