Confirmed users
595
edits
Labs/Jetpack/Reboot/JEP/114: Difference between revisions
→Open Issues
| (6 intermediate revisions by the same user not shown) | |||
| Line 14: | Line 14: | ||
We need to add methods to act on history and bookmarks (tags, annotations, icons...) other than just querying them. | 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 === | === Dependencies & Requirements === | ||
| Line 21: | Line 28: | ||
No UI is exposed. | No UI is exposed. | ||
== Capabilities Required (if applicable) == | === 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) == | === API Methods (if applicable) === | ||
See JEP 22: https://wiki.mozilla.org/Labs/Jetpack/JEP/22 | See JEP 22: https://wiki.mozilla.org/Labs/Jetpack/JEP/22 | ||
== Use Cases == | === 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''' | |||
<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> | |||
'''Remove bookmarks''' | |||
<pre class="brush:js;toolbar:false;"> | |||
places.bookmarks.filter({ bookmarked: { tags: ["removeme"] } }) | |||
.remove(callbackFunc, callbackScope); | |||
</pre> | |||
'''Annotations''' | |||
<pre class="brush:js;toolbar:false;"> | |||
// 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: [...] }); | |||
</pre> | |||
'''Bookmarks''' | |||
<pre class="brush:js;toolbar:false;"> | |||
// 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); | |||
</pre> | |||