Fichiers XUL et overlays XUL
Les overlays sont des fichiers XUL décrivant du contenu additionnel dans l'interface utilisateur. Bien que les overlays servent habituellement à définir des éléments de l'interface utilisateur ajoutés pour une mise à jour ou une amélioration de certaines fonctionnalités, ils peuvent être utilisés de différentes manières. Ils fournissent un mécanisme général pour :
- ajouter des composants supplémentaires dans l'interface utilisateur, comme dans l'exemple ci-dessous
- redéfinir des morceaux d'un fichier XUL sans avoir à reconstituer l'ensemble de l'interface utilisateur
- réemployer des morceaux particuliers d'une interface utilisateur
Les fichiers XUL et overlays fonctionnent ensemble pour décrire un seul document final. Bien qu'il n'existe aucune restriction formelle sur ce que doivent contenir les fichiers XUL de "base" et les fichiers overlays, les overlays XUL définissent généralement des items qui ne sont pas présents dans les versions natives de l'interface utilisateur, tels que des composants supplémentaires. Lorsque des plugins, des extensions du navigateur ou d'autres applications fournissent de nouveaux éléments d'interface au navigateur, ces éléments doivent être définis dans des fichiers d'overlays. L'installation d'un plugin de média, par exemple, peut ajouter de nouveaux icones et items de menu à l'interface :
Dans le fichier navigatorOverlay.xul ou un fichier séparé navigatorSSPOverlay.xul (où navigator.xul correspond à l'interface utilisateur de base pour le paquetage de navigation), ces nouveaux éléments plugins seront définis dans une collection d'éléments ou de partie d'arbres :
<menuitem name="Super Stream Player"/>
<menupopup name="SS Favorites">
<menuitem name="Wave" src="mavericks.ssp"/>
<menuitem name="Soccer" src="brazil_soccer.ssp"/>
</menupopup>
<titledbutton id="SSP" crop="right" flex="1"
value="&SSButton.label;" onclick="FireSSP()"/>
Les overlays et les attributs ID
Le moteur d'affichage utilise les attributs ID pour déterminer la position d'insertion des éléments d'un fichier overlay. Pour les overlays XUL, les mêmes ID que ceux des fichiers XUL de base doivent être utilisés, sinon les nouveaux éléments n'apparaîtront pas du tout. Dans le fichier de base, les nœuds parents des éléments overlay doivent donc contenir des ID. Par exemple, l'élément <menu> de l'arborescence XUL suivante doit être le parent de l'élément du menu de Super Stream Player ; il lui est donc attribué l'ID "file_menu":
<menu id="file_menu"> <menuitem name="Nouveau"/> <menuitem name="Ouvrir"/> <menuitem name="Sauvegarder"/> <menuitem name="Fermer"/> </menu>
Dans le fichier overlay, vous pouvez faire en sorte que le nouvel item soit ajouté au menu en lui spéficiant qu'il est l'enfant d'un élément de même ID dans le fichier overlay. Le moteur d'affichage récupère directement les éléments de l'overlay en les fusionnant aux nœuds correspondants de même ID du fichier de base. Voici l'exemple complet de l'overlay XUL ajoutant un item de menu Super Stream Player :
<?xml version="1.0"?>
<overlay id="singleItemEx"
xmlns:html="https://www.w3.org/1999/xhtml"
xmlns="http:www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
<menu id="file_menu">
<menuitem name="Super Stream Player"/>
</menu>
</overlay>
Notez que la structure des éléments dans l'élément menu du fichier de base et overlay du fichier overlay est similaire. Les items de fusion peuvent également imbriqués d'autres sous-structures : des nouveux menus surgissants peuvent contenir d'autres sous menus, des barres d'outils supplémentaires peuvent remplacer des barres d'outils existantes ou apparaître à leur côté comme la barre d'outils personnelle apparaissant sous la barre de navigation, etc. Tant que les ID des éléments apparaissant dans la balise overlay du fichier overlay et les ID des éléments du fichier de base seront les mêmes, la fusion s'effectuera pour toutes les sous-structures de ces éléments.
Comme vous ne pouvez pas fusionner un élément sans ID, vous devrez utiliser des méthodes du DOM pour l'ajouter à l'interface au travers d'un gestionnaire d'événement load.
Chargement des overlays
Les overlays peuvent être chargés explicitement ou dynamiquement. Un chargement d'overlay de manière explicite implique qu'il sera disponible à chaque fois que le fichier de base est chargé. Or, puisque le but des overlays est de compléter l'interface utilisateur ou de fournir des composants au paquetage de base, le chargement explicite peut devenir problématique lorsque l'overlay définit des éléments optionnels de l'interface utilisateur.
Chargement explicite des overlays
Une directive spéciale est utilisée pour le chargement des overlay de manière explicite dans le document principal. L'insertion de l'instruction suivante avant la déclaration DOCTYPE en début de fichier dira au moteur de rendu de charger le fichier indiqué :
<?xul-overlay href="chrome://component/content/componentOverlay.xul"?>
où component est le nom du paquetage à surcharger (par exemple chrome://navigator/content/navigatorOverlay.xul).
Le moteur de rendu charge tous les fichiers overlay et met en forme ensuite le document résultant, donc les problèmes associés avec l'insertion incrémentale dans des menus, des boîtes, des tableaux et des formulaires sont évités. Il est possible de charger autant d'overlays que souhaité depuis le document principal, et un overlay peut également charger d'autres overlays. Comme un overlay surcharge le document principal, il n'y a pas d'ambiguité sur l'application des feuilles de style ou des scripts. Les feuilles de style et les scripts chargés par l'overlay sont simplement appliqués à la totalité du document principal.
Chargement dynamique des overlays
Le registre chrome permet le chargement dynamique d'overlays XUL -- ou seulement si nécessaire. Le registre chrome, qui est une source de données RDF spéciales où les informations spécifiques à l'utilisateur sont mémorisées, contient des informations sur les composants ou les paquetages supplémentaires qui ont été installés avec le navigateur. Lorsqu'un composant tel que le "Super Stream Player" de l'exemple ci-dessus est enregistré là, les overlays associés à ce composant sont automatiquement chargés. Lorsque le composant n'est pas présent, seuls les fichiers de base sont chargés.
Chargement d'overlays à l'exécution
Firefox 1.5 et d'autres applications basées sur Gecko 1.8 supportent également le chargement d'overlays à la volée via la fonction DOM:document.loadOverlay.
Overlays et thèmes graphiques
Contrairement aux fichiers de base, les overlays ne doivent jamais charger le thème graphique principal pour un paquetage. Le fichier navigatorOverlay.xul, par exemple, ne doit pas et ne devrait jamais charger le fichier navigator.css qui définit le thème graphique principal du paquetage du navigateur. Étant donné que le principe d'un overlay est de définir de nouveaux éléments d'interface utilisateur pour un paquetage dans le contexte du thème graphique de ce paquetage, les overlays doivent ajouter une structure mais pas de nouveaux styles. Tous les thèmes graphiques chargés par un overlay remplacent de manière destructrice le thème graphique principal du fichier de base, et peuvent modifier l'apparence de base de façon désastreuse.
bookmarks.css et il est situé dans le sous répertoire skin/default.Overlay d'attributs
En plus d'ajouter de nouveaux éléments et arborescences, vous pouvez également remplacer des attributs sur des éléments existants. En XUL, les attributs contrôlent des fonctionnalités importantes lors du rendu à l'écran telles que les sources des images. L'exemple suivant écrase la source de l'image du fichier de base par une autre. Dans le fichier de base, l'élément HTML image pointe vers une icone GIF Netscape :
<html:img id="foo" src="netscapeImage.gif"/>
Dans l'overlay, un élément de même attribut ID définit une image différente, et cette image va remplacer l'image d'origine Netscape après le processus de fusion :
<html:img id="foo" src="mozillaImage.gif"/>
Lorsque le fichier de base référence un fichier overlay contenant l'élément HTML image ci-dessus, le nouvel attribut src sera superposé à l'original, et l'icone Mozilla remplacera l'icone Netscape.
Positionnement des overlays
Les overlays XUL supportent aussi le positionnement des nœuds. Vous pouvez spécifier un attribut de positionnement position sur un nœud dans l'overlay pour fournir une indication lors de l'insertion dans le document principal. Sur l'exemple suivant, le dernier item de menu - "Exemple quatre" - sera placé juste après l'item de menu "Nouveau" plutôt que d'être ajouté à la fin du menu comme pour les autres items enfants.
<overlay id="main-overlay" xmlns:html="https://www.w3.org/1999/xhtml"
xmlns:rdf="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns="https://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
<menu id="file_menu">
<menuitem name="Exemple un"/>
<menuitem name="Exemple deux"/>
<menuitem name="Exemple trois"/>
<menuitem name="Exemple quatre" position="1"/>
</menu>
</overlay>
Le nœud avec l'attribut position se positionne de lui même en haut du menu. La position peut également être indiquée au nœuds des fichiers overlays qui seront ordonnés dans un groupe d'items similaires dans le fichier de base. Par exemple, si seul le dernier menuitem ci-dessus était présent dans l'overlay et que les autres items étaient définis dans le fichier de base, le menuitem ajouté en overlay apparaîtrait toujours en haut du menu parent.
Réutilisation d'interfaces avec les overlays
Un des plus grands avantages de l'utilisation des overlays est de pouvoir réutiliser des groupes d'éléments qui apparaissent fréquemment dans l'interface utilisateur. Le mécanisme des overlays permet de fusionner des éléments dans une arborescence existante, mais il vous permet également de stocker des éléments d'interfaces courants et de les faire fusionner dans tous les fichiers de base les utilisant. En mettant un attribut ID sur un nœud vide dans le fichier de base, vous pouvez faire référence à une arborescence définie dans un fichier overlay et la fusionner où vous en avez besoin.
Par exemple, les boutons qui apparaissent en bas des boîtes de dialogue courantes, les boutons OK et Annuler, peuvent servir dans des dizaines d'endroits de l'interface utilisateur. Plutôt que de redéfinir l'ensemble des boutons à chaque fois que c'est nécessaire dans une boîte de dialogue, les fichiers de base peuvent se servir d'overlays dans lesquels ces boutons sont définis, dialogOverlay.xul. (En réalité, l'implémentation est un peu plus compliquée que cela : les fichiers de base utilisent dialogOverlay.xul depuis le répertoire component global, qui à son tour utilise les fichiers overlays de plateforme spécifiques tels que platformDialogOverlay.xul. Le mécanisme reste néanmoins le même.)
Chaque boîte de dialogue voulant ajouter ces boutons en overlay doit simplement déclarer en début de fichier :
<?xul-overlay href="chrome://global/content/dialogOverlay.xul"?>
puis inclure une boîte vide avec un ID okCancelButtons dans l'interface. L'extrait suivant affiche une boîte de dialogue avec des éléments d'interface personnalisés en haut et la référence à l'overlay pour les boutons Ok et Annuler en bas :
<box align="horizontal" id="bx1" flex="100%" style="margin-bottom: 1em; width: 100%;"> <html:input type="checkbox" id="dialog.newWindow"/> <html:label for="dialog.newWindow">&openWin.label;</html:label> <spring flex="100%"/> </box> <box id="okCancelButtons"/>
Pour plus de détails, consultez les définitions des boutons Ok et Annuler référencés ici dans le fichier global de composants platformDialogOverlay.xul. Les barres d'outils, les sous menus, les boîtes et toutes les autres arborescences apparaissant à de multiples endroits peuvent être définis dans des fichiers overlays de cette manière pour être réutilisés là où ils sont nécessaires.