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