HTMLForm/tutorial

From MediaWiki.org
Jump to navigation Jump to 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
/**
 * 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 = 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 = [];

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

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 {

    /**
     * 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