Skip to content
This repository has been archived by the owner on Feb 26, 2022. It is now read-only.

JEP Places API

Jump to bottom
jsantell edited this page Apr 18, 2013 · 20 revisions

Places API JEP (WIP)

Overview

An API for Firefox Places (History and Bookmarks).

Current Hacking

todo

  • More common use case examples
  • a 'before and after' example of a popular add-on moving from XPCOM to Jetpacks Places API

Goals

  • 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?

Questions/Concerns

  • 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

Proposed API

Bookmark

Bookmark contains static methods to create, update and manipulate BookmarkItem objects.

Functions

create(Object properties)
  • @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 a String or URL 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 be folder, bookmark, or separator. (Default: 'bookmark') 
let { create } = require('bookmark');

var properties = {
	title: 'Mozilla',
	url: 'http://www.mozilla.org'
};

var bookmark = create(properties)
save(items, [callback])
  • @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
}
remove(item, [callback])
  • @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');
})
removeAllChildren(item, [callback])
  • @param {BookmarkItem} item
  • @param {Function=} callback
  • @return {Promise}

Removes all children from a BookmarkItem of 'folder' type.

addTag(item, tag, [callback])
  • @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)

removeTag(item, tag, [callback])
  • @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)

getBookmarksByURL(url, [callback])
  • @param {String|URL} url
  • @param {Function=} callback
  • @return {Promise}
isBookmarked(url, [callback])
  • @param {String|URL} url
  • @param {Function=} callback
  • @return {Promise}

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

BookmarkItem Class

Properties
  • id
  • dateAdded
  • name
  • isReadOnly
  • index
  • name
  • url
  • parent
  • type

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} 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

Clone this wiki locally