HTMLForm

From mediawiki.org
Jump to navigation Jump to search
This page is a translated version of the page HTMLForm and the translation is 91% 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 Mappe les étiquettes de texte brut aux valeurs. Certains types de champ prennent en charge les tableaux multi-niveaux. 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 de 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 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 Touche permettant à un message i18n de s'afficher sous la forme d'une étiquette pour une entrée/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 msg, puis de paramètres du message.
label,

label-raw, buttonlabel

string Libellé d'une entrée/d'un bouton de formulaire. Remplacé 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 CSS class used to style help text
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 d'entrée. Il vous donne la possibilité de masser la valeur entrée avant qu'elle ne soit traitée. Voir HTMLFormField::filter()
help-message string Touche permettant à un message i18n de s'afficher directement sous l'élément de formulaire. Remplace les messages d'aide et d'aide. Il peut s'agir d'un tableau de clés msg, puis de paramètres du message.
help string Message à afficher directement sous l'élément de formulaire à utiliser comme 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 sans le préfixe "wp"), spécifiez-le ici et il sera utilisé sans modification.

dir string Direction of the element.
'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 message key or object to be parsed to extract the list of options (like 'ipbreason-dropdown').
'help-messages' array array of message keys/objects. As above, each item can be an array of msg key and then parameters. Overwrites '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 ] To hide a field if a given expression is not true.

'==='

[ '===', 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.


The expressions will be given to a JavaScript frontend module which will continually update the field's visibility.

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 )

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.