OOUI/Barres d'outils
Barres d'outils
Les barres d'outils sont des composants complexes d'interface qui permettent aux utilisateurs d'accéder facilement à une variété d'outils (comme les commandes de mise en forme) et d'actions. Ces outils sont des commandes supplémentaires faisant partie de la barre d'outils mais ils ne sont pas configurés comme telles.
Les développeurs créent et personnalisent les outils individuels puis les enregistrent avec une ToolFactory, qui crée les outils à la demande. Chaque outil a un nom symbolique (utilisé lors de son enregistrement), un titre (par exemple, ‘Insérer une image’), et une icône.
Les outils individuels sont organisés en groupes d'outils et affichés dans les menus, les listes ou une unique barre d'outils. Vous pouvez personnaliser l'organisation et l'ordre des groupes quand vous configurez la barre d'outils. Les outils peuvent apparaître dans n'importe quel ordre mais chaque outil ne peut figurer qu'une fois dans la barre d'outils.
Vous trouverez ci-après un exemple basique de barre d'outils. Nous détaillerons plus précisément chaque composant de cet exemple ultérieurement dans cette documentation. Pour avoir un aperçu réel de cette démonstration, voir la documentation du code générée.
Les outils
Les outils sont créés par l'extension de la classe abstraite Tools ou l'une de ses sous-classes PopupTool ou ToolGroupTool. Chaque outil doit être configuré avec les propriétés de nom statique, de titre et d'icône :
name— Le nom symbolique est utilisé en interne pour enregistrer l'outil via ToolFactory. Les outils doivent être enregistrés via une usine d'outils (tool factory) avant de pouvoir être utilisés dans une barre d'outils.title— Le texte du titre est utilisé de différentes manières en fonction du type de groupe dans lequel l'outil est placé : le groupe des barres d'outils BarToolGroup, le groupe des barres de menus MenuToolGroup, ou le groupe des listes d'outils ListToolGroup. Pour les groupes d'outils de type 'barre' où il n'y a qu'une icône pour identifier l'outil, le texte du titre est utilisé comme une bulle d'aide affichée quand l'utilisateur survole l’outil avec la souris. Pour les groupes d'outils de type 'liste', le texte du titre est utilisé pour identifier les outils dans les menus déroulants de l'interface utilisateur. Si un raccouci a été défini pour l'outil, il sera automatiquement affiché. Pour les groupes d'outils de type 'barre', le raccourci clavier est affiché dans une bulle; pour les outils des groupes de type 'menu' et 'liste', le raccouci apparait à droite de chaque élément du menu déroulant.icon— L'icône est aussi utilisée de différentes manières en fonction du type de groupe dans lequel se trouve l'outil. Pour les groupes d'outils de type 'barre', l'icône est affichée dans la barre d'outils afin d'identifier ces derniers. Pour les groupes d'outils de type 'liste', l'icône est affichée à côté du texte du titre dans le menu déroulant. Pour les groupes d'outils de type 'menu', l'icône est ignorée.
En plus des propriétés statiques, les outils doivent aussi implémenter les méthodes suivantes :
- onSelect() — utilisé pour spécifier l'action réalisée par l'outil quand il est sélectionné
- onUpdateState() — utilisé pour synchroniser l'état de l'outil avec l'état de son contexte le plus grand. Par exemple cette méthode peut être utilisée pour sélectionner l'outil 'bold’ de la barre d'outil quand le curseur du texte est placé dans une zone de texte en gras.
// exemple: créer un outil standard.
// créer une usine d'outils (fait une fois pour chaque barre d'outils). Tous les outils doivent être enregistrés via une usine d'outils qui crée les objets correspondants à la demande.
var toolFactory = new OO.ui.ToolFactory();
// définir les propriés statiques et l'action réalisée
function PictureTool() {
PictureTool.super.apply( this, arguments );
};
OO.inheritClass( PictureTool, OO.ui.Tool );
// chaque outil doit avoir son nom 'name' (utilisé comme identifiant interne, voir plus loin) et au moins une icône 'icon' et un titre 'title' (l'icône et le texte affiché).
PictureTool.static.name = 'picture';
PictureTool.static.icon = 'picture';
PictureTool.static.title = 'Insert picture';
// définir l'action réalisée lorsque l'outil est sélectionné (cliqué).
PictureTool.prototype.onSelect = function () {
// … mettre ici le code de l'outil …
this.setActive( false );
};
// définir onUpdateState(). Nous n'utiliserons pas cette fonction ici.
PictureTool.prototype.onUpdateState = function () {};
// enregistrer le nouvel outil via l'usine d'outils
toolFactory.register( PictureTool );
Les outils peuvent aussi être configurés avec la propriété statique 'group' qui pourra être utilisée ultérieurement quand l'outil sera ajouté dans une barre, un menu ou à une liste de groupe d'outils (voir ToolGroups pour un exemple de réalisation) :
// Définissez une propriété statique 'group' si vous souhaitez inclure des outils basés sur le nom défini ici.
function PictureTool() {
PictureTool.super.apply( this, arguments );
};
OO.inheritClass( PictureTool, OO.ui.Tool );
PictureTool.static.name = 'picture';
PictureTool.static.icon = 'picture';
PictureTool.static.title = 'Insert picture';
PictureTool.static.group = 'myGroup';
La liste complète des méthodes prises en charge ainsi que les options de configuration, sont décrites dans la documentation du code pour la classe Tool.
PopupTool
Les outils de fenêtrage ouvrent une fenêtre popup lorsqu'ils sont sélectionnés dans la barre d'outils.
A la différence des outils standards les outils de popup ne nécessitent pas que les développeurs spécifient les méthodes onSelect() ou onUpdateState(), car ces méthodes sont déjà implémentées.
// Exemple d'outil popup. Quand il est sélectionné, la fenêtre instantanée de l'outil affiche
// une fenêtre popup.
function HelpTool( toolGroup, config ) {
OO.ui.PopupTool.call( this, toolGroup, $.extend( { popup: {
padded: true,
label: 'Help',
head: true
} }, config ) );
this.popup.$body.append( '<p>I am helpful!</p>' );
};
OO.inheritClass( HelpTool, OO.ui.PopupTool );
HelpTool.static.name = 'help';
HelpTool.static.icon = 'help';
HelpTool.static.title = 'Help';
toolFactory.register( HelpTool );
La liste complète des méthodes prises en charge ainsi que les options de configuration, sont décrites dans la documentation du code pour la classe PopupTool.
ToolGroupTool
Un ToolGroupTool est une espèce particulière d'outil pouvant contenir d'autre outils ou d'autres groupes d'outils à l'intérieur. Le ToolGroupTool a été conçu spécialement pour être utilisé avec des outils regroupés sous une même barre afin de donner accès à des outils supplémentaires à partir d'un élément de la barre.
// Exemple : ToolGroupTool avec deux outils imbriqués, 'setting1' et 'setting2', définis ailleurs.
function SettingsTool() {
SettingsTool.super.apply( this, arguments );
};
OO.inheritClass( SettingsTool, OO.ui.ToolGroupTool );
SettingsTool.static.name = 'settings';
SettingsTool.static.title = 'Change settings';
SettingsTool.static.groupConfig = {
icon: 'settings',
label: 'ToolGroupTool',
include: [ 'setting1', 'setting2' ]
};
toolFactory.register( SettingsTool );
La liste complète des méthodes prises en charge ainsi que les options de configuration, sont décrites dans la documentation du code pour la classe ToolGroupTool.
Les groupes d'outils
Les outils sont regroupés dans des Toolgroups, créés par une ToolGroupFactory puis ajoutés à la barre d'outils quand celle-ci est définie. Des outils peuvent être ajoutés individuellement à n'importe quel type de groupement d'outils (barre, liste ou menu). Le type du toolgroup détermine la disposition des outils ajoutés dans la barre d'outils :
bar— Les outils sont affichés par leur icône sur une seule ligne.list— Les outils sont affichés avec un libellé et une icône dans un menu déroulant. Le titre de l'outil est utilisé comme texte du libellé. La liste peut être configurée pour être repliée ou développée, avec le paramètre allowCollapse.menu— Dans un menu déroulant les outils sont présentés en fonction de leur libellé. Le titre de l'outil est utilisé comme texte du libellé. Les groupes d'outils de type 'menu' sont généralement utilisés pour des ensembles d'outils mutuellement exclusifs, tels que des groupes de commandes pour la mise en forme du texte (paragraphe, titre, etc).
Les outils peuvent être ajoutés à un groupe d'outils de différentes manières : par leur nom symbolique, par le nom du groupe, ou en utilisant l'astérisque '*' pour tout couvrir :
Ajouter les outils par name :
// ajouter les outils par leur nom symbolique.
{
type: 'list',
include: [ 'picture', 'help' ]
}
// ou utiliser un objet :
{
type: 'list',
include: [ { name: 'picture' }, { name: 'help' } ]
}
Ajouter les outils par group.
Le nom d'un groupe d'outils est spécifié en utilisant la propriété statique 'group' (voir Tools pour un exemple).
// Ajouter les outils par nom de groupe.
{
type: 'list',
include: [ { group: 'myGroup' } ]
}
Ajouter les outils avec le catch-all :
// ajouter les outils avec le joker astérisque pour 'tout ramasser'
// L'astérisque indique que tous les outils qui ne sont pas encore dans un toolgroup sont à inclure.
{
type: 'list',
include: { '*' }
}
Les développeurs peuvent ensuite gérer l'arrangement des outils en utilisant les options de configuration promote et demote du groupe d'outils, pour réorganiser les outils, respectivement au début de la liste (ou à l'avant de la barre d'outils), ou à la fin.
Ces paramètres sont particulièrement utiles pour gérer leur priorité lorsque les outils ont été ajoutés en masse à la barre d'outils (par exemple avec l'astérique attrappe-tout, ou quand un groupe d'outils est ajouté à un toolgroup).
BarToolGroup
Les outils d'un BarToolGroup sont affichés par icône et sur une seule ligne.
Le titre de l'outil est affiché quand l'utilisateur survole l'outil avec la souris.
// Exemple de BarToolGroup
{
// Les outils sont affichés par icône sur une seule ligne
type: 'bar',
include: [ 'picture', 'help', 'settings', 'stuff']
}
La liste complète des méthodes prises en charge ainsi que les options de configuration, sont décrites dans la documentation du code pour la classe BarToolGroup.
ListToolGroup
Les outils d'un ListToolGroup sont affichés par leur icône et leur libellé dans un menu déroulant.
Le titre de l'outil est utilisé comme texte du libellé.
Les groupes de listes peuvent être configurés pour être développés ou repliés.
Les listes repliées auront une option 'Plus...' que les utilisateurs pourront sélectionner pour voir la liste complète des outils.
Si un toolgroup replié est développé, une option ‘Moins’ permet aux utilisateurs de replier la liste à nouveau.
// Exemple de ListToolGroup. Les outils sont affichés par icône et par libellé dans une liste déroulante.
// Le menu déroulant peut aussi être configuré avec un libellé, dans cet exemple, 'ListToolGroup'
{
type: 'list',
indicator: 'down',
label: 'ListToolGroup',
include: [ 'picture', 'help', 'settings', 'stuff' ]
}
En plus de label, ListToolGroups peut aussi être configuré avec un header et title :
// Exemple : ListToolGroup avec un libellé, un entête et un titre.
{
type: 'list',
indicator: 'down',
header: 'This is the header',
title: 'This is the title',
label: 'ListToolGroup (this is the label)',
include: [ 'picture', 'help', 'settings', 'stuff' ]
}
Utiliser le paramètre allowCollapse pour indiquer que l'outil est repliable ('help' et 'stuff', dans l'exemple ci-après).
Par défaut la liste s'ouvre dans l'état replié et l'utilisateur doit cliquer sur l'option 'Plus...' pour voir les outils repliés :
// Exemple d'un ListToolGroup avec des outils repliés. Par défaut, le menu s'ouvre dans l'état replié.
{
type: 'list',
indicator: 'down',
label: 'ListToolGroup - Collapsed',
include: [ 'picture', 'help', 'settings', 'stuff' ],
allowCollapse: [ 'help', 'stuff' ]
}
Pour afficher une liste repliable dans son état développé quand la liste est ouverte, initialiser le paramètre expanded à true :
// Pour développer une liste repliable, initialisez le paramètre 'expanded' à 'true'.
{
type: 'list',
indicator: 'down',
label: 'ListToolGroup - Expanded',
include: [ 'picture', 'help', 'settings', 'stuff' ],
allowCollapse: [ 'help', 'stuff' ],
expanded: true
}
Vous pouvez également indiquer le nom des outils qui ne doivent jamais être repliés.
Ceci est réalisé avec le paramètre forceExpand.
Dans l'exemple suivant, seul l'outil ‘help’ est mentionné comme étant développé; tous les autres outils sont repliés par défaut.
// Spécifier les outils qui doivent être développés; tous les autres seront repliés par défaut.
{
type: 'list',
indicator: 'down',
label: 'ListToolGroup - forceExpand',
include: [ 'picture', 'help', 'settings', 'stuff' ],
forceExpand: [ 'help' ]
}
La liste complète des méthodes prises en charge ainsi que les options de configuration, sont décrites dans la documentation du code pour la classe ListToolGroup.
MenuToolGroup
Les outils dans un MenuToolGroup sont affichés en fonction de leur libellé, dans un menu déroulant.
Le titre de l'outil est utilisé comme le texte du libellé, et le libellé du menu est mis à jour pour refléter quel outil ou quels outils sont actuellement sélectionnés.
Notez que si un MenuToolGroup est utilisé, alors chaque outil doit définir une méthode onUpdateState().
// Exemple : MenuToolGroup
function SettingsTool() {
SettingsTool.super.apply( this, arguments );
this.reallyActive = false;
}
OO.inheritClass( SettingsTool, OO.ui.Tool );
SettingsTool.static.name = 'settings';
SettingsTool.static.icon = 'settings';
SettingsTool.static.title = 'Change settings';
SettingsTool.prototype.onSelect = function () {
// Modifiez l'état actif à chaque clic
this.reallyActive = !this.reallyActive;
this.setActive( this.reallyActive );
// mettre à jour le libellé du menu
this.toolbar.emit( 'updateState' );
};
SettingsTool.prototype.onUpdateState = function () {};
toolFactory.register( SettingsTool );
// Un autre outil.
function StuffTool() {
StuffTool.super.apply( this, arguments );
this.reallyActive = false;
}
OO.inheritClass( StuffTool, OO.ui.Tool );
StuffTool.static.name = 'stuff';
StuffTool.static.icon = 'ellipsis';
StuffTool.static.title = 'Change the world';
StuffTool.prototype.onSelect = function () {
// Modifiez l'état actif à chaque clic
this.reallyActive = !this.reallyActive;
this.setActive( this.reallyActive );
// mettre à jour le libellé du menu
this.toolbar.emit( 'updateState' );
};
StuffTool.prototype.onUpdateState = function () {};
toolFactory.register( StuffTool );
// Ajouter l'objet MenuToolGroup à la barre d'outils.
toolbar.setup( [
{
type: 'menu',
indicator: 'down',
include: [ 'settings', 'stuff' ]
}
] );
Configurer la barre d'outils
En plus de pouvoir contenir des groupes d'outils, la barre d'outils peut être configurée avec des actions, du CSS, des touches de raccourci, et (ou) une ombre facultative.
Notez que les 'actions' dans le contexte de la barre d'outils sont différentes de ActionWidgets. Pour les barres d'outils, les 'actions' font référence à un conteneur vide aligné à droite et pouvent contenir ce que vous souhaitez.
Ajouter des groupes d'outils
Les objets Toolgroups sont ajoutés à la barre d'outil à l'aide de la méthode setup :
// ajouter les groupes d'outils à la barre d'outils.
toolbar.setup( [
{
type: 'bar',
include: [ 'picture', 'help' ]
},
{
type: 'list',
indicator: 'down',
label: 'More',
include: [ 'settings', 'stuff' ]
}
] );
Ajouter des actions
Les barres d'outils possèdent des zones d'actions optionnelles, qui contiennent des commandes disponibles pour les utilisateurs mais qui ne sont pas configurées en tant qu'outils. Dans l'exemple suivant la barre d'outils a été configurée pour utiliser des actions, ici deux boutons supplémentaires 'Action' et 'Disabled'. Pour simplifier, seul le code spécifique à l'action est mis dans l'exemple (le reste est la même chose que la barre d'outils de base).
// Exemple : une barre d'outils avec des actions supplémentaires.
// Créer la barre et initialiser le paramètre 'action' à 'true'.
var toolFactory = new OO.ui.ToolFactory();
var toolGroupFactory = new OO.ui.ToolGroupFactory();
var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory, { actions: true } );
// créer et ajouter les boutons d'action
actionButton = new OO.ui.ButtonWidget( { label: 'Action' } );
actionButtonDisabled = new OO.ui.ButtonWidget( { label: 'Disabled', disabled: true } );
toolbar.$actions.append( actionButton.$element, actionButtonDisabled.$element );
Utiliser CSS pour formater l'étiquette des outils
Le libellé des outils peut être mis en forme à l'aide des classes CSS prédéfinies dont le nom figure après chaque outil : oo-ui-tool-name-<nom symbolique de l'outil> (par exemple oo-ui-tool-name-picture). L'exemple suivant utilise les classes CSS pour personnaliser l'apparence des libellés des outils 'picture' et 'help'.
<!-- Exemple : styliser le libellé des outils avec CSS -->
<style>
.oo-ui-listToolGroup .oo-ui-tool-name-picture .oo-ui-tool-title {
font-size: 200%;
font-weight: normal;
}
.oo-ui-listToolGroup .oo-ui-tool-name-help .oo-ui-tool-title {
font-size: 150%;
font-weight: normal;
}
</style>
<script>
// Dans cet exemple, les outils 'picture' et 'help' sont stylisés.
{
type: 'list',
indicator: 'down',
label: 'Using CSS',
include: [ 'picture', 'help', 'settings', 'stuff' ]
}
</script>
Utiliser les touches de raccourci
La bibliothèque OOUI ne contient pas de système d'accélération mais la classe Toolbar possède une accroche pour en avoir un.
Pour utiliser un système d'accélération, faites une sous-classe de la barre d'outils et redéfinissez la méthode getToolAccelerator() qui renvoie un libellé décrivant les touches de raccouci de l'outil (nom symbolique) passé à la méthode.
Le libellé des raccourcis (par exemple Ctrl + M) est affiché de différentes manières, en fonction du type de groupe d'outils utilisé :
- Pour les groupes de type 'barre', le texte du raccouci apparaît dans la bulle qui s'affiche lorsque l'utilisateur survole l'outil avec la souris.
- Pour les groupes de type 'menu' et 'liste', le texte du raccouci est aligné à droite et grisé, ce qui respecte encore le WCAG niveau AA [1].
Construire la barre d'outils
La barre d'outils doit être ajoutée au document avant qu'il ne soit construit. Une fois avoir été ajoutée, la barre d'outils peut être initialisée.
// ajouter la barre d'outils
$( document.body ).append( toolbar.$element );
// C'est ici que la barre d'outils est construite actuellement.
// Ceci doit être fait après l'avoir insérée dans le document.
toolbar.initialize();
// émettre un événement 'updateState' après avoir initialisé la barre d'outils
toolbar.emit( 'updateState' );
La liste complète des méthodes prises en charge ainsi que les options de configuration, sont décrites dans la documentation du code pour la classe Toolbars.
Références
- ↑ WCAG (Web Content Accessibility Guidelines)
the Design System Team assure la maintenance de OOUI.
Obtenir de l'aide :
|
