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