mozilla
Vos résultats de recherche

    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

    Contributors to this page: BenoitL, Mgjbot
    Dernière mise à jour par : Mgjbot,