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

Updated: Modeling Jetpack Places API after the new Places Query API, see [2].

The entire new Places API will be *Asynchronous*. There is no getting around this. The existing Synchronous API willbe deprecated in Firefox 4.x

This means that anytime the results need to be iterated or consumed, a callback function is required. [This is optional]

// Read from the database

// 1. Create a UI callback function, if needed. [optional]

function callback(results){
  // iterate the results array-like object
  for (let item in results){
    insertItemIntoDom(results[item]);
  }
}

jetpack.places.fetch("Groucho Marx", callback);

// ^^ you can pass in a string or an object...

jetpack.places.fetch({phrase: "Groucho Marx", 
                     where: "history", 
                     since: "2009-03-01 12:00:01"}, callback);

jetpack.places.fetch({phrase: "Groucho Marx", 
                     where:"everywhere", 
                     before: "2008-12-31 00:00:01"}, callback)

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

// Write to the database

jetpack.places.bookmark(); // bookmarks the current tab
// perhaps we add this functionality to the 'current tab' object or all tabs

// results is an iterator-like object with length properties

function callback(results) {

  dump(results.count); // 3

  for (let item in results) {
    insertIntoDOM(results[item]); 
    // insertIntoDOM is defined by the developer to display the 
    // result item (bookmark or history object)
  }

  results[2].remove();

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

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

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

  results[1].save(); // called to make all changes permanent

}

jetpack.places.fetch({ where:bookmarks, 
                        tags: ["marx-brothers"] }, callback);