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.find({phrase: "Groucho Marx", 
                     where: "history"}, callback);

jetpack.places.find({phrase: "Groucho Marx", 
                     where:"bookmarks"}, callback)

// Write to the database

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

// results is an iterator-like object with a count property

function callback(results) {

  dump(results.length); // 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[1].title = "Groucho, we hardly knew ye!";

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

}

jetpack.places.find({ where: "bookmarks", phrase: "mustache"}, callback);

Full Example

//
//
// an example jetpack using the places API
// if the title of the contentDocument contains the word 'foo' always bookmark it
jetpack.future.import("places");

function titleParse(doc) {
  let title = doc.title.split();
  for (let idx in title) {
    if (title[idx] === 'foo'){
      jetpack.tabs.current.bookmark({tags:['foo', 'jetpack-auto-tag']});
      break;
    }
  }

  // lets alert the user - tell them how many bookmarks we have with 'foo':

  function callback(results) {
    alert("You have " + results.count + " bookmarks where the title contains 'foo'! Very Nice!");
  }

  jetpack.places.fetch({where: 'bookmarks', phrase: 'foo', tags: ['foo']}, callback);

}

jetpack.tabs.onReady( titleParse );