Handbuch:HTML-Formular Tutorial 2

Der Rest dieser Seite befasst sich mit der Verwendung von HTML-Formular durch generische $formDescriptor-Einträge (Einstellungen, die für alle Feldtypen gelten). Wir arbeiten daher nur an HTMLTextField-Eingaben.

Überspringe den allgemeinen Teil und gehe direkt zur Feldspezifikation

Hier sind wir in /mediawiki/extensions/MyForm/MyForm_body.php und arbeiten an der execute()-Funktion ...

Start

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

Hinzufügen eines einfachen Textfeldes

Ersetzen wir "Hallo Welt" durch ein Textfeld namens simpletextfield

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

    // formDescriptor Feld, um HTML- Formular mitzuteilen, was erstellt werden soll
    $formDescriptor = [
        'simpletextfield' => [
            'label' => 'Simple Text Field', // Label of the field
            'class' => 'HTMLTextField', // Input type
        ]
    ];

    // Erstelle das Objekt im HTML-Formular
    $htmlForm = HTMLForm::factory( 'table', $formDescriptor, $this->getContext() );

    // Text, der in der Schaltfläche "Senden" angezeigt werden soll
    $htmlForm->setSubmitText( 'Allons-y gaiement' );

    $htmlForm->show(); // Anzeige des Formulars
}

Nun sieht das Formular wie folgt aus:

Callback hinzufügen

Leider zeigt der vorherige Code das Formular an, aber das Formular funktioniert nicht. Wir müssen eine Abfolge schreiben, um die Formulareingabe zu verarbeiten!

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

    // formDescriptor Feld, um HTML- Formular mitzuteilen, was erstellt werden soll
    $formDescriptor = [
        'simpletextfield' => [
            'label' => 'Simple Text Field', // Label of the field
            'class' => 'HTMLTextField', // Input type
        ]
    ];
    // Erstelle das HTMLFormular-Objekt und rufe das Formular "myform" auf
    $htmlForm = new HTMLForm( $formDescriptor, $this->getContext(), 'myform' );
    // Text, der in der Schaltfläche "Senden" angezeigt werden soll
    $htmlForm->setSubmitText( 'Allons-y gaiement' );

    // Wir erstellen eine callback-Funktion
    $htmlForm->setSubmitCallback( [ $this, 'processInput' ] );  
    // Rufe beim Senden processInput() in Deiner extends SpecialPage-Klasse auf

    // Anzeige des Formulars
    $htmlForm->show();
}

// Callback Function
// OnSubmit Callback, hier machen wir die ganze Logik, die wir machen wollen ...
public static function processInput( $formData ) {
    // Wenn "true" ausgegeben wird, wird das Formular nicht erneut angezeigt
    if ( $formData['simpletextfield'] === 'next' ) {
        return true; 
    } elseif ( $formData[ 'simpletextfield' ] === 'again' ) {
        // Wenn "false" ausgegeben wird, wird das Formular erneut angezeigt
        return false;
    }

    // Wenn eine Zeichenfolge zurückgegeben wird, wird sie im Formular als Fehlermeldung angezeigt
    return 'Try again';
}

Das Formular verarbeitet nun die übermittelten Daten:

Übermittlungsmethode

Das Formular kann so eingestellt werden, dass entweder die POST- oder die GET-Übermittlungsmethode verwendet wird.

• POST (Standardeinstellung): Der Inhalt der Formularfelder wird in der Seiten-URL nicht angezeigt. Diese Methode sollte für Formulare verwendet werden, die den Wiki-Inhalt ändern (z. B. Seiten bearbeiten oder Benutzer blockieren).
• GET: Der Inhalt der Formularfelder wird in der Seiten-URL angezeigt. Die resultierende URL kann mit einem Lesezeichen versehen oder verknüpft werden, damit andere sie anzeigen können. Die Übermittlung sehr langer Formulare (mehrere Kilobyte Text) kann jedoch fehlschlagen. Diese Methode sollte für Formulare verwendet werden, die den Wiki-Inhalt nicht ändern (z. B. eine Liste von Seiten anzeigen).

Wenn Du vor hast, die Daten über eine GET-Anforderung zu übermitteln, musst Du Folgendes hinzufügen:

$htmlForm->setMethod( 'get' );

Beachte, dass für GET-Formulare, die ein check- oder multiselect -Feld verwenden, eine "Formular-ID" festgelegt sein muss, damit sie ordnungsgemäß funktioniert, genauso wie wenn Du mehrere Formulare auf einer Seite verwendest – siehe unten: Verwendung mehrerer Formulare auf einer Seite.

Validierung hinzufügen

Felder können vor dem Absenden eines callbacks einzeln validiert werden.

Zuerst geben wir die Anweisung HTMLForm, indem wir diese Zeile hinzufügen:

// Rufe validateSimpteTextField() in Deiner Erweiterung der SpecialPage-Klasse auf
'validation-callback' => [ $this, 'validateSimpleTextField' ],

in formDescriptor:

// formDescriptor Feld, um HTMLForm mitzuteilen, was erstellt werden soll
$formDescriptor = [
    'simpletextfield' => [
        // Bezeichnung des Feldes
        'label' => 'Simple Text Field',
        'class' => 'HTMLTextField',
        // Rufe validateSimpteTextField() in Deiner Erweiterung der SpecialPage-Klasse auf
        'validation-callback' => [ $this, 'validateSimpleTextField' ],
    ]
];

