HTMLForm

From mediawiki.org
Jump to navigation Jump to search
This page is a translated version of the page HTMLForm and the translation is 73% complete.
Outdated translations are marked like this.
Other languages:
Deutsch • ‎English • ‎Türkçe • ‎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.

This roughly translates into the <select> type attribute. If 'class' is not specified, this is used as a map through HTMLForm::$typeMappings to get the class name.

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. This is NOT the CSS class!
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. Maps raw text labels to values. Some field types support multi-level arrays. Overwrites 'options-message'.
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

Subsections should make use of '/' character e.g. foo/bar/baz creates a preference 'baz' inside the section 'bar' which is inside the section 'foo'

label-message,

buttonlabel-message

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

Message key or object for a message to use as the label. Can be an array of msg key and then parameters to the message.

label,

label-raw, buttonlabel

string Etiquette du champ de saisie ou du bouton Overridden by hlabel-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 See HTMLFormField::validate()
filter-callback array Classe et fonction à utiliser pour filtrer l'entrée It gives you the chance to massage the inputted value before it's processed. See HTMLFormField::filter()
help-message string Clé pour un message i18n à afficher directement sous l'élément de formulaire Overwrites 'help-messages' and 'help'. Can be an array of msg key and then parameters to the message.
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 It is passed through to the object, indicating that it is a required field.
name string Remplace le nom de l'entrée (la valeur par défaut est wp{$fieldname})

If you want a different name (eg one without the "wp" prefix), specify it here and it will be used without 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.