Labs/Jetpack/JEP/22

JEP 22 - Places API

• Champion: David Dahl <ddahl at mozilla dot com>
• Status: Planning
• Type: API Track
• Created: 27 July 2009
• Reference Implementation: jetpack.places
• JEP Index

Introduction and Rationale

The Places API will provide Jetpack developers the ability to search bookmarks and history as well as add/edit/remove/tag bookmarks.

The plan is to make this Jetpack api ride on top of a new QueryApi for Places, which is being worked on in bug 522572: [1]

Proposal

Hide all of the muckety muck of Places "Query API" inside of an easy to use Jetpack API.

jetpack.places.find("Groucho Marx")

jetpack.places.find({term: "Groucho Marx", where:"history", since: "2009-03-01 12:00:01"})

jetpack.places.find({term: "Groucho Marx", where:"history", before: "2008-12-31 00:00:01"})

jetpack.places.find({term: "Groucho Marx", where:"bookmarks", between: ["2009-03-01 12:00:01", "2009-04-01 12:00:03"]})

jetpack.places.bookmark() // bookmarks the current tab

var bookmarks = jetpack.places.find({term: "Groucho Marx", where:"bookmarks", between: ["2009-03-01 12:00:01", "2009-04-01 12:00:03"]})

// bookmarks is an iterator or generator-like object with length properties

dump(bookmarks.length) // 3

bookmarks[2].remove()

bookmarks[1].title = "Groucho, we hardly knew ye!"

bookmarks[1].tag("myhero") // auto saves tags

bookmarks[1].tags() // returns ["myhero", "mustachioed-funny-guys",]

bookmarks[1].save() // called to make the title change stick


var places_items = jetpack.places.find({ tags: ["marx-brothers"] })

// returns an array of placesItem objects