Dann schreiben wir die Validierungslogik:

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

Die Validierungslogik überprüft nun die übermittelten Daten vor der Verarbeitung:

Erforderliches Feld

Du kannst angeben, dass ein Feld erforderlich ist, indem Du es einfach

'required' => true,

zum formDescriptor hinzufügst. Jeder validation-callback wird überschrieben. Wenn du ein erforderliches Feld validieren möchtest, füge Deiner Validierungs-callback.Funktion die folgende Logik hinzu:

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

Filter hinzufügen

Die Filterung erfolgt VOR der Validierung, um die Eingabe zu ändern.

formDescriptor-Deklaration:

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

Filterlogik:

public static function filterSimpleTextField( $simpleTextField, $allData ) {
    // Füge "?!?" der Eingabe hinzu 
    return $simpleTextField . '?!?';
}

Hinzufügen einer i18n Unterstützung

Mit dieser Funktion kannst Du das Label in die Sprache übersetzen, die in den Benutzereinstellungen definiert ist. Ersetze einfach 'label' durch 'label-message' im formDescriptor, um die Zeichenfolge automatisch über die i18n-Routine abzurufen:

 $formDescriptor = [
    'simpletextfield' => [
        // i18n-Nachricht-ID für die Feldbezeichnung
        'label-message' => 'myform-simpletextfield',
        // Eingabetyp
        'class' => 'HTMLTextField',
        'validation-callback' => [ $this, 'validateSimpleTextField' ],
        'filter-callback' => [ $this, 'filterSimpleTextField' ],
    ]
];

Vergiss nicht, den richtigen Eintrag in die Lokalisierungsdateien aufzunehmen. Zum Beispiel hier in Englisch und Französisch:

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

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

Für den Sende-Button müssen wir es "manuell" eintragen:

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

Natürlich musst Du, wie immer, den Eintrag myform-submit in die Lokalisierungsdateien einfügen.

Abschnitte hinzufügen

Jetzt müssen wir einige Felder hinzufügen und sie organisieren. Dafür wechseln wir zu einem größeren 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',
    ]
];

Die angezeigte Abschnittszeichenfolge wird automatisch aus den Lokalisierungsdateien abgerufen. Hier müssen wir Folgendes in en.json: hinzufügen:

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

Nun sieht das Formular wie folgt aus:

Unterabschnitte

Abschnitte können leicht mit der mächtigen Stärke von / verschachtelt werden.

$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',
    ]
];

Die i18n ID sieht dann so aus:

'subsectionA'

Nun sieht das Formular wie folgt aus:

Hilfetext hinzufügen

Wie wäre es, Benutzern Anweisungen zur einfachen Verwendung Deines Formulars zu geben? help oder help-message (ein i18n-Nachrichtenname) sind dafür da.

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

Nun sieht das Formular wie folgt aus:

Hinzufügen von html CLASS und ID

Dafür sind cssclass und id da.

$formDescriptor = [
    'field1' => [
        'section' => 'section1',
        'class' => 'HTMLTextField',
        'label' => 'field1',
         // Füge zur Wrapper-Objektklasse hinzu
        'cssclass' => 'AClassForField1',
        // Zum Eingabeobjekt hinzufügen
        'id' => 'AnIdForField1',
    ],
];

Änderung der Eingabe-Bezeichnung

Standardmäßig lautet der Eingabename wp{$fieldname}. Im vorherigen Beispiel lautet der Eingabename daher wpfield1. Dies kann mit name geändert werden:

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

Damit Du Dir das vorstellen kannst, wird die HTML-Ausgabe wie folgt generiert:

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

Eingabe deaktivieren

disabled steht dort und der Benutzer kann mittels (STRG-C) keine Eingaben kopieren. Die Eingabe kann nicht hochgeladen werden. (On some browsers it may not be possible to copy the value.) The item will not be sent to the server.

'disabled' => true,

So einfach ist das!

Eingabe schreibgeschützt

readonly (schreibgeschützt) ist eingetragen und der Benutzer kann keine Einträge ändern. The item will be sent to the server.

'readonly' => true,

Auch dies ist so einfach!

Verwendung mehrerer Formulare in einer einzelnen Seite

MediaWiki Version:

≥ 1.28

Wenn Du mehrere Formulare auf einer einzelnen, speziellen Seite verwendest (z. B. eines zum Anzeigen von Suchergebnissen und eines zum Ändern eines Ergebnisses), musst Du eine "Formular-ID" festlegen, damit HTMLForm erkennen kann, welches der Formulare gesendet wurde. Die Bezeichnung kann eine beliebige Zeichenfolge sein, muss jedoch für jedes Formular unterschiedlich sein.

$htmlForm->setFormIdentifier( 'myform1' );

Aus technischen Gründen ist dies auch erforderlich, wenn ein check- oder multiselect-Feld in einem GET-Formular verwendet wird. Andernfalls kann HTMLForm nicht erkennen, ob das Formular gesendet wurde und daher, ob die Standardwerte geladen werden sollen oder nicht.

NÄCHSTE SEITE DES TUTORIALS