Labs/Jetpack/Reboot/JEP/114: Difference between revisions

From MozillaWiki
< Labs‎ | Jetpack‎ | Reboot‎ | JEP
Jump to navigation Jump to search
No edit summary
Line 43: Line 43:


=== Examples ===
=== Examples ===
'''Get module'''
<pre class="brush:js;toolbar:false;">
var places = require("places");
</pre>
'''Get module'''
<pre class="brush:js;toolbar:false;">
var places = require("places");
</pre>
'''Filter history'''
<pre class="brush:js;toolbar:false;">
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);
</pre>
'''Filter bookmarks'''
<pre class="brush:js;toolbar:false;">
places.history.filter({ phrase: "search words" }, callbackFunc, callbackScope);
</pre>
'''Filter pages'''
<pre class="brush:js;toolbar:false;">
places.filter({ phrase: "search words" }, callbackFunc, callbackScope);
</pre>
'''Clear history'''
<pre class="brush:js;toolbar:false;">
places.history.remove(callbackFunc, callbackScope);
</pre>
'''Remove pages from history'''
<pre class="brush:js;toolbar:false;">
places.history.filter({ host: "remove.host.com" })
              .remove(callbackFunc, callbackScope);
</pre>

Revision as of 13:47, 14 May 2010

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.
  • 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

Get module

var places = require("places");

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