Guide de migration vers Places

Ce document est destiné aux développeurs d'extensions et d'applications utilisant les API de marque-pages et d'historique dans Firefox 2 ou précédents, et migrent leur code vers Firefox 3.

Aperçu

Places est un ensemble d'API pour gérer l'historique de navigation et les métadonnées d'URI. Cela regroupe l'historique, les marque-pages, les étiquettes, favicônes et annotations. Deux modèles d'identité existent dans le système : les URI et les identifiants uniques pour les éléments du système de marque-pages. Certaines de ces API sont basées sur les URI, d'autres utilisent des id. La signature de l'API et son contexte suffisent généralement à indiquer ce qui doit être fourni.

Marque-pages

Le service de marque-pages du toolkit est nsINavBookmarksService :

var bookmarks = Cc["@mozilla.org/browser/nav-bookmarks-service;1"].
                getService(Ci.nsINavBookmarksService);

Le magasin de données des marque-pages est hiérarchique, modélisant les dossiers et leur contenu. Certains dossiers significatifs sont disponibles comme attributs de nsINavBookmarksService.

  • nsINavBookmarksService.placesRoot — Le dossier racine de la hiérarchie.
  • nsINavBookmarksService.bookmarksMenuFolder — Le contenu de ce dossier est visible dans le menu Marque-pages.
  • nsINavBookmarksService.toolbarFolder — Le contenu de ce dossier est visible dans la Barre personnelle.
  • nsINavBookmarksService.unfiledBookmarksFolder — Les éléments qui ont été marqués (avec une étoile), mais n'ont été placés dans aucun dossier.
  • nsINavBookmarksService.tagsFolder — Les sous-dossiers de ce dossier sont des étiquettes, et leurs enfants sont des URI qui ont été étiquetées avec le nom de ce dossier.

Note : ce document couvre le service Places du toolkit. Cependant, les développeurs de Firefox peuvent tirer profit de certaines API supplémentaires qui sont spécifiques au navigateur :

Création

Création d'un marque-page

// crée un nsIURI pour l'URL à marquer.
var bookmarkURI = Cc["@mozilla.org/network/io-service;1"].
                  getService(Ci.nsIIOService).
                  newURI("http://www.mozilla.com", null, null);

var bookmarkId = bookmarks.insertBookmark(
  bookmarks.toolbarFolder, // L'id du dossier dans lequel le marque-page sera placé.
  bookmarkURI,             // L'URI du marque-page — un objet nsIURI.
  bookmarks.DEFAULT_INDEX, // La position du marque-page dans son dossier parent.
  "mon titre");    // Le titre du marque-page.

Création d'un dossier

var folderId = bookmarks.createFolder(
  bookmarks.toolbarFolder, // L'id du dossier dans lequel le nouveau dossier sera placé.
  "mon dossier",           // Le titre du nouveau dossier .
  bookmarks.DEFAULT_INDEX);    // La position du nouveau dossier dans son dossier parent.

Création d'un séparateur

var separatorId = bookmarks.insertSeparator(
  bookmarks.toolbarFolder, //L'id du dossier dans lequel le séparateur sera placé.
  bookmarks.DEFAULT_INDEX);    // La position du séparateur dans son dossier parent.

Création d'un marque-page dynamique

var IOService = Cc["@mozilla.org/network/io-service;1"].
                  getService(Ci.nsIIOService);

var siteURI = IOService.newURI("http://www.mozilla.com", null, null);
var feedURI = IOService.newURI("http://www.mozilla.org/news.rdf", null, null);

var livemarks = Cc["@mozilla.org/browser/livemark-service;2"].
                getService(Ci.nsILivemarkService);

livemarks.createLivemark(bookmarks.toolbarFolder, // L'id du dossier dans lequel le marque-page dynamique sera placé.
  "Mon titre",        // Le titre du marque-page dynamique
  siteURI,                    // L'URI du site. Un objet nsIURI.
  feedURI,                    // L'URI du flux. Un objet nsIURI.
  bookmarks.DEFAULT_INDEX);   // La position du marque-page dynamique dans son dossier parent.

Lecture

Propriétés d'un élément

