Manipulating bookmarks using Places

The Places bookmarks service, provided by the nsINavBookmarksService interface, provides methods for creating, deleting, and manipulating bookmarks and bookmark folders. This article offers examples for how to perform common bookmark management tasks using the bookmarks service.

Initiating the bookmarks service

As is the case with nearly all interfaces, before you can use the bookmarks service, you need to get access to it:

var bmsvc = Components.classes["@mozilla.org/browser/nav-bookmarks-service;1"]
                      .getService(Components.interfaces.nsINavBookmarksService);

Creating a bookmark folder

Creating a new bookmark folder is done using the nsINavBookmarksService.createFolder() method. For example, to create a new folder in the Bookmarks menu:

var menuFolder = bmsvc.bookmarksMenuFolder; // Bookmarks menu folder
var newFolderId = bmsvc.createFolder(menuFolder, "Folder name here", bmsvc.DEFAULT_INDEX);

This code locates the Bookmarks menu's folder, then creates a new folder named "Folder name here" in it. Specifying DEFAULT_INDEX as the index at which to insert the new folder places it at the end of the list.

You can easily change this code to insert the new folder into the bookmarks toolbar by changing bookmarksMenuFolder to another folder attribute.

Creating a new bookmark

To create a new bookmark, use the nsINavBookmarksService.insertBookmark() method. The URI for the bookmark needs to be specified using an nsIURI object.

var ios = Components.classes["@mozilla.org/network/io-service;1"]
                    .getService(Components.interfaces.nsIIOService);
var uri = ios.newURI("http://google.com/", null, null);
var newBkmkId = bmsvc.insertBookmark(newFolderId, uri, bmsvc.DEFAULT_INDEX, "");

This example instantiates the nsIIOService and uses it to create an nsIURI referring to the Google web site, then calls nsINavBookmarksService.insertBookmark() to create a new bookmark to Google, placing it at the end of the bookmarks folder referenced by newBkmkId.

Finding bookmark items

If you know the URI of a site and wish to find all bookmarks that link to it, you can use the nsINavBookmarksService.getBookmarkIdsForURI() method.

var ios = Components.classes["@mozilla.org/network/io-service;1"]
                    .getService(Components.interfaces.nsIIOService);
var uri = ios.newURI("http://google.com/", null, null);
var bookmarksArray = bmsvc.getBookmarkIdsForURI(uri, {});

After executing this code, the array bookmarksArray contains the IDs of all bookmarks that refer to the specified URI (in this case, "http://google.com").

Manipulating existing items

There are a number of convenient methods you can use to make changes to existing bookmarks and bookmark folders. This section covers some of them.

The item title

To change the title of a bookmark or bookmark folder, you use the nsINavBookmarksService.setItemTitle() method.

bmsvc.setItemTitle(newBkmkId, "New title");

This sets the title of the item referenced by the ID newBkmkId to "New title".

You can fetch the current title of an item using the nsINavBookmarksService.getItemTitle() method:

var thisTitle = bmsvc.getItemTitle(newBkmkId);

This code will display an alert containing the title of the item referenced by the ID newBkmkId.

The item URI

Similarly, you can obtain the URI corresponding to a given bookmark item by calling the nsINavBookmarksService.getBookmarkURI() method.

var thisURI = bmsvc.getBookmarkURI(newBkmkId);

Assuming you've run all the code samples previous to this one, this will output "http://google.com".

You can use the nsINavBookmarksService.changeBookmarkURI() method to update the URI for a given bookmark item:

var uri = ios.newURI("http://mozilla.com/", null, null);
bmsvc.changeBookmarkURI(newBkmkId, uri);

This example changes the bookmark to refer to the Mozilla web site instead of Google.

Note: All annotations, tags, and so forth are kept when the bookmark's URI is changed.

Checking to see if a URI is bookmarked

If you want to see if a given URI is already bookmarked -- for example, to avoid creating a new bookmark for a site that's already bookmarked -- you can use the nsINavBookmarksService.isBookmarked() method.

var ios = Components.classes["@mozilla.org/network/io-service;1"]
                    .getService(Components.interfaces.nsIIOService);
var uri = ios.newURI("http://mozilla.com/", null, null);
if (!bmsvc.isBookmarked(uri)) {
  bmsvc.insertBookmark(bmsvc.toolbarFolder, uri, bmsvc.DEFAULT_INDEX, "Mozilla");
}

This example looks to see if the user already has a bookmark for the Mozilla web site, and, if not, creates one, adding it to the user's bookmarks toolbar.

Finding the folder containing an item

If you need to know what folder contains an item (this can be especially handy after using nsINavBookmarksService.getBookmarkIdsForURI() to find bookmarks for a given URI), you can use the nsINavBookmarksService.getFolderIdForItem() method.

var parentFolderId = bmsvc.getFolderIdForItem(newBkmkId);

Observing changes to bookmarks and tags

To set up an observer to listen for changes related to bookmarks, you will need to create an nsINavBookmarkObserver object and use the nsINavBookmarksService.addObserver() and nsINavBookmarksService.removeObserver() methods. Note that this example takes advantage of XPCOMUtils to generate the nsISupports.QueryInterface() method.

// An nsINavBookmarkObserver
var myExt_bookmarkListener = {
  onBeginUpdateBatch: function() {},
  onEndUpdateBatch: function() {},
  onItemAdded: function(aItemId, aFolder, aIndex) {},
  onItemRemoved: function(aItemId, aFolder, aIndex) {},
  onItemChanged: function(aBookmarkId, aProperty, aIsAnnotationProperty, aValue) {
    MyExtension.doSomething();
  },
  onItemVisited: function(aBookmarkId, aVisitID, time) {},
  onItemMoved: function(aItemId, aOldParent, aOldIndex, aNewParent, aNewIndex) {},
  QueryInterface: XPCOMUtils.generateQI([Components.interfaces.nsINavBookmarkObserver])
};
// An extension
var MyExtension = {
  // This function is called when my add-on is loaded
  onLoad: function() {
    bmsvc.addObserver(myExt_bookmarkListener, false);
  },
  // This function is called when my add-on is unloaded
  onUnLoad: function() {
    bmsvc.removeObserver(myExt_bookmarkListener);
  },
  doSomething: function() {
    alert("Did something.");
  }
};