paramName
( optional Type array of paramType )
Undocumented.
Description of this parameter from the json schema.
Bookmarks

Use the chrome.bookmarks module to create, organize, and otherwise manipulate bookmarks.

Manifest

You must declare the "bookmarks" permission in your extension's manifest to use the bookmarks API. For example:

{
  "name": "My extension that uses bookmarks",
  "version": "0.1",
  "permissions": [
    "bookmarks"
  ]
}

Description

BookmarkTreeNode objects are an important part of the chrome.bookmarks API. Each bookmark tree node represents either a URL or a group of bookmarks, as you can see in the following figure.

2 kinds of bookmark objects
[PENDING: this figure needs to be updated]

Properties

Objects that represent bookmarks can have the following properties:

id
An integer ID that's unique for each bookmark. IDs are unique and persisted within the current profile and are and stable across shutdown and startup of the browser.
title
The name of the bookmark. This is the user-visible string that describes the URL or group.
parentId (omitted for the root group)
The ID of the group that this bookmark is in.
index (optional; omitted for the root group)
The 0-based integer position of the bookmark within its group.
url (omitted for groups)
The URL of the page that the bookmark points to.
...

Examples

The following code creates a bookmark group with the title "Chromium bookmarks". The last argument defines a function to be executed after the folder is created. 

chrome.bookmarks.create({'parentId': bookmarkBar.id,
                         'title': 'Chromium bookmarks'},
                        function(newFolder) {...});

The next snippet creates a bookmark pointing to the Chromium developer doc. Since nothing too bad will happen if creating the bookmark fails, this snippet doesn't bother to define a callback function. 

chrome.bookmarks.create({'parentId': chromiumBookmarks.id,
                         'title': 'dev doc',
                         'url': 'http://code.google.com/chrome/extensions'});

Say you have bookmark hierarchy that looks like this:

  • Bookmarks
    • Google
      • Apps
        • ...
        • ...
        • ...
      • Google homepage
    • Example

Here's how those bookmarks might be represented with bookmark objects:

a hierarchy of bookmarks

Here's some code you could use to create that hierarchy:

[PENDING: ...code goes here...]

API reference: chrome.bookmarks

Methods

create

void chrome.bookmarks.create(, object bookmark, function callback)

Creates a bookmark or folder under the specified parentId. If url is NULL or missing, it will be a folder.

Parameters

bookmark
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
parentId
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
index
( optional Type array of integer )
Undocumented.
Description of this parameter from the json schema.
title
( optional Type array of string )
Undocumented.
Description of this parameter from the json schema.
url
( optional Type array of string )
Undocumented.
Description of this parameter from the json schema.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

If you specify the callback parameter, it should specify a function that looks like this: 

function(BookmarkTreeNode result) {...});
result
( BookmarkTreeNode array of paramType )
Undocumented.
Description of this parameter from the json schema.

get

void chrome.bookmarks.get(, string or array of string idOrIdList, function callback)

Retrieves the specified BookmarkTreeNode(s).

Parameters

idOrIdList
( Type array of string or array of string )
A single string-valued id, or an array of string-valued ids
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

If you specify the callback parameter, it should specify a function that looks like this: 

function(array of BookmarkTreeNode results) {...});
results
( Type array of BookmarkTreeNode array of paramType paramType )
Undocumented.
Description of this parameter from the json schema.

getChildren

void chrome.bookmarks.getChildren(, string id, function callback)

Retrieves the children of the specified BookmarkTreeNode id.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

If you specify the callback parameter, it should specify a function that looks like this: 

function(array of BookmarkTreeNode results) {...});
results
( Type array of BookmarkTreeNode array of paramType paramType )
Undocumented.
Description of this parameter from the json schema.

getTree

void chrome.bookmarks.getTree(, function callback)

Retrieves the entire Bookmarks hierarchy.

Parameters

callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

If you specify the callback parameter, it should specify a function that looks like this: 

function(array of BookmarkTreeNode results) {...});
results
( Type array of BookmarkTreeNode array of paramType paramType )
Undocumented.
Description of this parameter from the json schema.

move

