HTMLForm

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page HTMLForm and the translation is 98% complete.
Outdated translations are marked like this.
Other languages:
Deutsch • ‎English • ‎dansk • ‎español • ‎français • ‎polski • ‎português do Brasil • ‎русский • ‎中文 • ‎日本語

HTMLForm est une classe pour manipuler tout ce qui a rapport aux formulaires de l'interface utilisateur. MediaWiki 1.16 et ultérieur incluent HTMLForm dans HTMLForm.php.

HTMLForm/tutorial donne les bases de HTMLForm.

Paramètres

La spécification précise pour :

Paramètre Type Description
type string Type de contenu de formulaire à créer. Par exemple : text, radio, ou multiselect. Ils vont correspondre à des sous-classes spécifiques de HTMLForm.
class string Sous classes à utiliser pour ce contenu de formulaire. Ceci réalise la même chose que le paramètre 'type', mais plus directement.
size integer Longueur des champs de texte
maxlength integer Longueur maximale des champs de texte
min integer Quantité minimale de la valeur
max integer Quantité maximale de la valeur
invert boolean Initialise les entrées de type bascule, à coché par défaut
options array Options à afficher dans le cas d'un élément de formulaire : multiselect, radio, ou select
rows array Lignes à afficher pour un élément de formulaire de type matrice à cocher, ou nombre de lignes affichées pour un élément de type zone de texte
columns array Colonnes à afficher pour un élément matrice à cocher
force-options-off array Options à laisser non cochée et désactivée dans un élément de formulaire matrice à cocher
force-options-on array Options à laisser cochée et activée dans un élément de formulaire matrice à cocher
section string Clé pour qu'un message i18n s'affiche en tant que titre de section ou de sous-section
label-message,

buttonlabel-message

string Clé pour qu'un message i18n s'affiche en tant qu'étiquette de formulaire de saisie ou de bouton
label,

label-raw, buttonlabel

string Etiquette du champ de saisie ou du bouton
vertical-label boolean Mis à true si vous voulez que l'étiquette soit située au-dessus des options plutôt qu'à leur gauche
id string ID de l'attribut à assigner à l'entrée
cssclass string Classe de l'attibut à assigner à l'entrée
validation-callback array Classe et fonction à utiliser pour la validation de l'entrée
filter-callback array Classe et fonction à utiliser pour filtrer l'entrée
help-message string Clé pour un message i18n à afficher directement sous l'élément de formulaire
help string Message à afficher directement sous l'élément de formulaire
tooltip string Suffixe de la clé des messages i18n à utiliser pour le titre et/ou les attributs accesskey (tooltip-YOURVALUE et accesskey-YOURVALUE)
placeholder string Valeur à utiliser pour l'attribut HTML5 à substituer
placeholder-message string Clé du message i18n à afficher après substitution
disabled boolean Ne pas autoriser la modification des entrées du formulaire ni son envoi
readonly boolean Ne pas autoriser la modification des entrées du formulaire
required boolean Si true, l'entrée ne peut être laissée vide
name string Remplace le nom de l'entrée (la valeur par défaut est wp{$fieldname})
default string (or array) Valeur(s) par défaut du champs (à ne pas confondre avec $wgDefaultUserOptions)

Exemple d'utilisation

<?php

class SpecialTestForm extends SpecialPage {
	public function __construct() {
		parent::__construct( 'TestForm' );
	}

	public function execute( $par ) {
		$this->getOutput()->setPageTitle( 'Test form' );

		$formDescriptor = [
			'myfield1' => [
				'section' => 'section1/subsection',
				'label-message' => 'testform-myfield1',
				'type' => 'text',
				'default' => 'Meep',
			],
			'myfield2' => [
				'section' => 'section1',
				'class' => 'HTMLTextField', // HTMLTextField same as type 'text'
				'label-message' => 'testform-myfield2',
			],
			'myfield3' => [
				'class' => 'HTMLTextField',
				'label' => 'Foo bar baz',
			],
			'myfield4' => [
				'class' => 'HTMLCheckField',
				'label' => 'This be a pirate checkbox',
				'default' => true,
			],
			'omgaselectbox' => [
				'class' => 'HTMLSelectField',
				'label' => 'Select an oooption',
				'options' => [
					'Pirates' => 'pirate',
					'Ninjas' => 'ninja',
					'Back to the NINJAR!' => 'ninjars',
				],
			],
			'omgmultiselect' => [
				'class' => 'HTMLMultiSelectField',
				'label' => 'Weapons to use',
				'options' => [
					'Cannons' => 'cannon',
					'Swords' => 'sword',
				],
				'default' => [ 'sword' ],
			],
			'radiolol' => [
				'class' => 'HTMLRadioField',
				'label' => 'Who do you like?',
				'options' => [
					'Pirates' => 'pirates',
					'Ninjas' => 'ninjas',
					'Both' => 'both',
				],
				'default' => 'pirates',
			],
		];

		$htmlForm = new HTMLForm( $formDescriptor, $this->getContext() );
		$htmlForm
			->setSubmitText( 'Foo submit' )
			->setSubmitCallback( [ $this, 'trySubmit' ] )
			->show();
	}

	public function trySubmit( $formData ) {
		if ( $formData[ 'myfield1' ] === 'Fleep' ) {
			return true;
		}

		return 'Fail';
	}
}

$wgSpecialPages['TestForm'] = 'SpecialTestForm';

Formats d'affichage

Le format d'affichage par défaut pour HTMLForm est un affichage de type table, avec des étiquettes dans la colonne de gauche et des entrées dans la colonne de droite. Il est possible de sélectionner quelques formats différents, par exemple $htmlForm->setDisplayFormat( 'div' ); utilisera une disposition basée sur les div, les autres plus rares étant raw et inline.

Version de MediaWiki : 1.26

Pour modifier le formulaire pour qu'il utilise la boîte à outils OOUI pour les éléments HTMLform, à partir de MediaWiki 1.26, vous devez utiliser 'ooui' comme format d'affichage dans HTMLForm::factory :

$htmlForm = HTMLForm::factory( 'ooui', $formDescriptor, $this->getContext() );

Notes historiques

HTMLForm a été introduit par Werdna dans r48740 comme partie de ses redéfinitions des préférences système. Historiquement, les versions MediaWiki de la 1.4.0 à la 1.11 incluaient une classe HTMLForm différente, écrite par Hashar et JeLuF. Cette HTMLForm a été supprimée dans r29245.