Accès aux marque-pages

Cette page vient d'être traduite, mais elle a besoin d'un relecteur différent du traducteur. Pensez également à toujours vérifier le contenu avec sa toute dernière version en anglais.

Ce document permet de démarrer rapidement pour ceux qui désirent retrouver rapidement une portion de l'arbre des marque-pages. Ceux-ci sont accessibles via le Système de requêtes de Places, qui contient des informations plus générales. Pour en savoir plus sur l'API du service de marque-pages, consultez Service de marque-pages.

Obtention des objets de requête et d'options

Toutes les interrogations se font au travers du service d'historique. Tout d'abord, il faut obtenir une requête vide et des objets d'options depuis celui-ci :

var historyService = Components.classes["@mozilla.org/browser/nav-history-service;1"]
                               .getService(Components.interfaces.nsINavHistoryService);
var options = historyService.getNewQueryOptions();
var query = historyService.getNewQuery();

Recherche du dossier désiré

Les ID de dossiers connus sont obtenus depuis le service de marque-pages. Les attributs définis dans /toolkit/components/places/public/nsINavBookmarksService.idl sont : placesRoot, bookmarksRoot, tagRoot et toolbarFolder. Il est également possible d'obtenir des ID de dossiers depuis une requête antérieure.

Cet exemple récupèrera le contenu de la barre personnelle :

var bookmarksService = Components.classes["@mozilla.org/browser/nav-bookmarks-service;1"]
                                 .getService(Components.interfaces.nsINavBookmarksService);
var toolbarFolder = bookmarksService.toolbarFolder;

Remplissage des objets de requête et d'options

Si vous désirez un arbre complet des marque-pages, il sera nécessaire d'utiliser l'option de groupement GROUP_BY_FOLDER. Actuellement, le système de requêtes n'a pas besoin de cette option, et renverra toujours une hiérarchie lorsque le contenu d'exactement un dossier est demandé, il s'agit du bug 331487. Une fois qu'il sera corrigé, une requête de marque-pages sans GROUP_BY_FOLDER renverra une liste plate de tous les marque-pages dans tous les dossiers et sous-dossiers correspondant à la requête.

Pour une requête « normale » de marque-pages, vous aurez un dossier racine. Ce dossier sera donné à setFolders dans votre objet de requête :

options.setGroupingMode(options.GROUP_BY_FOLDER);
query.setFolders([toolbarFolder], 1);

Exécution de la requête

Les fonctions executeQuery et executeQueries renverront un objet nsINavHistoryResult contenant les résultats de la requête :

var result = historyService.executeQuery(query, options);

Lecture des résultats

Lorsque la requête se fait sur exactement un dossier groupé par dossier et sans paramètres compliqués comme des mots-clés ou des intervalles de date (comme dans cet exemple), la racine root de ce résultat sera un nsINavHistoryContainerResultNode correspondant à votre dossier. Si la requête est complexe ou que vous n'avez pas utilisé GROUP_BY_FOLDER, la racine sera un nsINavHistoryQueryResultNode.

Avant d'accéder aux enfants d'un conteneur de résultats, il faut d'abord l'ouvrir, et il est ensuite possible de parcourir ses enfants. Tant que le conteneur est ouvert, il écoutera les notifications du système de marque-pages pour rester à jour. Lorsque vous en avez terminé, assurez-vous de fermer le conteneur pour libérer les ressources. Dans le cas contraire, il continuera à recevoir des notifications et à se mettre à jour, ce qui ralentira tout le navigateur.

var rootNode = result.root;
rootNode.containerOpen = true;

// parcourt les enfants directs de ce dossier et les affiche en console
for (var i = 0; i < rootNode.childCount; i ++) {
  var node = rootNode.getChild(i);
  dump("Enfant : " + node.title + "\n");
}

// toujours fermer un conteneur après utilisation !
rootNode.containerOpen = false;

Si vous rencontrez un nœud dont le type est RESULT_TYPE_FOLDER ou un autre type de conteneur, il peut être ouvert pour parcourir sa hiérarchie. La section « Utilisation des résultats » dans Places:Système de requêtes vous intéressera sûrement pour comprendre quels sont les différents types de résultats.

Listing du code complet

var historyService = Components.classes["@mozilla.org/browser/nav-history-service;1"]
                               .getService(Components.interfaces.nsINavHistoryService);
var options = historyService.getNewQueryOptions();
var query = historyService.getNewQuery();

var bookmarksService = Components.classes["@mozilla.org/browser/nav-bookmarks-service;1"]
                                 .getService(Components.interfaces.nsINavBookmarksService);
var toolbarFolder = bookmarksService.toolbarFolder;

// la ligne suivante peut être commentée pour l'instant tant que le bug n'a pas été corrigé ; la version finale en aura besoin
options.setGroupingMode(options.GROUP_BY_FOLDER);
query.setFolders([toolbarFolder], 1);

var result = historyService.executeQuery(query, options);
var rootNode = result.root;
rootNode.containerOpen = true;

// parcourt les enfants directs de ce dossier et les affiche en console
for (var i = 0; i < rootNode.childCount; i ++) {
  var node = rootNode.getChild(i);
  dump("Enfant : " + node.title + "\n");
}

// toujours fermer un conteneur après utilisation !
rootNode.containerOpen = false;