Manual:HTMLForm Tutorial 2

The rest of this page is about the use of HTMLForm through generic $formDescriptor entries (settings that are common to all fields types). We are therefore working only on HTMLTextField input.

Skip the generic part and directly go to the field specification stuff

Here we are in /mediawiki/extensions/MyForm/MyForm_body.php and working on the execute() function...

Starting point

public function execute( $par ) {
    $this->setHeaders();
    $this->getOutput()->addHTML( 'Hello World' );
}

Adding a Simple Text Field

Let's replace "Hello World" by a text field called simpletextfield

public function execute( $par ) {
    $this->setHeaders();

    // formDescriptor Array to tell HTMLForm what to build
    $formDescriptor = [
        'simpletextfield' => [
            'label' => 'Simple Text Field', // Label of the field
            'class' => 'HTMLTextField', // Input type
        ]
    ];

    // Build the HTMLForm object
    $htmlForm = HTMLForm::factory( 'table', $formDescriptor, $this->getContext() );

    // Text to display in submit button
    $htmlForm->setSubmitText( 'Allons-y gaiement' );

    $htmlForm->show(); // Display the form
}

Now, the form looks like:

Adding Callback

Sadly, the previous code displays the form, but the form doesn't work. We need to write some logic to process the form input!

public function execute( $par ) {
    $this->setHeaders();

    // formDescriptor Array to tell HTMLForm what to build
    $formDescriptor = [
        'simpletextfield' => [
            'label' => 'Simple Text Field', // Label of the field
            'class' => 'HTMLTextField', // Input type
        ]
    ];
    // Build the HTMLForm object, calling the form 'myform'
    $htmlForm = new HTMLForm( $formDescriptor, $this->getContext(), 'myform' );
    // Text to display in submit button
    $htmlForm->setSubmitText( 'Allons-y gaiement' );

    // We set a callback function
    $htmlForm->setSubmitCallback( [ $this, 'processInput' ] );  
    // Call processInput() in your extends SpecialPage class on submit

    // Display the form
    $htmlForm->show();
}

// Callback function
// OnSubmit Callback, here we do all the logic we want to do…
public static function processInput( $formData ) {
    // If true is returned, the form won't display again
    if ( $formData['simpletextfield'] === 'next' ) {
        return true; 
    } elseif ( $formData[ 'simpletextfield' ] === 'again' ) {
        // If false is returned, the form will be redisplayed
        return false;
    }

    // If a string is returned, it will be displayed as an error message with the form
    return 'Try again';
}

Now, the form processes the submitted data:

Submission method

The form can be set to use either the POST or GET submission method.

• POST (default): The form fields' contents are not shown in the page URL. This method should be used for forms that change the wiki content (e.g. edit pages or block users).
• GET: The form fields' contents are shown in the page URL. The resulting URL can be bookmarked or linked to allow others to view it. However, submission of very long forms (multiple kilobytes of text) may fail. This method should be used for forms that do not change the wiki content (e.g. show a list of pages).

If you are trying to submit the data via a GET request, you will have to add the following:

$htmlForm->setMethod( 'get' );

Note that GET forms using a check or multiselect field have to have a "form identifier" set to work correctly, same as if you were using multiple forms on one page – see Using multiple forms on a single page below.

Adding Validation

Fields can be individually validated before submit callback.

First we tell HTMLForm by adding this line:

// Call validateSimpteTextField() within your extends SpecialPage class
'validation-callback' => [ $this, 'validateSimpleTextField' ],

in formDescriptor:

// formDescriptor Array to tell HTMLForm what to build
$formDescriptor = [
    'simpletextfield' => [
        // Label of the field
        'label' => 'Simple Text Field',
        'class' => 'HTMLTextField',
        // Call validateSimpleTextField() within your extends SpecialPage class
        'validation-callback' => [ $this, 'validateSimpleTextField' ],
    ]
];

Then we write the validation logic:

public static function validateSimpleTextField( $simpleTextField, $allData ) {
    if ( $simpleTextField === 'merde' ) {
        return 'Excuse my French';
    }
    return true;
}

Now, the validation logic checks submitted data before processing:

Required Field

You can specify that a field is required by simply adding

'required' => true,

to the formDescriptor. Any validation-callback will overwrite required. If you want to validate a required field, add the following logic to your validation callback function:

if ( $simpleTextField === '' ) {
    return wfMessage( 'htmlform-required', 'parseinline' );
}

Adding Filtering

Filtering happens BEFORE validation to change input.

formDescriptor declaration:

'filter-callback' => [ $this, 'filterSimpleTextField' ],

Filtering logic:

public static function filterSimpleTextField( $simpleTextField, $allData ) {
    // Add "?!?" to the input 
    return $simpleTextField . '?!?';
}

