Este documento es para los desarrolladores de aplicaciones y extensiones que tienen código los API de los marcadores y de el historial es Firefox 2 y anteriores y que están migrando a Firefox 3.
Visión general
Catálogo es un conjunto de API para la administración del historial de navegación y los meta datos de las URI. Esto incluye historial, marcadores, pestañas, favicons y anotaciones. Existen dos modelos de identidad en el sistema: URI e identificadores únicos para elementos del sistema de marcadores. Algunos de los API están centrados en URI, mientras que otros usan identificadores de elementos. La firma del API y su contexto, generalmente dejan claro qué modelo se requiere.
Marcadores
El servicio del toolkit marcadores es nsINavBookmarksService:
var bookmarks = Cc["@mozilla.org/browser/nav-bookmarks-service;1"].
getService(Ci.nsINavBookmarksService);
EL almacenamiento de los marcadores es jerárquico, sirviendo de modelo a las carpetas y su contenido. Varias carpetas significativas están disponibles como atributos de nsINavBookmarksService.
- nsINavBookmarksService.placesRoot - La carpeta raíz de la jerarquía.
- nsINavBookmarksService.bookmarksMenuFolder - El contenido de esta carpeta es visible en el menú Buscadores.
- nsINavBookmarksService.toolbarFolder - El contenido de esta carpeta está visible en la barra de herramientas Marcadores.
- nsINavBookmarksService.unfiledBookmarksFolder - Los elementos que han sido marcados con una estrella, pero que no están incluidos en ninguna carpeta.
- nsINavBookmarksService.tagsFolder - Las sub carpetas de esta carpeta son pestañas y sus hijos son URI que han sido marcadas con ese naombre de carpeta.
Nota: Este documento cubre el servicio de tolkit Catálogo. Sin embargo, los desarrolladores de Firefox pueden aprovechar diversos API de ayuda que son específicos del navegador:
Creación
Crear un Marcador
// create an nsIURI for the URL to be bookmarked.
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, // El Id de la carpeta donde se guardará el marcador.
bookmarkURI, // La URI del marcador - un objeto nsIURI.
bookmarks.DEFAULT_INDEX, // La posición del marcador en su carpeta padre.
"my bookmark title"); // El título del marcador.
Crear una carpeta
var folderId = bookmarks.createFolder( bookmarks.toolbarFolder, // La id de la carpeta donde se guardará la nueva carpeta. "my folder title", // El título de la nueva carpeta. bookmarks.DEFAULT_INDEX); // La posición de la nueva carpeta en su carpeta padre.
Crear un separador
var separatorId = bookmarks.insertSeparator( bookmarks.toolbarFolder, // La id de la carpeta donde será puesto el separador. bookmarks.DEFAULT_INDEX); // La posición del separador en su carpeta padre.
Crear un marcador dinámico
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, // La id de la carpeta donde será almacenado el marcador dinámico
"My Livemark Title", // El título del marcador dinámico
siteURI, // La URI del sitio. Un objeto nsIURI.
feedURI, // La URI del Canal. Un objeto nsIURI.
bookmarks.DEFAULT_INDEX); // La posición del marcador dinámico en su carpeta padre.
Lectura
Propiedades de los elementos
Para todos los elementos:
- String getItemTitle(aItemId) - XXX
- Int64 getItemIndex(aItemId) - XXX
- PRTime getItemType(aItemId) - XXX
- PRTime getItemDateAdded(aItemId) - XXX
- PRTime getItemLastModified(aItemId) - XXX
- Int64 getFolderIdForItem(aItemId) - Devuelve la id de la carpeta que contienen el elemento dado.
- String getItemGUID(aItemId) - Devuelve un identificador global único del elemento. Esto se usa principalmente en las extensiones, para sincronizar los datos de los marcadores entre diferentes perfiles.
Para marcadores:
- nsIURI getBookmarkURI(aItemId) - XXX
- String getKeywordForBookmark(aItemId) - XXX
Para carpetas:
- Int64 getChildFolder(aFolderId, aSubfolderTitle) - Devuelve la id de la primera sub carpeta que coincide con el título dado.
- Int64 getIdForItemAt(aFolderId, aPosition) - Devuelve la id del elemento en la posición determinada .
- Bool getFolderReadonly(aFolderId)
Contenido de las carpetas
Las consultas en Catálogo se ejecutan a través del servicio principal de historial. El ejemplo siguiente, muestra como listar el contenido de una carpeta de Marcadores y cómo acceder a las propiedades de cada elemento.
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 propiedad raíz del resultado de una consulta es un objeto representando la carpeta que especificaste.
var folderNode = result.root;
// Abre la carpeta y actúa reiterativamente con su contenido.
folderNode.containerOpen = true;
for (var i=0; i < folderNode.childCount; ++i) {
var childNode = folderNode.getChild(i);
// Algunas propiedades del elemento.
var title = childNode.title;
var id = childNode.itemId;
var type = childNode.type;
// Algunas acciones específicas del tipo.
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;
// ahora puedes actuar reiterativamente sobre el 'hijo' de una carpeta.
}
}
Hay documentación sobre otros tipos de nodo disponible en IDL.
Búsqueda
Actualización
Para todos los elementos:
- setItemTitle(aItemId, aTitle) - Cambia el título de un elemento.
- setItemIndex(aItemId, aIndex) - Cambia la posición de un elemento. NOTA: este no cambia los indices de toda la carpeta - para una solución administrada, usa moveItem.
- setItemDateAdded(aItemId, aDateAdded) - Ajusta la fecha en que fue añadido el elemento por primera vez, en micro segundos.
- setItemLastModified(aItemId, aLastModified) - Ajusta la fecha en que fue añadido el elemento por última vez, en micro segundos.
- setItemGUID(aItemId, aGUID) - Devuelve un identificador global único del elemento. Esto se usa principalmente en las extensiones, para sincronizar los datos de los marcadores entre diferentes perfiles.
- moveItem (aFolderId, aNewParentId, aIndex) - Mueve un elemento de una carpeta a otra.
Para marcadores:
- changeBookmarkURI(aItemId, aURI) - Cambia la URI del marcador.
- setKeywordForBookmark(aItemId, aKeyword) - Ajusta la palabra-clave para el marcador.
Borrado
- Elementos
- Contenedores
Observar
Importar/Exportar en formato HTML
Respaldo/Restauración
Nuevo
- Pestañas
- Anotaciones
- Búsquedas guardadas
- Contenedores dinámicos