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...

Adding a Simple Text Field
Let's replace "Hello World" by a text field called 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! Now, the form processes the submitted data:



Submission method
The form can be set to use either the POST or GET submission method. if you are trying to submit the data via a GET request, you will have to add the following: and replace the   with  Note that GET forms using a   or   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.
 * 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).

Adding Validation
Fields can be individually validated before submit callback

First we tell HTMLForm by adding this line 'validation-callback' => array('SpecialMyForm', 'validateSimpleTextField'), #Calling validateSimpteTextField within SpecialMyForm in formDescriptor: Then we write the validation logic: 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 formDescriptor. Any validation-callback will overwrite required. If you want to validate a required field, add the following logic to your validation callback function:

Adding Filtering
Filtering happens BEFORE validation to change input.

formDescriptor declaration: 'filter-callback' => array('SpecialMyForm', 'filterSimpleTextField'),

Filtering logic

Adding i18n support
Replacing "label" by "label-message" in formDescriptor will automatically fetch the string through i18n routine: Don't forget to add the correct entry in the i18n file arrays: 'myform-simpletextfield' => 'International Simple Text Field' For example here, english and french... '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 i18n file.

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

The section string displayed is automatically fetched from i18n file. Here we therefore need to add this in our i18n file: Now, the form looks like:



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

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 (i18n ID) are here for you

Now, the form looks like:



Adding html CLASS and ID
cssclass and id are here for you

Changing Name of input
By default, input name is wp{$fieldname}, for the previous example, input name is therefore wpfield1. This can be changed with name : Just to give you an idea, here is the html output generated:

Disabling input
disabled is there, user cannot copy (CTRL-C) input. The item will not be valid for submission. 'disabled' => true, As simple as that!

Turning input read-only
readonly is there, user can copy (CTRL-C) input. 'readonly' => true, Again, as simple as that!

Using multiple forms on a single page
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. For technical reasons, this is also necessary when using a  or   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. (T166256#3290268)

NEXT PAGE OF THE TUTORIAL