HTMLForm

From mediawiki.org
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 :

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.