void chrome.bookmarks.move(, string id, object destination, function callback)

Moves the specified BookmarkTreeNode to the provided location.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
destination
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
parentId
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
index
( optional Type array of integer )
Undocumented.
Description of this parameter from the json schema.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

If you specify the callback parameter, it should specify a function that looks like this: 

function(BookmarkTreeNode result) {...});
result
( BookmarkTreeNode array of paramType )
Undocumented.
Description of this parameter from the json schema.

remove

void chrome.bookmarks.remove(, string id, function callback)

Removes a bookmark or an empty bookmark folder.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

If you specify the callback parameter, it should specify a function that looks like this: 

function() {...});

removeTree

void chrome.bookmarks.removeTree(, string id, function callback)

Recursively removes a bookmark folder.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

If you specify the callback parameter, it should specify a function that looks like this: 

function() {...});

search

void chrome.bookmarks.search(, string query, function callback)

Seaches for BookmarkTreeNodes matching the given query.

Parameters

query
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

If you specify the callback parameter, it should specify a function that looks like this: 

function(array of BookmarkTreeNode results) {...});
results
( Type array of BookmarkTreeNode array of paramType paramType )
Undocumented.
Description of this parameter from the json schema.

update

void chrome.bookmarks.update(, string id, object changes, function callback)

Updates the properties of a bookmark or folder. Only specify the properties that you want to change, unspecified properties will be left unchanged. NOTE: currently, only 'title' is supported.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
changes
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
title
( optional Type array of string )
Undocumented.
Description of this parameter from the json schema.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

If you specify the callback parameter, it should specify a function that looks like this: 

function(BookmarkTreeNode result) {...});
result
( BookmarkTreeNode array of paramType )
Undocumented.
Description of this parameter from the json schema.

Events

onChanged

chrome.bookmarks.onChanged.addListener(function(string id, object changeInfo) {...});

Fired when a bookmark or folder changes. NOTE: currently, only title changes trigger this.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
changeInfo
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
title
( Type array of string )
Undocumented.
Description of this parameter from the json schema.

onChildrenReordered

chrome.bookmarks.onChildrenReordered.addListener(function(string id, object reorderInfo) {...});

Fired when the children of a folder have changed their order due to the order being sorted in the UI. This is not called as a result of a move().

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
reorderInfo
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
childIds
( Type array of Type array of string paramType )
Undocumented.
Description of this parameter from the json schema.

onCreated

chrome.bookmarks.onCreated.addListener(function(string id, BookmarkTreeNode bookmark) {...});

Fired when a bookmark or folder is created.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
bookmark
( BookmarkTreeNode array of paramType )
Undocumented.
Description of this parameter from the json schema.

onMoved

chrome.bookmarks.onMoved.addListener(function(string id, object moveInfo) {...});

Fired when a bookmark or folder is moved to a different parent folder.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
moveInfo
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
parentId
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
index
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
oldParentId
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
oldIndex
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.

onRemoved

chrome.bookmarks.onRemoved.addListener(function(string id, object removeInfo) {...});

Fired when a bookmark or folder is removed. When a folder is removed recursively, a single notification is fired for the folder, and none for its contents.

Parameters

id
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
removeInfo
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
parentId
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
index
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.

Types

BookmarkTreeNode

paramName
( Type array of object )
A node in the bookmarks tree, which is either a bookmark or a folder. Child nodes are ordered within their parent.
id
( Type array of string )
The unique identifier for the node.
parentId
( optional Type array of string )
The id of the parent folder node. Not present in the root node.
index
( optional Type array of integer )
The 0-based position of this node within its parent.
url
( optional Type array of string )
The URL navigated to when a user clicks on the bookmark. This field isn't present for folders.
title
( Type array of string )
The text displayed for the node.
dateAdded
( optional Type array of number )
When this node was created, represented in milliseconds since the epoch (new Date(dateAdded)).
dateGroupModified
( optional Type array of number )
When the contents of this folder last changed, represented in milliseconds since the epoch.
children
( optional Type array of BookmarkTreeNode array of paramType paramType )
An ordered list of children of this node.