Adding i18n support

This functionality allows to translate the label in the language defined in the user interface preferences. Just replace 'label' by 'label-message' in formDescriptor to automatically fetch the string through i18n routine:

 $formDescriptor = [
    'simpletextfield' => [
        // i18n message id for the field's label
        'label-message' => 'myform-simpletextfield',
        // Input type
        'class' => 'HTMLTextField',
        'validation-callback' => [ $this, 'validateSimpleTextField' ],
        'filter-callback' => [ $this, 'filterSimpleTextField' ],
    ]
];

Don't forget to add the correct entry in the localization files. For example here, in English and French :

"myform-simpletextfield": "International Simple Text Field"

"myform-simpletextfield": "Champ de texte simple international"

For the submit button, we need to do it "manually":

$htmlForm->setSubmitText( wfMessage( 'myform-submit' ) );

Of course, as always, you'll need to add the myform-submit entry in the localization files.

Adding sections

Now, we need to add some fields and organize them, let's switch to a bigger formDescriptor.

$formDescriptor = [
    'field1' => [
        'section' => 'section1',
        'class' => 'HTMLTextField',
        'label' => 'field1',
    ],
    'field2' => [
        'section' => 'section1',
        'class' => 'HTMLTextField',
        'label' => 'field1',
    ],
    'field3' => [
        'section' => 'section2',
        'class' => 'HTMLTextField',
        'label' => 'field1',
    ],
    'field4' => [
        'section' => 'section3',
        'class' => 'HTMLTextField',
        'label' => 'field1',
    ]
];

The section string displayed is automatically fetched from the localization files. Here we therefore need to add this in en.json:

{
    "section1": "The First Section",
    "section2": "Section II",
    "section3": "Third Section"
}

Now, the form looks like:

Subsections

Sections can be easily nested with the incredible power of /.

$formDescriptor = [
    'field1' => [
        'section' => 'section1',
        'class' => 'HTMLTextField',
        'label' => 'field1',
    ],
    'field2' => [
        'section' => 'section1/subsectionA',
        'class' => 'HTMLTextField',
        'label' => 'field1',
    ],
    'field3' => [
        'section' => 'section2/subsectionB',
        'class' => 'HTMLTextField',
        'label' => 'field1',
    ],
    'field4' => [
        'section' => 'section2/subsectionC',
        'class' => 'HTMLTextField',
        'label' => 'field1',
    ]
];

The i18n ID will be like:

'subsectionA'

Now, the form looks like:

Adding Help-text

What about providing users with instructions to use your form easily? help or help-message (an i18n message name) are here for you.

$formDescriptor = [
    'field1' => [
        'section' => 'section1',
        'class' => 'HTMLTextField',
        'label' => 'field1',
        'help' => 'Just say something!',
    ],
];

Now, the form looks like:

Adding html CLASS and ID

cssclass and id are here for you.

$formDescriptor = [
    'field1' => [
        'section' => 'section1',
        'class' => 'HTMLTextField',
        'label' => 'field1',
         // Add to the wrapper object class
        'cssclass' => 'AClassForField1',
        // Add to the input object
        'id' => 'AnIdForField1',
    ],
];

Changing Name of input

By default, input name is wp{$fieldname}, for the previous example, the input name is therefore wpfield1. This can be changed with name:

$formDescriptor = [
    'field1' => [
        'section' => 'section1',
        'class' => 'HTMLTextField',
        'label' => 'field1',
        'cssclass' => 'AClassForField1',
        'id' => 'AnIdForField1',
        'name' => 'ANameForField1',
    ],
];

Just to give you an idea, here is the HTML output generated:

<tr class="mw-htmlform-field-HTMLTextField AClassForField1">
    <td class="mw-label">
        <label for="AnIdForField1">field1</label>
    </td>
    <td class="mw-input">
        <input id="AnIdForField1" size="45" name="ANameForField1">
    </td>
</tr>

Disabling input

disabled is there and the user cannot change the input. (On some browsers it may not be possible to copy the value.) The item will not be sent to the server.

'disabled' => true,

As simple as that!

Turning input read-only

readonly is there, and the user cannot modify input. The item will be sent to the server.

'readonly' => true,

Again, as simple as that!

Using multiple forms on a single page

MediaWiki version:

≥ 1.28

If you use multiple forms on a single special page (e.g. one to show search results, and another to modify a result), you need to set a "form identifier" to allow HTMLForm to detect which of the forms was submitted. The identifier can be any string, and it must be different for every form.

$htmlForm->setFormIdentifier( 'myform1' );

For technical reasons, this is also necessary when using a check or multiselect field in a GET form; otherwise HTMLForm can't detect whether the form was submitted and therefore whether it should load the default values or not.

NEXT PAGE OF THE TUTORIAL