OOUI/Utiliser OOUI dans MediaWiki
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 $2 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 :
- Liste mise à jour automatiquement : https://doc.wikimedia.org/oojs-ui/master/php/annotated.html
- Démonstration en direct avec des exemples (page de démonstration dans la branche master)
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 :
- https://phabricator.wikimedia.org/diffusion/MW/browse/master/includes/specials/SpecialMIMESearch.php (Special:MIMESearch)
- https://phabricator.wikimedia.org/diffusion/MW/browse/master/includes/specials/SpecialResetTokens.php (Special:ResetTokens)
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 :
oojs-ui-core— bibliothèque JavaScript du noyau OOUI. Contient les widgets de base et les affichages qui sont également disponibles en PHP (voir la liste exacte ci-dessus) avec la possibilité de les infuser.oojs-ui-widgets— widgets et affichages supplémentaires.oojs-ui-toolbars— barre d'outils et outils.oojs-ui-windows— fenêtres et dialogues.oojs-ui.styles.icons-*— styles spécifiques d'icônes en fonction des icônes que vous souhaiteriez utiliser, par exempleoojs-ui.styles.icons-interactionspour l'icône de vérification. Les noms de groupe peuvent être vus sur la page de démonstration ou dans le code.
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.
- Manual:TitleInputWidget
- Manual:UserInputWidget
- Manual:SearchInputWidget
- Manual:NamespaceInputWidget
- Manual:DateInputWidget (example call)
- Manual:DateTimeInputWidget
- Manual:CategoryMultiselectSelector
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.
the Design System Team assure la maintenance de OOUI.
Obtenir de l'aide :
|
