OOUI/Créer des interfaces par programme

This page is a translated version of the page OOUI/Creating interfaces programmatically and the translation is 100% complete.

La bibliothèque OOUI[1] contient les blocs de base pour construire une interface utilisateur orientée objet. Elle comprend beaucoup de widgets et d'affichages prêts à l'emploi, ainsi que des éléments de base pouvant être assemblés pour créer quelque chose de votre conception. Des systèmes complexes, tels que les fenêtres et les barres d'outils, sont également fournis et peuvent être étendus et associés pour répondre aux besoins de votre application.

Les interfaces utilisateur sont créés dans OOUI par programmation, ce qui supprime entièrement le balisage HTML. Cette technique permet au balisage d'évoluer, tant que l'API qui génère le balisage reste stable. Le balisage peut changer quand on étend une classe pour qu'elle prenne en compte une nouvelle fonctionnalité, ou quand on corrige un bogue pour augmenter la compatibilité.

Tout ce qui existe dans OOUI et que l'utilisateur peut voir est construit en utilisant des éléments assemblés de manière à former les parties discrètes de l'interface utilisateur, et pouvant fonctionner ensemble. En maximisant la réutilisation des éléments, l'aspect , le comportement et la cohérence de l'API sont plus faciles à maintenir.

Pour commencer

Si vous n'êtes pas encore assez familiarisé avec la manière de créer des interfaces avec OOUI, cette section contient un tutoriel rapide sur la manière de construire un widget en utilisant la bibliothèque.

Créer un widget se fait en deux étapes de base :

  1. le widget est créé et configuré
  2. le widget est ajouté au DOM[2]

Notez que les objets OOUI doivent être ajoutés au DOM avant d'être visibles par l'utilisateur. Les développeurs qui écrivent du code doivent tenir compte du fait qu'un widget peut ou non être attaché au DOM, et ne sera jamais attaché au DOM lors de l'exécution du constructeur. Même après qu'un élément ait été attaché, il peut ultérieurement être détaché. Vous pouvez vérifier qu'un élément est actuellement attaché en utilisant la méthode .isElementAttached().

N'oubliez pas d'inclure les bibliothèques nécessaires jQuery et Special:MyLanguage/OOjs ainsi que les informations de style pertinentes (un des thèmes OOUI, actuellement WikimediaUI par défaut ou Apex comme alternative) et la bibliothèque OOUI elle-même.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Eléments devant être inclus</title>
    <!-- inclure la feuille de style du thème WikimediaUI -->
    <link rel="stylesheet" href="resources/lib/ooui/oojs-ui-core-wikimediaui.css">
  </head>
  <body>

    <!-- jQuery -->
    <script src="resources/lib/jquery/jquery.js"></script>

    <!-- OOjs -->
    <script src="resources/lib/oojs/oojs.jquery.js"></script>

    <!-- OOUI -->
    <script src="resources/lib/ooui/oojs-ui-core.js"></script>
    <script src="resources/lib/ooui/oojs-ui-wikimediaui.js"></script>
  </body>
</html>

Créer et configurer un widget

