-
Notifications
You must be signed in to change notification settings - Fork 263
JEP Places API
An API for Firefox Places (History and Bookmarks).
-
Phase 1
- Provide easy to use API for CRUD, querying, and tagging behaviour for bookmarks, folders, separaters (must have)
- Hook Bookmark instances to platform observers (nsINavBookmarkObserver)
- Provide easy to use API for CRUD, querying History and Bookmarks (nice to have)
- How are keywords used?
- Should we have node-style callbacks when using the optional callback parameter instead of promises?
function (err, res) {}
- Should Backup/Restore be implemented? backup/restore
Bookmark contains static methods to create, update and manipulate bookmark items like bookmarks, folders and separators.
- @param {Object} properties
- @param {Function=} callback
- @return {Promise}
Takes an object of properties, or an array of objects and returns a a promise for a Bookmark
object. Upon creation, the item makes an asynchronous saves.
-
String title
: required The name of the bookmark -
String|URL url
: required the url (either as aString
orURL
instance) -
BookmarkItem|Number parent
: The ID of the parent folder where the bookmark should live. (Default: ID of the menu folder) -
Number index
: The position of the Folder within its parent. Defaults to the last position. (Default: -1)
let { createBookmark } = require('bookmark');
createBookmark({
title: 'Mozilla',
url: 'http://www.mozilla.org
}).then(function (bookmark) {
})
- @param {Object} properties
- @param {Function=} callback
- @return {Promise}
Takes an object of properties, or an array of objects and returns a a promise for a Folder
object. Upon creation, the item makes an asynchronous saves.
-
String title
: required The name of the bookmark -
BookmarkItem|Number parent
: The ID of the parent folder where the bookmark should live. (Default: ID of the menu folder) -
Number index
: The position of the Folder within its parent. Defaults to the last position. (Default: -1)
- @param {Object} properties
- @param {Function=} callback
- @return {Promise}
Takes an object of properties, or an array of objects and returns a a promise for a Separator
object. Upon creation, the item makes an asynchronous saves.
-
BookmarkItem|Number parent
: The ID of the parent folder where the separator should live. (Default: ID of the menu folder) -
Number index
: The position of the Folder within its parent. Defaults to the last position. (Default: -1)
- @param {Bookmark|Folder|Separator|Array} items
- @param {Function=} callback
- @return {Promise}
Pushes properties of items
to their platform counterparts -- returns a promise that resolves to instances of these items upon saving.
let { save } = require('bookmarks');
createFolder(…).then(function (folder) {
createBookmark({ url: 'http://foo', parent: folder, … })
.then(function (bookmark) {
// Now update bookmark's url to 'http://bar'
bookmark.url = 'http://bar';
save(bookmark).then(function (bm) {
// Now the bookmark on the platform
// has been updated with url 'http://bar'
})
})
})
##### update(items, [callback])
* @param {Bookmark|Folder|Separator|Array} items
* @param {Function=} callback
* @return {Promise}
**THIS NEEDS A BETTER NAME?**
Updating `items` refreshes the properties of the instance with the most up-to-date properties from the host. Returns a promise that resolves to the instances upon completion.
let { update } = require('bookmarks');
let bookmark; createBookmark(…).then(function (bm) { // We store the saved bookmark and use it later down the road… bookmark = bm; });
// ..later..
// We update bookmark
because another addon or
// the user could've changed it
update(bookmark).then(function (bm) {
// Now the properties of bookmark
are updated
// if there were any changes
})
##### remove(item, [callback])
* @param {Bookmark|Folder|Separator|Array} items
* @param {Function=} callback
* @return {Promise}
Removes the platform's bookmark based off of `item`'s ID.
let { remove } = require('bookmark');
let item = someQueryReturningAnItem();
remove(item).then(function () { console.log('removed'); })
##### removeChildren(item, [callback])
* @param {Folder|Array} folder
* @param {Function=} callback
* @return {Promise}
Removes all children from a `Folder`, also takes an array of folders.
##### getChildren(item, [callback])
* @param {Folder} folder
* @param {Function=} callback
* @return {Promise}
Get all children from a `Folder`, or array of `Folder`s.
let { getChildren } = require('bookmark');
getChildren(folder).then(function (children) {
});
##### getBookmarksByURL(urls, [callback])
* @param {String|Array} urls
* @param {Function=} callback
* @return {Promise}
Returns a promise that resolves to an array of `Bookmark`s.
##### getBookmarksByTag(tag, [callback])
* @param {String|Array} tag
* @param {Function=} callback
* @return {Promise}
Returns a promise that resolves to an array of `Bookmark`s that have been tagged with `tag`.
##### isBookmarked(url, [callback])
* @param {String|URL} url
* @param {Function=} callback
* @return {Promise}
Returns a promise that resolves to a boolean indicating whether or not the URL has been bookmarked.
#### Properties
These constants store the IDs of default folders and are used in other methods in `Folder` and `Bookmark`
* `Bookmark.MENU`
* `Bookmark.PLACES`
* `Bookmark.TAGS`
* `Bookmark.TOOLBAR`
* `Bookmark.UNSORTED`
#### Bookmark Class
##### Properties
* `id` *readonly*
* `index`
* `title`
* `url`
* `parent`
#### Folder Class
##### Properties
* `id` *readonly*
* `index`
* `title`
* `parent`
* `readonly` (should this be implemented?)
#### Separator Class
##### Properties
* `id` *readonly*
* `index`
### Tags
Tags are URL based, so if several bookmarks of `http://mozilla.com` exist, adding a tag of `moz` to this URL would add it to all bookmarks with that URL. This can be a utility to be used standalone for querying/editing tags, and also used within the **Bookmarks** module to tag bookmarks.
#### Functions
##### tag(url, tags, [callback])
Tags `url` with `tags`
* @param {String|URL} url
* @param {String|Array} tags
* @param {Function=} callback
* @return {Promise}
##### untag(url, tags, [callback])
Removes `tags` from `url`
* @param {String|URL} url
* @param {String|Array} tags
* @param {Function=} callback
* @return {Promise}
##### getURLsWithTag(tag, [callback])
Returns an array of URLs that are tagged with `tag`
* @param {String|Array} tags
* @param {Function=} callback
* @return {Promise}
##### getTagsFromURL(url, [callback])
Returns an array of tags that match `url`
* @param {String|URL|Array} url
* @param {Function=} callback
* @return {Promise}
var { Tags } = require('sdk/places/tags'); var url = 'http://mozilla.com';
Tags.tag(url, ['mozilla', 'javascript', 'jetpacks']) .then(Tags.untag(url, 'javascript')) .then(Tags.getURLsWithTag('mozilla')) .then(function (val) { val; // ['http://mozilla.com'] return Tags.getTagsFromURL(url); }) .then(function (val) { val; // ['mozilla', 'jetpacks']; });
### History
## Resources
* [Places Developer Guide](https://developer.mozilla.org/en-US/docs/Places_Developer_Guide)
* Bookmarks
* [nsINavBookmarksService [docs]](https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/nsINavBookmarksService)
* [Manipulating Bookmarks Using Places](https://developer.mozilla.org/en-US/docs/Manipulating_bookmarks_using_Places)
* History
* [nsINavHistoryService [docs]](https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/nsINavHistoryService)
* [nsIGlobalHistory2 [docs]](https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/nsIGlobalHistory2)
* [nsIBrowserHistory [docs]](https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/nsIBrowserHistory)
* [mozIAsyncHistory [docs]](https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/mozIAsyncHistory)
* [Using Places History Service](https://developer.mozilla.org/en-US/docs/Using_the_Places_history_service)
* [Original JEP 22, Places API](https://wiki.mozilla.org/Labs/Jetpack/JEP/22)
* [PlacesQueryAPIRedesign](https://wiki.mozilla.org/Firefox/Projects/PlacesQueryAPIRedesign)