Panneau latéral

Cette page propose différents extraits montrant le fonctionnement du panneau latéral de Firefox.

Consultez le tutorial sur la création d'un panneau latéral pas à pas pour Firefox.

Ouverture et fermeture du panneau latéral

Firefox fournit une fonction native toggleSidebar() définie dans browser.js. Cela signifie que la fonction est disponible dans toutes les fenêtres de navigation. Elle sert à ouvrir ou fermer le panneau latéral.

Voici la documentation de cette fonction issue de source :

/**
 * Opens or closes the sidebar identified by commandID.
 *
 * @param commandID a string identifying the sidebar to toggle; see the
 *                  note below. (Optional if a sidebar is already open.)
 * @param forceOpen boolean indicating whether the sidebar should be
 *                  opened regardless of it's current state (optional).
 * @note
 * We expect to find a xul:broadcaster element with the specified ID.
 * The following attributes on that element may be used and/or modified:
 *  - id           (required) the string to match commandID. The convention
 *                 is to use this naming scheme: 'view<sidebar-name>Sidebar'.
 *  - sidebarurl   (required) specifies the URL to load in this sidebar.
 *  - sidebartitle or label (in that order) specify the title to 
 *                 display on the sidebar.
 *  - checked      indicates whether the sidebar is currently displayed.
 *                 Note that toggleSidebar updates this attribute when
 *                 it changes the sidebar's visibility.
 *  - group        this attribute must be set to "sidebar".
 */
function toggleSidebar(commandID, forceOpen) {

Exemples :

// Basculer le panneau latéral des Marque-pages 
// (le fermer s'il est ouvert, l'ouvrir s'il est fermé)
toggleSidebar("viewBookmarksSidebar");

// Ouvrir le panneau latéral de l'historique, qu'il soit déjà ouvert ou fermé
toggleSidebar("viewHistorySidebar", true);

// Fermer le panneau latéral, si nous sommes surs qu'il y en a d'ouvert
toggleSidebar();

Accès au panneau latéral depuis un script browser.xul

Le contenu du panneau latéral est toujours un document séparé du document de navigation principal (le panneau est en réalité également implémenté par un élément XUL browser). Cela signifie que vous ne pouvez pas avoir accès au contenu du panneau latéral depuis un script référencé par un overlay browser.xul.

Pour accéder à vos objets window ou document, vous devez utiliser respectivement les propriétés contentWindow ou contentDocument de document.getElementById("sidebar"). Par exemple, le code suivant appelle une fonction définie dans le contexte du panneau latéral :

var sidebarWindow = document.getElementById("sidebar").contentWindow;
// Vérifie que notre panneau latéral est actuellement ouvert :
if (sidebarWindow.location.href ==
      "chrome://yourextension/content/whatever.xul") {
  // Appel de "yourNotificationFunction" dans le contexte du panneau latéral :
  sidebarWindow.yourNotificationFunction(anyArguments);
} 

Accès à la fenêtre browser.xul depuis un script du panneau latéral

Consultez la section Accès aux éléments du document de la fenêtre principale depuis une fenêtre fille de Travailler avec des fenêtres dans le chrome.

Redimensionner le panneau latéral par programmation

Pour modifier la largeur du panneau latéral, utilisez le code suivant :

function setSidebarWidth(newwidth) {
 var mainWindow = window.QueryInterface(Components.interfaces.nsIInterfaceRequestor)
 .getInterface(Components.interfaces.nsIWebNavigation)
 .QueryInterface(Components.interfaces.nsIDocShellTreeItem)
 .rootTreeItem
 .QueryInterface(Components.interfaces.nsIInterfaceRequestor)
 .getInterface(Components.interfaces.nsIDOMWindow);
 mainWindow.document.getElementById("sidebar-box").width=newwidth;
}

ou

function setSidebarWidth(newwidth) {
  window.top.document.getElementById("sidebar-box").width=newwidth;
}

Vous pouvez également désactiver la possibilité de redimensionner manuellement, via la souris, en masquant l'élément de séparation du panneau latéral. Pour que cet extrait fonctionne, vous devez déclarer mainWindow comme dans le bloc de code précédent et ajouter :

mainWindow.document.getElementById("sidebar-splitter").hidden = true;

Après avoir modifier l'attribut hidden du séparateur, assurez vous de rétablir sa valeur lorsque vous fermez votre panneau latéral, ou lors du remplacement par un autre panneau. Par exemple, utilisez le code suivant dans un gestionnaire d'évènement Unload de votre panneau latéral :

mainWindow.document.getElementById("sidebar-splitter").hidden =
  mainWindow.document.getElementById("sidebar-box").hidden;

Étiquettes et contributeurs liés au document

Étiquettes :
Contributeurs ayant participé à cette page : BenoitL, Chbok
Dernière mise à jour par : Chbok,