HTMLForm

This page is a translated version of the page HTMLForm and the translation is 100% complete.

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 :

les paramètres génériques est dans Tutoriel HTMLForm deuxième partie
les paramètres relatifs au type et à la classe est sur Tutoriel HTMLForm troisième partie

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. Cela se traduit approximativement par l'attribut de type `‎<select>`. Si 'class' n'est pas spécifié, il est utilisé comme une carte via HTMLForm::$typeMappings pour obtenir le nom de la classe.
class	string	Sous-classe PHP à utiliser pour ce contenu de formulaire. Ceci accomplit la même chose que le paramètre de type, mais plus directement. Ce n'est pas la classe CSS !
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 Fait correspondre les étiquettes de texte brut aux valeurs. Certains types de champ prennent en charge les tableaux multidimensionnels. Overwrites 'options-message'.
rows	array	Lignes à présenter dans un élément de formulaire de matrice de contrôle, ou nombre de lignes affichées pour l'élément de formulaire d'une 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 afficher un message i18n comme titre de section ou de sous-section. Les sous-sections doivent utiliser le caractère '/', p.ex. foo/bar/baz crée une préférence 'baz' à l'intérieur de la section 'bar' qui se trouve à l'intérieur de la section 'foo'
label-message, buttonlabel-message	string	Clé permettant à un message i18n d'être affiché sous la forme d'une étiquette pour un champ de saisie ou un bouton de formulaire. Clé de message ou objet d'un message à utiliser comme étiquette. Il peut s'agir d'un tableau de clés de messages puis des paramètres du message.
label, label-raw, buttonlabel	string	Libellé d'une entrée ou un bouton de formulaire. Réécrasé par label-message.
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
csshelpclass	string	classe CSS utilisée pour mettre en forme le texte d'aide
validation-callback	array	Classe et fonction à utiliser pour la validation de l'entrée Voir HTMLFormField::validate()
filter-callback	array	Classe et fonction à utiliser pour le filtrage des entrées. Il vous donne la possibilité de modifier la valeur entrée avant qu'elle ne soit traitée. Voir HTMLFormField::filter()
help-message	string	Clé permettant à un message i18n d'être affiché directement sous l'élément de formulaire. Remplace les messages 'help-messages' et 'help'. Il peut s'agir d'un tableau de clés de messages, et des paramètres de message.
help	string	Message à afficher directement sous l'élément de formulaire, et servant de texte d'aide.
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 Il est transmis à l'objet, indiquant qu'il s'agit d'un champ obligatoire.
name	string	Remplace le nom de l'entrée (la valeur par défaut est wp{$fieldname}) Si vous voulez un nom différent (par exemple un nom sans le préfixe "wp"), spécifiez-le ici et il sera utilisé tel quel.
dir	string	Direction de l'élément.
'options-messages'	array	associative array mapping message keys to values. Some field types support multi-level arrays. Overwrites 'options' and 'options-message'.
'options-message'	array	clé de message ou objet à analyser pour extraire la liste des options (comme 'ipbreason-dropdown').
'help-messages'	array	tableau des clés de messages ou d'objets. Comme ci-dessus chaque élément peut être un tableau de clés de messages et de paramètres. Il prévaut sur 'help'.
'help-inline'	array	Whether help text (defined using options above) will be shown inline after the input field, rather than in a popup. Defaults to true. Only used by OOUI form fields.
'hide-if'	array	expression given as an array stating when the field should be hidden. The first array value has to be the expression's logic operator. Suppo [ 'NOT', array $expression ] Pour masquer un champ si une expression donnée n'est pas vraie. '===' [ '===', string $fieldName, string $value ] To hide a field if another field identified by $field has the value $value. '!==' [ '!==', string $fieldName, string $value ] Same as [ 'NOT', [ '===', $fieldName, $value ] 'OR', 'AND', 'NOR', 'NAND' [ 'XXX', array $expression1, ..., array $expressionN ] To hide a field if one or more (OR), all (AND), neither (NOR) or not all (NAND) given expressions are evaluated as true. Les expressions seront passées à un premier module d'interface JavaScript qui entretiendra la visibilité du champ de manière continue.
nodata	boolean	if set (to any value, which casts to true), the data for this field will not be loaded from the actual request. Instead, always the default data is set as the value of this field.
default	string (or array)	Valeur(s) par défaut du champ (à ne pas confondre avec $wgDefaultUserOptions ) Note extensions/skins adding preferences via hook must make use of UserGetDefaultOptions to set default value.

Exemple d'utilisation

classe SpecialTestForm

<?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';

i18n/en.json

{
	"@metadata": {
		"authors": [
			"MW_Kappa"
		]
	},
	"testform-desc": "some informative text for page Special:Version",
	"section1": "display text for section1",
	"subsection": "display text for subsection"
}

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.