whale.bookmarks
| Description: | Use the whale.bookmarks API to create, organize, and otherwise manipulate bookmarks. Also see Override Pages, which you can use to create a custom Bookmark Manager page. |
|---|---|
| Availability: | Since Chrome 20. |
| Permissions: | "bookmarks" |
{
"name": "My extension",
...
**"permissions": [
"bookmarks"
]**,
...
}
## Objects and properties
Bookmarks are organized in a tree, where each node in the tree is either a bookmark or a folder (sometimes called a _group_). Each node in the tree is represented by a [bookmarks.BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) object.
`BookmarkTreeNode` properties are used throughout the `whale.bookmarks` API. For example, when you call [bookmarks.create](/extensions/bookmarks#method-create), you pass in the new node's parent (`parentId`), and, optionally, the node's `index`, `title`, and `url` properties. See [bookmarks.BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) for information about the properties a node can have.
**Note:** You cannot use this API to add or remove entries in the root folder. You also cannot rename, move, or remove the special "Bookmarks Bar" and "Other Bookmarks" folders.
## Examples
The following code creates a folder with the title "Extension bookmarks". The first argument to `create()` specifies properties for the new folder. The second argument defines a function to be executed after the folder is created.
whale.bookmarks.create({'parentId': bookmarkBar.id,
'title': 'Extension bookmarks'},
function(newFolder) {
console.log("added folder: " + newFolder.title);
});
The next snippet creates a bookmark pointing to the developer documentation for extensions. Since nothing bad will happen if creating the bookmark fails, this code doesn't bother to define a callback function.
whale.bookmarks.create({'parentId': extensionsFolderId,
'title': 'Extensions doc',
'url': 'http://code.google.com/chrome/extensions'});
For an example of using this API, see the [basic bookmarks sample](https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/docs/examples/api/bookmarks/basic/). For other examples and for help in viewing the source code, see [Samples](samples).
## Types
### BookmarkTreeNodeUnmodifiable
Indicates the reason why this node is unmodifiable. The managed value indicates that this node was configured by the system administrator. Omitted if the node can be modified by the user and the extension (default).
| Enum |
|---|
| `"managed"` |
### BookmarkTreeNode
A node (either a bookmark or a folder) in the bookmark tree. Child nodes are ordered within their parent folder.
| properties |
|---|
| string | id |
The unique identifier for the node. IDs are unique within the current profile, and they remain valid even after the browser is restarted.
|
| string | (optional) parentId |
The `id` of the parent folder. Omitted for the root node.
|
| integer | (optional) index |
The 0-based position of this node within its parent folder.
|
| string | (optional) url |
The URL navigated to when a user clicks the bookmark. Omitted for folders.
|
| string | title |
The text displayed for the node.
|
| double | (optional) dateAdded |
When this node was created, in milliseconds since the epoch (`new Date(dateAdded)`).
|
| double | (optional) dateGroupModified |
When the contents of this folder last changed, in milliseconds since the epoch.
|
| [BookmarkTreeNodeUnmodifiable](/extensions/bookmarks#type-BookmarkTreeNodeUnmodifiable) | (optional) unmodifiable |
Since Chrome 37.
Indicates the reason why this node is unmodifiable. The managed value indicates that this node was configured by the system administrator or by the custodian of a supervised user. Omitted if the node can be modified by the user and the extension (default).
|
| array of [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) | (optional) children |
An ordered list of children of this node.
|
## Properties
| `1,000,000` | `whale.bookmarks.MAX_WRITE_OPERATIONS_PER_HOUR` |
|---|---|
**Deprecated** since Chrome 38. Bookmark write operations are no longer limited by Chrome.
|
| `1,000,000` | `whale.bookmarks.MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE` |
**Deprecated** since Chrome 38. Bookmark write operations are no longer limited by Chrome.
|
## Methods
### get
`whale.bookmarks.get(string or array of string idOrIdList, function callback)`
Retrieves the specified BookmarkTreeNode(s).
| Parameters |
|---|
| string or array of string | idOrIdList |
A single string-valued id, or an array of string-valued ids
|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(array of [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) results) {...};`
| array of [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) | results | |
|---|---|---|
|
### getChildren
`whale.bookmarks.getChildren(string id, function callback)`
Retrieves the children of the specified BookmarkTreeNode id.
| Parameters |
|---|
| string | id | |
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(array of [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) results) {...};`
| array of [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) | results | |
|---|---|---|
|
### getRecent
`whale.bookmarks.getRecent(integer numberOfItems, function callback)`
Retrieves the recently added bookmarks.
| Parameters |
|---|
| integer | numberOfItems |
The maximum number of items to return.
|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(array of [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) results) {...};`
| array of [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) | results | |
|---|---|---|
|
### getTree
`whale.bookmarks.getTree(function callback)`
Retrieves the entire Bookmarks hierarchy.
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(array of [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) results) {...};`
| array of [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) | results | |
|---|---|---|
|
### getSubTree
`whale.bookmarks.getSubTree(string id, function callback)`
Retrieves part of the Bookmarks hierarchy, starting at the specified node.
| Parameters |
|---|
| string | id |
The ID of the root of the subtree to retrieve.
|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(array of [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) results) {...};`
| array of [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) | results | |
|---|---|---|
|
### search
`whale.bookmarks.search(string or object query, function callback)`
Searches for BookmarkTreeNodes matching the given query. Queries specified with an object produce BookmarkTreeNodes matching all specified properties.
| Parameters |
|---|
| string or object | query |
Either a string of words and quoted phrases that are matched against bookmark URLs and titles, or an object. If an object, the properties `query`, `url`, and `title` may be specified and bookmarks matching all specified properties will be produced.
|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(array of [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) results) {...};`
| array of [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) | results | |
|---|---|---|
|
### create
`whale.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 |
|---|
| object | bookmark |
| string | (optional) parentId |
|---|---|
Defaults to the Other Bookmarks folder.
|
| integer | (optional) index | |
| string | (optional) title | |
| string | (optional) url | |
|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function( [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) result) {...};`
| [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) | result | |
|---|---|---|
|
### move
Moves the specified BookmarkTreeNode to the provided location.
| Parameters |
|---|
| string | id | |
| object | destination |
| string | (optional) parentId | |
|---|---|---|
| integer | (optional) index | |
|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function( [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) result) {...};`
| [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) | result | |
|---|---|---|
|
### update
Updates the properties of a bookmark or folder. Specify only the properties that you want to change; unspecified properties will be left unchanged. **Note:** Currently, only 'title' and 'url' are supported.
| Parameters |
|---|
| string | id | |
| object | changes |
| string | (optional) title | |
|---|---|---|
| string | (optional) url | |
|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function( [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) result) {...};`
| [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) | result | |
|---|---|---|
|
### remove
`whale.bookmarks.remove(string id, function callback)`
Removes a bookmark or an empty bookmark folder.
| Parameters |
|---|
| string | id | |
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function() {...};` |
### removeTree
## Events
`whale.bookmarks.removeTree(string id, function callback)`
Recursively removes a bookmark folder.
| Parameters |
|---|
| string | id | |
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function() {...};` |
### onCreated
Fired when a bookmark or folder is created.
#### addListener
`whale.bookmarks.onCreated.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(string id, [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) bookmark) {...};`
| string | id | |
|---|---|---|
| [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) | bookmark | |
|
### onRemoved
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.
#### addListener
`whale.bookmarks.onRemoved.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(string id, object removeInfo) {...};`
| string | id | |
|---|---|---|
| object | removeInfo |
| string | parentId | |
|---|---|---|
| integer | index | |
| [BookmarkTreeNode](/extensions/bookmarks#type-BookmarkTreeNode) | node |
Since Chrome 48.
|
|
|
### onChanged
Fired when a bookmark or folder changes. **Note:** Currently, only title and url changes trigger this.
#### addListener
`whale.bookmarks.onChanged.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(string id, object changeInfo) {...};`
| string | id | |
|---|---|---|
| object | changeInfo |
| string | title | |
|---|---|---|
| string | (optional) url | |
|
|
### onMoved
Fired when a bookmark or folder is moved to a different parent folder.
#### addListener
`whale.bookmarks.onMoved.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(string id, object moveInfo) {...};`
| string | id | |
|---|---|---|
| object | moveInfo |
| string | parentId | |
|---|---|---|
| integer | index | |
| string | oldParentId | |
| integer | oldIndex | |
|
|
### onChildrenReordered
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().
#### addListener
`whale.bookmarks.onChildrenReordered.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(string id, object reorderInfo) {...};`
| string | id | |
|---|---|---|
| object | reorderInfo |
| array of string | childIds | |
|---|---|---|
|
|
### onImportBegan
Fired when a bookmark import session is begun. Expensive observers should ignore onCreated updates until onImportEnded is fired. Observers should still handle other notifications immediately.
#### addListener
`whale.bookmarks.onImportBegan.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function() {...};` |
### onImportEnded
Fired when a bookmark import session is ended.
#### addListener
`whale.bookmarks.onImportEnded.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function() {...};` |