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. [1]