Labs/Jetpack/Reboot/JEP/114

JEP 114 - Places

• Champions: David Dahl - ddahl <at> mozilla.com, Marco Bonardo - mak <at> mozilla.com
• Status: Rebooting
• Bug Ticket: bug 545700
• Type: API
• Difficulty: 2

Proposal

Elegant access to Places API, more javascript addicted (no crappy xpcom calls).

Key Issues

The filtering part is a relatively easy port since the initial prototype implementation is a .jsm that is built with attention to inputs and scope.

We need to add methods to act on history and bookmarks (tags, annotations, icons...) other than just querying them.

Open Issues

• Currently Places Query API is in alpha stage, needs to be finished.
• Which "observers" capabilities are required? Is it better to observe just a liveupdate result (in future) or all relevant changes to bookmarks and pages?
• The Query API does not act on temp tables for performance reasons, thus history results are cached on 2 minutes (this problem will go away as soon as we remove temp tables, that is targeted for FX4)
• Live updating results are not supported OOTB, these will come later as a wrapper around current Query API, and will most likely be exposed as .result(), similar to filter, but will return objects iteratable rather than simple static arrays.
• hiearchies management is still a bit in the clouds.

Dependencies & Requirements

New Places Query API bug 522572 https://wiki.mozilla.org/Firefox/Projects/PlacesQueryAPIRedesign

No UI is exposed.

Capabilities Required (if applicable)

• filter pages based on key details: title, uri, host, tags, annotations, bookmarked, visited.
• bookmarks management: create bookmarks, edit bookmarks, remove bookmarks, tags
• history management: remove pages from history
• annotations management: add/remove annotations

API Methods (if applicable)

See JEP 22: https://wiki.mozilla.org/Labs/Jetpack/JEP/22

Use Cases

Bookmark or tag multiple pages, tags manager, filtering interface, show slices of history or bookmarks, show visits graphs. Extract useful information from Places.

Examples

This is a selection of possibilities, changing filtering can achieve many more actions.

Get module

var places = require("places");

Filter history

function callbackFunc(results) {
  // results is an array of ResultItem objects.
  // a 0-length results indicates there are no more results.
}

// See PlacesQuery for description of the query configuration object.
places.history.filter({ host: "^www.moz" }, callbackFunc, callbackScope);

Filter bookmarks

places.history.filter({ phrase: "search words" }, callbackFunc, callbackScope);

Filter pages

places.filter({ phrase: "search words" }, callbackFunc, callbackScope);

Clear history

places.history.remove(callbackFunc, callbackScope);

Remove pages from history

places.history.filter({ host: "remove.host.com" })
              .remove(callbackFunc, callbackScope);

Remove bookmarks

places.bookmarks.filter({ bookmarked: { tags: ["removeme"] } })
                .remove(callbackFunc, callbackScope);

Annotations

// Add bookmark annotations. If the result is not required to be bookmarked,
// a page annotation is added instead.
places.bookmarks.filter({ uri: "^http://mozilla.org/annotateme/$" })
                .annotate([{ name: "annoToAdd", value: "annoValue" }],
                          myCallback, callbackScope);

// To remove an annotation omit value.
places.bookmarks.filter({ uri: "^http://mozilla.org/annotateme/$" })
                .annotate([{ name: "annoToAdd" }], myCallback, callbackScope);

// XXX to simplify this could just be .save({ annotations: [...] });

Bookmarks

// Add a bookmark.
places.bookmarks.save({ uri: "http://moz.org/"
                      , title: "a bookmark"
                      , parent: 3
                      , position: 12
                      }, myCallback, callbackScope);

// Edit a bookmark: set title, remove tag foo, add tag bar.
places.bookmarks.filter({ uri: "http://moz.org/"
                        , sort: { by: "time", dir: "desc" }
                        , limit: 1
                        }).save({ title: "a new title"
                                , tags: ["-foo", "bar"]
                                }, myCallback, callbackScope);