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
Jordan Santell edited this page May 14, 2013 · 20 revisions

Places API JEP (WIP)

Overview

An API for Firefox Places (History and Bookmarks).

Current Hacking

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)
    • Provide easy to use API for CRUD, querying History and Bookmarks (nice to have)

Questions/Concerns

  • 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

Proposed API

Bookmark

Bookmark contains static methods to create, update and manipulate bookmark items like bookmarks, folders and separators.

Functions

createBookmark(Object properties, Function callback)
  • @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 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) 
let { createBookmark } = require('bookmark');

createBookmark({
	title: 'Mozilla',
	url: 'http://www.mozilla.org
}).then(function (bookmark) {
	
})
createFolder(Object properties, Function callback)
  • @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)
createSeparator(Object properties, Function callback)
  • @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)
save(items, [callback])
  • @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 Folders.

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 Bookmarks.

getBookmarksByTag(tag, [callback])
  • @param {String|Array} tag
  • @param {Function=} callback
  • @return {Promise}

Returns a promise that resolves to an array of Bookmarks 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

Clone this wiki locally