Guía para la migración a catálogo

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("http://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("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, // 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

Historia

Agregar

Consultas

Observar

Nuevo

Etiquetas y colaboradores del documento

Etiquetas: 
 Colaboradores en esta página: HenryGR, Mgjbot
 Última actualización por: HenryGR,