-
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'
})
})
})
- @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
})
- @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');
})
- @param {Folder|Array} folder
- @param {Function=} callback
- @return {Promise}
Removes all children from a Folder
, also takes an array of folders.
- @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) {
});
- @param {String|Array} urls
- @param {Function=} callback
- @return {Promise}
Returns a promise that resolves to an array of Bookmark
s.
- @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
.
- @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.
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
-
id
readonly index
title
url
parent
-
id
readonly index
title
parent
-
readonly
(should this be implemented?)
-
id
readonly index
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.
Tags url
with tags
- @param {String|URL} url
- @param {String|Array} tags
- @param {Function=} callback
- @return {Promise}
Removes tags
from url
- @param {String|URL} url
- @param {String|Array} tags
- @param {Function=} callback
- @return {Promise}
Returns an array of URLs that are tagged with tag
- @param {String|Array} tags
- @param {Function=} callback
- @return {Promise}
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'];
});