Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.

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("https://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("https://www.mozilla.com", null, null);
var feedURI = IOService.newURI("https://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,