Places:Migration Guide

From MDC

This document is for extension and application developers who have code that uses the bookmarks and history APIs in Firefox 2 or earlier, and are migrating that code to Firefox 3.

Contents 1 Overview 2 Bookmarks 2.1 Creating 2.2 Reading 2.2.1 Item Properties 2.2.2 Folder Contents 2.2.3 Searching 2.3 Updating 2.4 Deleting 2.5 Observing 2.6 HTML Import/Export 2.7 Backup/Restore 2.8 New 3 History 3.1 Adding 3.2 Querying 3.3 Observing 3.4 New

[edit] Overview

Places is a set of APIs for managing browsing history and URI metadata. This encompasses history, bookmarks, tags, favicons, and annotations. There are two models of identity in the system: URIs and unique identifiers for items in the bookmark system. Some of the APIs are URI-centric, some use item ids. The API signature and context usually make clear which is required.

[edit] Bookmarks

The toolkit bookmarks service is nsINavBookmarksService:

var bookmarks = Cc["@mozilla.org/browser/nav-bookmarks-service;1"].
                getService(Ci.nsINavBookmarksService);

The bookmarks datastore is hierarchical, modeling folders and their contents. Several significant folders are made available as attributes of nsINavBookmarksService.

• nsINavBookmarksService.placesRoot - The root folder of hierarchy.
• nsINavBookmarksService.bookmarksMenuFolder - The contents of this folder are visible in the Bookmarks menu.
• nsINavBookmarksService.toolbarFolder - The contents of this folder are visible on the Bookmarks toolbar.
• nsINavBookmarksService.unfiledBookmarksFolder - Items that have been "starred", but not places in any folder.
• nsINavBookmarksService.tagsFolder - Subfolders of this folder are tags, and their children are URIs that have been tagged with that folder's name.

Note: This document covers the toolkit Places services. However, Firefox developers can take advantage of several helper APIs that are browser-specific:

• FUEL
• nsIPlacesTransactionsService
• Places:PlacesUtils

[edit] Creating

Creating a Bookmark

// 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, // The id of the folder the bookmark will be placed in.
  bookmarkURI,             // The URI of the bookmark - an nsIURI object.
  bookmarks.DEFAULT_INDEX, // The position of the bookmark in it's parent folder.
  "my bookmark title");    // The title of the bookmark.

Creating a Folder

var folderId = bookmarks.createFolder(
  bookmarks.toolbarFolder, // The id of the folder the new folder will be placed in.
  "my folder title",       // The title of the new folder.
  bookmarks.DEFAULT_INDEX);    // The position of the new folder in it's parent folder.

Creating a Separator

var separatorId = bookmarks.insertSeparator(
  bookmarks.toolbarFolder, // The id of the folder the separator will be placed in.
  bookmarks.DEFAULT_INDEX);    // The position of the separator in it's parent folder.

Creating a Livemark

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, // The id of the folder the livemark will be placed in
  "My Livemark Title",        // The title of the livemark
  siteURI,                    // The URI of the site. A nsIURI object.
  feedURI,                    // The URI of the actual feed. A nsIURI object.
  bookmarks.DEFAULT_INDEX);   // The position of the livemark in its parent folder.

[edit] Reading

[edit] Item Properties

For all items:

• String getItemTitle(aItemId) - XXX
• Int64 getItemIndex(aItemId) - XXX
• PRTime getItemType(aItemId) - XXX
• PRTime getItemDateAdded(aItemId) - XXX
• PRTime getItemLastModified(aItemId) - XXX
• Int64 getFolderIdForItem(aItemId) - Returns the id of the folder containing the given item.
• String getItemGUID(aItemId) - Returns a globally unique identifier for the item. This is mainly for use by extensions that sync bookmark data between different profiles.

For bookmarks:

• nsIURI getBookmarkURI(aItemId) - XXX
• String getKeywordForBookmark(aItemId) - XXX

For folders:

• Int64 getChildFolder(aFolderId, aSubfolderTitle) - Returns the id of the first subfolder matching the given title.
• Int64 getIdForItemAt(aFolderId, aPosition) - Returns the id of the item at the given position (throws if there's no item there).
• Bool getFolderReadonly(aFolderId)

[edit] Folder Contents

Queries in Places are executed through the main history service. The example below shows how to enumerate a bookmark folder's contents, and how to access the properties of the items themselves.

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());

// The root property of a query result is an object representing the folder you specified above.
var folderNode = result.root;

// Open the folder, and iterate over it's contents.
folderNode.containerOpen = true;
for (var i=0; i < folderNode.childCount; ++i) {
  var childNode = folderNode.getChild(i);

  // Some item properties.
  var title = childNode.title;
  var id = childNode.itemId;
  var type = childNode.type;
  
  // Some type-specific actions.
  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;
    // now you can iterate over a subfolder's children

  }
}

Other available node types are documented in the IDL.

[edit] Searching

[edit] Updating

For all items:

• setItemTitle(aItemId, aTitle) - Changes an item's title.
• setItemIndex(aItemId, aIndex) - Changes an item's position. NOTE: This does not re-index the whole folder - use moveItem for a managed solution.
• setItemDateAdded(aItemId, aDateAdded) - Set the date the item was first added, in microseconds.
• setItemLastModified(aItemId, aLastModified) - Set the date the item was last modified, in microseconds.
• setItemGUID(aItemId, aGUID) - Returns a globally unique identifier for the item. This is mainly for use by extensions that sync bookmark data between different profiles.
• moveItem (aFolderId, aNewParentId, aIndex) - Move an item from one folder to another.

For bookmarks:

• changeBookmarkURI(aItemId, aURI) - Change a bookmark's URI.
• setKeywordForBookmark(aItemId, aKeyword) - Set the keyword for a bookmark.

[edit] Deleting

• Items
• Containers

[edit] Observing

[edit] HTML Import/Export

[edit] Backup/Restore

[edit] New

• Tags
• Annotations
• Saved Searches
• Dynamic Containers

[edit] History

[edit] Adding

[edit] Querying

[edit] Observing

[edit] New