Pour tous les éléments :

  • String getItemTitle(aItemId) — XXX
  • Int64 getItemIndex(aItemId) — XXX
  • PRTime getItemType(aItemId) — XXX
  • PRTime getItemDateAdded(aItemId) — XXX
  • PRTime getItemLastModified(aItemId) — XXX
  • Int64 getFolderIdForItem(aItemId) — Renvoie l'id du dossier contenant l'élément donné.
  • String getItemGUID(aItemId) — Renvoie un identifiant globalement unique pour l'élément. Surtout utile pour les extensions synchronisant des données de marque-pages entre différents profils.

Pour les marque-pages :

  • nsIURI getBookmarkURI(aItemId) — XXX
  • String getKeywordForBookmark(aItemId) — XXX

Pour les dossiers :

  • Int64 getChildFolder(aFolderId, aSubfolderTitle) — Renvoie l'id du premier sous-dossier correspondant au titre donné.
  • Int64 getIdForItemAt(aFolderId, aPosition) — Renvoie l'id de l'élément à la position donnée (déclenche une exception s'il n'y en a pas).
  • Bool getFolderReadonly(aFolderId)

Contenu d'un dossier

Les requêtes dans Places sont exécutées au travers du service d'historique principal. L'exemple ci-dessous montre comment parcourir le contenu d'un dossier de marque-pages, et comment accéder aux propriétés des éléments eux-mêmes.

var history = Cc["@mozilla.org/browser/nav-history-service;1"].
              getService(Ci.nsINavHistoryService);
var query = history.getNewQuery();
query.setFolders([myFolderId], 1);

var result = history.executeQuery(query, history.getNewQueryOptions());

// La propriété root d'un résultat de requête est un objet représentant le dossier spécifié plus haut.
var folderNode = result.root;

// Ouverture du dossier et parcours de son contenu.
folderNode.containerOpen = true;
for (var i=0; i < folderNode.childCount; ++i) {
  var childNode = folderNode.getChild(i);

  // Quelques propriétés des éléments.
  var title = childNode.title;
  var id = childNode.itemId;
  var type = childNode.type;
  
  // Quelques actions spécifiques selon le type.
  if (type == Ci.nsINavHistoryResultNode.RESULT_TYPE_URI) {

    var uri = childNode.uri;

  }
  else if (type == Ci.nsINavHistoryResultNode.RESULT_TYPE_FOLDER) {

    childNode.QueryInterface(Ci.nsINavHistoryContainerResultNode);
    childNode.containerOpen = true;
    // à présent vous pouvez parcourir les enfants d'un sous-dossier

  }
}

Les autres types de nœuds disponibles sont documentés dans l'IDL.

Recherche

Mise à jour

Pour tous les éléments :

  • setItemTitle(aItemId, aTitle) — Modifie le titre d'un élément.
  • setItemIndex(aItemId, aIndex) — Modifie la position d'un élément. Note : ceci ne réindexe pas le dossier complet — utilisez moveItem pour une solution gérée.
  • setItemDateAdded(aItemId, aDateAdded) — Définit la date d'ajout de l'élément, en microsecondes.
  • setItemLastModified(aItemId, aLastModified) — Définit la date de dernière modification de l'élément, en microsecondes.
  • setItemGUID(aItemId, aGUID) — Renvoie un identifiant globalement unique pour l'élément. Surtout utile pour les extensions synchronisant les données de marque-pages entre différents profils.
  • moveItem (aFolderId, aNewParentId, aIndex) — Déplace un élément d'un dossier à un autre.

Pour les marque-pages :

  • changeBookmarkURI(aItemId, aURI) — Change l'URI d'un marque-page.
  • setKeywordForBookmark(aItemId, aKeyword) — Définit un mot-clié pour un marque-page.

Suppression

  • Éléments
  • Conteneurs

Observation

Import/export HTML

Sauvegarde/restauration

Nouveautés

  • Balises
  • Annotations
  • Recherches enregistrées
  • Conteneurs dynamiques

Historique

Ajout

Interrogation

Observation

Nouveautés

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : Mgjbot, BenoitL
 Dernière mise à jour par : Mgjbot,