-
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)
-
Phase 2
- Provide easy to use API for CRUD, querying History and Bookmarks (nice to have)
Integration with awesomebar?
- How are keywords used?
- Should Folder/Bookmark constructor also take just an ID instead of options so we can retrieve IDs from queries and create new Bookmark/Folder objects to return? May be too heavy.
- Should Backup/Restore be implemented? backup/restore
Bookmark contains static methods to create, update and manipulate BookmarkItem
objects.
- @param {Object} properties
- @return {BookmarkItem}
Takes an object of properties, or an array of objects and returns a BookmarkItem
object. This object is not yet synced with the user's bookmarks.
While I like accepting both a folder ID and BookmarkItem object as a parent, if the parent is not yet created, we wouldn't be able to store the ID immediately. This has a side effect of the property being stored differently for different instances, rather than converting on construction.
-
String name
: 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) -
String type
: The type of bookmark item. Can befolder
,bookmark
, orseparator
. (Default: 'bookmark')
let { create } = require('bookmark');
var properties = {
title: 'Mozilla',
url: 'http://www.mozilla.org'
};
var bookmark = create(properties)
- @param {BookmarkItem|Array} items
- @param {Function=} callback
- @return {Promise}
let { save } = require('bookmarks');
let folder = create(…);
let itemA = create({ parent: folder, … });
let itemB; // Assume this was from a query, exists
// First, update itemB's url,
// and an example of using callbacks
itemB.url = 'http://bar';
update(itemB, function (err) {
if (!err) { console.log('success'); }
next();
});
// this would either need to do a full overwrite of
// the real bookmark's properties, or query each property
// to check if it should change
// After we updated itemB's url, now let's
// change both titles just for user confusion.
function next () {
itemA.title = itemB.title = "A new title";
// Can use promises, and pass in an array of
// items to be updated
update([itemA, itemB]).then(handleSuccess, handleFailure);
// ^^^ what happens here is since itemA's parent,
// `folder` does not yet exist, it'll save that first
// behind the scenes and then create/save itemA.
// itemB will be saved at some point in parallel.
//
// When both itemA and itemB have been updated,
// the returned promise will be resolved
}
- @param {BookmarkItem} item
- @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 {BookmarkItem} item
- @param {Function=} callback
- @return {Promise}
Removes all children from a BookmarkItem of 'folder'
type.
- @param {BookmarkItem} item
- @param {String|Array} tag
- @param {Function=} callback
- @return {Promise}
Adds tag/s to bookmark item (adds tags to all bookmarks that share this URI)
- @param {BookmarkItem} item
- @param {String|Array} tag
- @param {Function=} callback
- @return {Promise}
Removes tag/s from bookmark (removes tags from all bookmarks that share this URI)
- @param {String|URL} url
- @param {Function=} callback
- @return {Promise}
- @param {String|URL} url
- @param {Function=} callback
- @return {Promise}
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
dateAdded
name
isReadOnly
index
name
url
parent
type
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.
Need to make async
-
void Tags.tag(String|URL url, String|Array tags)
Tagsurl
withtags
-
void Tags.untag(String|URL url, String|Array tags)
Removestags
fromurl
-
[String] Tags.getURLsWithTag(String tag)
Returns an array of URLs that are tagged withtag
-
[String] Tags.getTagsFromURL(String|URL url)
Returns an array of tags that matchurl
var { Tags } = require('sdk/places/tags');
var url = 'http://mozilla.com';
Tags.tag(url, ['mozilla', 'javascript', 'jetpacks']);
Tags.untag(url, 'javascript');
Tags.getURLsWithTag('mozilla'); // ['http://mozilla.com']
Tags.getTagsFromURL(url); // ['mozilla', 'jetpacks']