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);

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']});
    }
  }
  // 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 );