OOUI/Utiliser OOUI dans MediaWiki

From mediawiki.org
This page is a translated version of the page OOUI/Using OOUI in MediaWiki and the translation is 100% complete.
Languages:

OOUI est inclus dans le noyau de MediaWiki; il peut être utilisé à la fois par le code PHP et par JavaScript.

PHP

Avant de commencer

Pour utiliser les éléments OOUI, la bibliothèque PHP OOUI doit être chargée et les styles nécessaires doivent avoir été définis par l'habillage adéquat (détails fastidieux).

La manière la plus pratique est de parcourir les éléments suivants.

Pages spéciales etc.

Partout où vous avez accès à une instance de OutputPage, appelez sa méthode enableOOUI(). Elle est actuellement accessible via $this->getOutput() dans la plupart des contextes, comme sur les pages spéciales, ou comme $out dans la signature des accroches.

Exemple : 

function execute( $param ) {
	$out = $this->getOutput();
	$out->enableOOUI();
	// … écrivez votre code ici …
	$group = new OOUI\ButtonGroupWidget( [
		// … ajoutez vos widgets ici …
	] );
	$out->addHTML( $group );
}

Autre exemple, utile quand vous n'avez pas d'accès facile à une instance de OutputPage : 

RequestContext::getMain()->getOutput()->enableOOUI();

Notez que la méthode enableOOUI() (implémentée par la classe OutputPage ) assure que le bon thème et la directionalité sont configurés correctement, et que la page charge les styles OOUI. Les widgets OOUI sont répartis par espace de noms, ils doivent donc être préfixés avec OOUI\ ou être importés. Convertir le widget en chaîne de caractères le transforme en HTML, de sorte que vous pouvez ajouter les widgets à la page en utilisant $out->addHTML(). Notez également que dans certains cas, activer OOUI n'est pas suffisant. Par exemple si vous voulez ajouter une icône spécifique, vous devrez explicitement ajouter le paquet d'icônes associé.

Exemple : 

public function load() {
    $this->getOutput()->enableOOUI();
    $this->getOutput()->addModuleStyles( [ 'oojs-ui.styles.icons-moderation' ] );
    return ( new OOUI\IconWidget(
		[
			'icon' => 'block',
			'classes' => [ 'flaggedrevs-icon' ],
			'title' => 'Block',
		]
	) )->toString();
}

Fonctions et balises d'analyseur, modèles de contenu

Si vous avez accès à une instance de ParserOutput (habituellement comme $parser->getOutput() ou $pout), appelez sa méthode setEnableOOUI( true ) et également OutputPage::setupOOUI().

Exemple : 

public static function myTagHook( $content, array $attributes, Parser $parser, PPFrame $frame ) {
	OutputPage::setupOOUI();
	$parser->getOutput()->setEnableOOUI( true );
	// … écrivez votre code ici …
	$group = new OOUI\ButtonGroupWidget( [
		// … ajoutez vos widgets ici …
	] );
	return [ $group->toString(), 'markerType' => 'nowiki' ];
}

Dans les autres cas

