Manipulating bookmarks using Places

  • Revision slug: Manipulating_bookmarks_using_Places
  • Revision title: Manipulating bookmarks using Places
  • Revision id: 287342
  • Created:
  • Creator: sdwilsh
  • Is current revision? No
  • Comment 55 words added, 42 words removed

Revision Content

{{ Fx_minversion_header(3) }}

The Places bookmarks service, provided by the {{ Interface("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 {{ Ifmethod("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 {{ Ifmethod("nsINavBookmarksService", "insertBookmark") }} method. The URI for the bookmark needs to be specified using an {{ Interface("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 {{ Interface("nsIIOService") }} and uses it to create an {{ Interface("nsIURI") }} referring to the Google web site, then calls {{ Ifmethod("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 {{ Ifmethod("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 <tt>bookmarksArray</tt> 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 {{ Ifmethod("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 {{ Ifmethod("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 {{ Ifmethod("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 {{ Ifmethod("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 {{ Ifmethod("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 {{ Ifmethod("nsINavBookmarksService", "getBookmarkIdsForURI") }} to find bookmarks for a given URI), you can use the {{ Ifmethod("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 {{ Interface("nsINavBookmarkObserver") }} object and use the {{ Ifmethod("nsINavBookmarksService", "addObserver") }} and {{ Ifmethod("nsINavBookmarksService", "removeObserver") }} methods.  Note that this example takes advantage of XPCOMUtils to generate the {{ Ifmethod("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.");
  }
};

See also

  • {{ Interface("nsINavBookmarksService") }}
  • {{ Interface("nsINavBookmarkObserver") }}
  • Places
{{ languages( { "es": "es/Manipular_marcadores_usando_el_cat\u00e1logo", "ja": "ja/Manipulating_bookmarks_using_Places" } ) }}

Revision Source

<div class="noinclude">
<p>{{ Fx_minversion_header(3) }}
</p>
</div>
<p>The Places bookmarks service, provided by the {{ Interface("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.
</p>
<h3 id="Initiating_the_bookmarks_service" name="Initiating_the_bookmarks_service">Initiating the bookmarks service</h3>
<p>As is the case with nearly all interfaces, before you can use the bookmarks service, you need to get access to it:
</p>
<pre class="eval">var bmsvc = Components.classes["@mozilla.org/browser/nav-bookmarks-service;1"]
                      .getService(Components.interfaces.nsINavBookmarksService);
</pre>
<h3 id="Creating_a_bookmark_folder" name="Creating_a_bookmark_folder">Creating a bookmark folder</h3>
<p>Creating a new bookmark folder is done using the {{ Ifmethod("nsINavBookmarksService", "createFolder") }} method. For example, to create a new folder in the Bookmarks menu:</p>
<pre class="eval">var menuFolder = bmsvc.bookmarksMenuFolder; // Bookmarks menu folder
var newFolderId = bmsvc.createFolder(menuFolder, "Folder name here", bmsvc.DEFAULT_INDEX);
</pre>
<p>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.</p>
<p>You can easily change this code to insert the new folder into the bookmarks toolbar by changing <code>bookmarksMenuFolder</code> to <a class="internal" href="/en/nsINavBookmarksService#Attributes" title="en/nsINavBookmarksService#Attributes">another folder attribute</a>.</p><h3 id="Creating_a_new_bookmark" name="Creating_a_new_bookmark">Creating a new bookmark</h3>
<p>To create a new bookmark, use the {{ Ifmethod("nsINavBookmarksService", "insertBookmark") }} method. The URI for the bookmark needs to be specified using an {{ Interface("nsIURI") }} object.</p>
<pre class="eval">var ios = Components.classes["@mozilla.org/network/io-service;1"]
                    .getService(Components.interfaces.nsIIOService);
var uri = ios.newURI(<span class="nowiki">"http://google.com/"</span>, null, null);
var newBkmkId = bmsvc.insertBookmark(newFolderId, uri, bmsvc.DEFAULT_INDEX, "");
</pre>
<p>This example instantiates the {{ Interface("nsIIOService") }} and uses it to create an {{ Interface("nsIURI") }} referring to the Google web site, then calls {{ Ifmethod("nsINavBookmarksService", "insertBookmark") }} to create a new bookmark to Google, placing it at the end of the bookmarks folder referenced by <code>newBkmkId</code>.</p><h3 id="Finding_bookmark_items" name="Finding_bookmark_items">Finding bookmark items</h3>
<p>If you know the URI of a site and wish to find all bookmarks that link to it, you can use the {{ Ifmethod("nsINavBookmarksService", "getBookmarkIdsForURI") }} method.
</p>
<pre class="eval">var ios = Components.classes["@mozilla.org/network/io-service;1"]
                    .getService(Components.interfaces.nsIIOService);
var uri = ios.newURI(<span class="nowiki">"http://google.com/"</span>, null, null);
var bookmarksArray = bmsvc.getBookmarkIdsForURI(uri, {});
</pre>
<p>After executing this code, the array <tt>bookmarksArray</tt> contains the IDs of all bookmarks that refer to the specified URI (in this case, <span class="nowiki">"http://google.com"</span>).
</p>
<h3 id="Manipulating_existing_items" name="Manipulating_existing_items">Manipulating existing items</h3>
<p>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.</p>
<h4 id="The_item_title" name="The_item_title">The item title</h4>
<p>To change the title of a bookmark or bookmark folder, you use the {{ Ifmethod("nsINavBookmarksService", "setItemTitle") }} method.</p>
<pre class="eval">bmsvc.setItemTitle(newBkmkId, "New title");
</pre>
<p>This sets the title of the item referenced by the ID <code>newBkmkId</code> to "New title".</p>
<p>You can fetch the current title of an item using the {{ Ifmethod("nsINavBookmarksService", "getItemTitle") }} method:</p>
<pre class="eval">var thisTitle = bmsvc.getItemTitle(newBkmkId);
</pre>
<p>This code will display an alert containing the title of the item referenced by the ID <code>newBkmkId</code>.</p>
<h4 id="The_item_URI" name="The_item_URI">The item URI</h4>
<p>Similarly, you can obtain the URI corresponding to a given bookmark item by calling the {{ Ifmethod("nsINavBookmarksService", "getBookmarkURI") }} method.</p>
<pre class="eval">var thisURI = bmsvc.getBookmarkURI(newBkmkId);
</pre>
<p>Assuming you've run all the code samples previous to this one, this will output <span class="nowiki">"http://google.com"</span>.</p>
<p>You can use the {{ Ifmethod("nsINavBookmarksService", "changeBookmarkURI") }} method to update the URI for a given bookmark item:</p>
<pre class="eval">var uri = ios.newURI(<span class="nowiki">"http://mozilla.com/"</span>, null, null);
bmsvc.changeBookmarkURI(newBkmkId, uri);
</pre>
<p>This example changes the bookmark to refer to the Mozilla web site instead of Google.</p>
<p>{{ Note("All annotations, tags, and so forth are kept when the bookmark\'s URI is changed.") }}</p><h3 id="Checking_to_see_if_a_URI_is_bookmarked" name="Checking_to_see_if_a_URI_is_bookmarked">Checking to see if a URI is bookmarked</h3>
<p>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 {{ Ifmethod("nsINavBookmarksService", "isBookmarked") }} method.</p>
<pre class="eval">var ios = Components.classes["@mozilla.org/network/io-service;1"]
                    .getService(Components.interfaces.nsIIOService);
var uri = ios.newURI(<span class="nowiki">"http://mozilla.com/"</span>, null, null);
if (!bmsvc.isBookmarked(uri)) {
  bmsvc.insertBookmark(bmsvc.toolbarFolder, uri, bmsvc.DEFAULT_INDEX, "Mozilla");
}
</pre>
<p>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.</p><h3 id="Finding_the_folder_containing_an_item" name="Finding_the_folder_containing_an_item">Finding the folder containing an item</h3>
<p>If you need to know what folder contains an item (this can be especially handy after using {{ Ifmethod("nsINavBookmarksService", "getBookmarkIdsForURI") }} to find bookmarks for a given URI), you can use the {{ Ifmethod("nsINavBookmarksService", "getFolderIdForItem") }} method.
</p>
<pre class="eval">var parentFolderId = bmsvc.getFolderIdForItem(newBkmkId);
</pre>
<h3 id="Observing_changes_to_bookmarks_and_tags" name="Observing_changes_to_bookmarks_and_tags">Observing changes to bookmarks and tags</h3>
<p>To set up an observer to listen for changes related to bookmarks, you will need to create an {{ Interface("nsINavBookmarkObserver") }} object and use the {{ Ifmethod("nsINavBookmarksService", "addObserver") }} and {{ Ifmethod("nsINavBookmarksService", "removeObserver") }} methods.  Note that this example takes advantage of <a class="internal" href="/En/XPCOMUtils.jsm" title="En/XPCOMUtils.jsm">XPCOMUtils</a> to generate the {{ Ifmethod("nsISupports", "QueryInterface") }} method.</p>
<pre class="eval">// 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.");
  }
};
</pre><h3 id="See_also" name="See_also">See also</h3>
<ul><li> {{ Interface("nsINavBookmarksService") }}
</li><li> {{ Interface("nsINavBookmarkObserver") }}
</li><li> <a href="en/Places">Places</a>
</li></ul>
<div class="noinclude">
</div>
{{ languages( { "es": "es/Manipular_marcadores_usando_el_cat\u00e1logo", "ja": "ja/Manipulating_bookmarks_using_Places" } ) }}
Revert to this revision