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

Places API JEP

Jump to bottom
jsantell edited this page Mar 26, 2013 · 7 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 (must have)
    • Hook Bookmark instances to platform observers
  • Phase 2
    • Provide easy to use API for CRUD, querying History and Bookmarks (nice to have)
  • ~~Integration with awesomebar? ~~

Questions/Concerns

  • Goals?
  • How are keywords used?
  • Think about how events will hook into Folder/Bookmark via UI, and also from addon nsINavBookmarkObserver
  • Separater support?
  • 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

Bookmarks

Bookmarks contains classes for Bookmark and Folder.

Class

Constructor
constructor Bookmark(Object options)

Instantiates a new Bookmark. options can take the following arguments:

  • name: required The name of the bookmark
  • url: required the url (either as a String or URL instance)
  • parent: The parent folder where the bookmark should live. Takes either a Folder instance, or a constant of the Folder object.
  • index: The position of the Folder within its parent. Defaults to -1, the last position. (Default: -1)
Methods
  • remove() docs
  • move(index, [parent]) Can just change index, or index and parent docs
  • addTag(String|Array tag) Adds tag/s to bookmark (adds tags to all bookmarks that share this URI)
  • removeTag(String|Array tag) Removes tag/s from bookmark (removes tags from all bookmarks that share this URI)
Properties
  • id
  • dateAdded
  • name (get/setable)
  • isReadOnly (get/setable)
  • index (get/setable)

Functions

  • Bookmark.getBookmarksByURL(String|URL url)
  • Bookmark.isBookmarked(String|URL url)

Folders

Bookmarks contains classes for Bookmark and Folder -- separate here for documentation purposes.

Class

Constructor
constructor Folder(Object options)

Instantiates a new Folder. options can take the following arguments:

  • name: required The name of the folder
  • parent: The parent folder where the parent lives. Takes either another Folder instance, or a default folder constant on Folder. (Default: Menu Folder))
  • index: The position of the Folder within its parent. Defaults to -1, the last position. (Default: -1)
Methods
  • remove() docs
  • move(parent, index) docs
  • removeAllChildren() docs
Properties
  • id
  • name (get/setable)
  • index (get/setable)

Properties

These constants store the IDs of default folders and are used in other methods in Folder and Bookmark

  • Folder.MENU
  • Folder.PLACES
  • Folder.TAGS
  • Folder.TOOLBAR
  • Folder.UNSORTED

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

  • void Tags.tag(String|URL url, String|Array tags) Tags url with tags

  • void Tags.untag(String|URL url, String|Array tags) Removes tags from url

  • [String] Tags.getURLsWithTag(String tag) Returns an array of URLs that are tagged with tag

  • [String] Tags.getTagsFromURL(String|URL url) Returns an array of tags that match url

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']

History

Resources

Clone this wiki locally