Voir Avant de commencer. (au lieu d'utiliser les balises ‎<link>, servez vous des modules de style ResourceLoader décrits ci-dessous).

Utiliser les widgets OOUI

Construire un widget : 

$btn = new OOUI\ButtonWidget( [
    'label' => 'Click me!',
    'href' => 'https://example.com',
] );

Ses propriétés peuvent être modifiées à l'aide de ses méthodes getter et setter : 

$btn->setLabel( 'Still click me!' );

Une fois la création du widget terminée, vous pouvez l'utiliser comme une chaîne pour l'afficher (vous pouvez faire explicitement la conversion en chaîne en appelant la méthode toString()). 

$this->getOutput()->addHTML( "<div>$btn</div>" );

Liste des éléments disponibles

Voir aussi :

Depuis OOUI v0.34.0 diffusé le 4 septembre 2019, les éléments disponibles dans PHP (ou dans JavaScript via oojs-ui-core, voir ci-dessous) sont :

Widgets:

  • ButtonWidget
  • ButtonInputWidget
  • ButtonGroupWidget
  • CheckboxInputWidget
  • CheckboxMultiselectInputWidget
  • RadioInputWidget
  • RadioSelectInputWidget
  • TextInputWidget
  • MultilineTextInputWidget
  • NumberInputWidget
  • SearchInputWidget
  • DropdownInputWidget
  • ComboBoxInputWidget
  • LabelWidget
  • IconWidget
  • IndicatorWidget
  • ProgressBarWidget
  • SelectFileInputWidget
  • SelectWidget
  • TabSelectWidget
  • TabOptionWidget

Layouts:

  • ActionFieldLayout
  • FieldLayout
  • FieldsetLayout
  • FormLayout
  • HorizontalLayout
  • IndexLayout
  • MenuLayout
  • PanelLayout
  • TabPanelLayout
  • StackLayout

Exemple

De longues structures peuvent être créées et affichées à l'aide d'un un unique appel : 

$this->getOutput()->addHTML( new OOUI\FormLayout( [
	'method' => 'POST',
	'action' => 'login.php',
	'items' => [
		new OOUI\FieldsetLayout( [
			'label' => 'Form layout',
			'items' => [
				new OOUI\FieldLayout(
					new OOUI\TextInputWidget( [
						'name' => 'username',
					] ),
					[
						'label' => 'User name',
						'align' => 'top',
					]
				),
				new OOUI\FieldLayout(
					new OOUI\TextInputWidget( [
						'name' => 'password',
						'type' => 'password',
					] ),
					[
						'label' => 'Password',
						'align' => 'top',
					]
				),
				new OOUI\FieldLayout(
					new OOUI\CheckboxInputWidget( [
						'name' => 'rememberme',
						'selected' => true,
					] ),
					[
						'label' => 'Remember me',
						'align' => 'inline',
					]
				),
				new OOUI\FieldLayout(
					new OOUI\ButtonInputWidget( [
						'name' => 'login',
						'label' => 'Log in',
						'type' => 'submit',
						'flags' => [ 'primary', 'progressive' ],
						'icon' => 'check',
					] ),
					[
						'label' => null,
						'align' => 'top',
					]
				),
			]
		] )
	]
] ) );

HTMLForm , FormSpecialPage

HTMLForm prend en charge OOUI. Vous pouvez utiliser le format d'affichage ooui des formulaires HTMLForm pour les générer par OOUI. C'est en général plus pratique car HTMLForm fournit la fonctionnalité pour valider et gérer l'envoi du formulaire. Voir les formats d'affichage HTMLForm. 

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

Sur FormSpecialPage, utilisez la méthode getDisplayFormat() : 

protected function getDisplayFormat() {
	return 'ooui';
}

Exemples :

Les widgets utilisés dans le formulaire seront automatiquement infusés (voir ci-dessous) si le widget JavaScript offre des capacités supplémentaires par rapport au PHP.

JavaScript

Utilisation des widgets OOUI

En fonction de la fonctionnalité vous allez utiliser, listez un ou plusieurs des modules suivants présent dans vos dépendances de modules qui utilisent OOUI :

Par exemple (extension.json) : 

{
	"ResourceModules": {
		"ext.myExtension": {
			"dependencies": [
				"oojs-ui-core",
				"oojs-ui-windows"
			],
			"scripts": [
				...
			]
		}
	}
}

Le code des modules dépendants de OOUI peut utiliser les éléments comme indiqué dans documentation OOUI. Commencer ici la lecture.

Infusion

Afin de fournir un accroissement progressif et pour éviter la duplication du code entre PHP et JavaScript, les widgets OOUI PHP présents sur une page peuvent être infusés à l'intérieur des widgets OOUI.

En supposant qu'un widget PHP a été déclaré infusable à sa création : 

$btn = new OOUI\ButtonWidget( [
    'infusable' => true,
    'id' => 'my-button',
    'label' => 'Click me!',
    'href' => 'https://example.com',
] );

Il peut être infusé à partir du code JavaScript : 

var button = OO.ui.infuse( $( '#my-button' ) );
// Ou, pour un code auto-documenté :
var button = OO.ui.ButtonWidget.static.infuse( $( '#my-button' ) );

Le widget peut maintenant être modifié à partir du code JavaScript : 

button
	.setLabel( 'Really click me!' )
	.on( 'click', function () {
		alert( 'I was clicked!' );
	} );

Gadgets

OOUI peut être utilisé dans les gadgets du wiki et dans les scripts des utilisateurs. Comme ci-dessus, il suffit de s'assurer que le module oojs-ui-core (ou un module différent) est chargé, avant d'exécuter votre code.

Pour les gadgets, vous devez ajouter une entrée dans le champ dependencies de la description du gadget. Voir la Documentation du gadget pour les instructions et les exemples.

Pour les scripts utilisateur, entourez votre code dans un appel à mw.loader.using( … ), comme c'est toujours le cas lorsque vous chargez des modules. Pour les instructions, voir la documentation du ResourceLoader. Exemple : 

mw.loader.using( 'oojs-ui-core' ).done( function () {
	$( function () {
		var button = new OO.ui.ButtonWidget( {
			label: 'Click me!'
		} );
		button.on( 'click', function () {
			alert( 'You clicked the button!' );
		} );
		$( '#mw-content-text' ).append( button.$element );
	} );
} );

Widgets OOUI spécifiques à MediaWiki

Plusieurs widgets OOUI spécifiques à MediaWiki sont disponibles dans les espaces de noms mw.widgets (pour JavaScript) et MediaWiki\Widget (pour PHP); ils implémentent les éléments communs d'interface de MediaWiki.


A FAIRE : Ecrivez-nous.

Utiliser les thèmes

OOUI est livré avec deux thèmes, et chaque widget que vous créez va utiliser le thème défini par l'habillage actuel en utilisant SkinOOUIThemes de extension.json. Les thèmes personnalisés peuvent être également fournis par l'habillage. Pour les détails, voir les Thèmes OOUI.

Retrieved from "https://www.mediawiki.org/w/index.php?title=OOUI/Using_OOUI_in_MediaWiki/fr&oldid=6424263"