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 10, 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 `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)
Clone this wiki locally