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

However, this initial inplementation is still using the synchronous places API. the Async implementation is being written in parallel.

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.places.bookmark.create({url: document.location, title: document.title, 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.find({where: 'bookmarks', phrase: 'foo'}, callback);

}

jetpack.tabs.onReady( titleParse );