Chaque widget est créé et configuré avec soit un objet de configuration qui est passé à son constructeur, soit en utilisant les méthodes pour initialiser les configurations (voir l'exemple ci-dessous). Beaucoup des méthodes de la bibliothèque sont chaînables, comme montré dans l'exemple.

Une fois le widget créé, il doit être attaché au DOM pour être visible par l'utilisateur. Utiliser la méthode jQuery .append() pour insérer le nouveau widget dans le DOM en utilisant sa propriété $element

L'exemple suivant montre comment créer et ajouter un simple ButtonWidget qui, lorsqu'il est cliqué, ouvre https://www.mediawiki.org dans une nouvelle fenêtre. button1 est configuré en utilisant un objet config. button2 est configuré en utilisant les méthodes du widget :

 

// Exemple: créer et configurer un nouveau ButtonWidget à l'aide d'un objet config 
// (pour button1) ou les méthodes de ButtonWidget (pour button2), et ajouter les boutons 
// au DOM.

// bouton 1: créer un nouveau bouton de classe OO.ui.ButtonWidget
// les options de configuration (libellé, href, et cible dans cet exemple) 
// sont spécifiées à l'aide d'un objet de configuration.
var button1 = new OO.ui.ButtonWidget( { 
  label: 'Click me!', 
  href: 'https://www.mediawiki.org', 
  target: 'new'
} );
// bouton 2: utiliser les méthodes de ButtonWidget pour configurer le bouton
// notez que vous pouvez chaîner plusieurs méthodes
var button2 = new OO.ui.ButtonWidget()
  .setLabel( 'Click me!' )
  .setHref( 'https://www.mediawiki.org' )
  .setTarget( 'new' );
// ajouter les boutons au DOM en utilisant la propriété $element et la méthode .append() de jQuery
$( 'body' ).append( button1.$element, button2.$element );

Notez que certaines méthodes de type get comme getItemFromData() ou getElementDocument(), ne doivent pas être chaînées. Ces méthodes peuvent renvoyer ‘null’, et le fait d'appeler une autre méthode avec ‘null’ provoque une erreur.

Connecter un gestionnaire d'événements à un widget

Les Widgets émettent des événements quand vous agissez dessus ou lorsqu'ils sont modifiés d'une manière particulière. Ces événements peuvent être récupérés en leur connectant un gestionnaire d'événements. L'exemple ci-dessous utilise un gestionnaire d'événements pour afficher une alerte lorsque le bouton est cliqué. Quand le bouton est cliqué, son libellé est remplacé par « Do not click me! » en utilisant la méthode setLabel() du bouton.

// Exemple: connecter un gestionnaire d'événements à un bouton.

// créer un nouveau bouton
var button3 = new OO.ui.ButtonWidget( { 
  label: 'I handle events' 
} );
// configurer les gestionnaires d'événements
// Utiliser la méthode on() de ButtonWidget pour préciser l'événement (un clic par exemple) 
// et un gestionnaire d'événement
button3.on( 'click', function () {
  alert( 'I was clicked!' );
  button3.setLabel( 'Do not click me!' );
} );
// ajouter le bouton au DOM.
$( 'body' ).append( button3.$element );

La gestion des événements est fournie par la classe EventEmitter, mixée dans tous les widgets. Pour d'autres informations à propos de EventEmitter, veuillez consulter l'introduction à OOjs.

Comprendre les mixins

Le concept des mixins[3] est fondamental pour la bibliothèque, et beaucoup de ses éléments peuvent être adaptés en utilisant les fonctionnalités du mixin. Par exemple on peut facilement ajouter une icône à un widget de bouton en tirant avantage du fait que la classe IconElement est mixée dans la classe ButtonWidget.

 

// Créer un nouveau bouton et ajouter une icône en utilisant l'option de configuration fournie 
// par la classe IconElement
var button4 = new OO.ui.ButtonWidget( { 
  label: 'Button with icon', 
  icon: 'alert'
} );

// ajouter le bouton au DOM.
$( 'body' ).append( button4.$element );

Les classes de mixin peuvent être utilisées pour créer ou pour ajouter de nouveaux éléments à un widget (comme l'icône de l'exemple ci-dessus), ou pour ajouter de nouveaux comportements (comme de nouvelles méthodes pour gérer les drapeaux de style ou les titres).

Il existe trois sortes d'éléments mixins, chacun d'eux étant identifié par une convention de nommage :

  • Content — les mixins de contenu génèrent les éléments par défaut (par exemple les groupes, icônes, indicateurs et étiquettes). Les noms des éléments de contenu n'ont pas de suffixe (par exemple GroupElement, IconElement, etc.)
  • Attribute — les mixins d'attributs opèrent sur $element par défaut (par exemple les drapeaux et les titres). Les noms des mixins d'attributs ont un suffixe « ed » (comme FlaggedElement, TitledElement, etc.)
  • Behaviour — les mixins de comportement opèrent sur $element par défaut (comme clippable). Les mixins de comportement sont identifiés par le suffixe « able » (comme ClippableElement, etc.)

Notez que si une classe mixin peut créer et initialiser un objet, elle ne l'ajoute pas au DOM. Ceci doit être fait manuellement si vous souhaitez manipuler l'objet directement.

Il n'est pas rare de voir des widgets composés de multiple mixins : par exemple la classe ButtonWidget utilise utilise les mixins ButtonElement et IconElement (et quelques autres). Vous pouvez voir facilement les classes mixées disponibles en regardant la documentation de niveau code pour chacune des classes. Les classes mixin seront toujours affichées dans le coin supérieur droit de l'écran de documentation de chaque classe. En plus, chaque option de configuration note le nom de la classe qui la définit.

Références

  1. OOUI (Object-Oriented User Interface)
  2. DOM (Document Object Model)
  3. mixins (fr) (en)