Firefox/Projects/PlacesQueryAPIRedesign
Jump to navigation
Jump to search
Places Query API
Create a sensible, easy to use Query API for Places for Firefox.next & Jetpack. This API should make it possible to do targeted queries against history and bookmarks with a minimum of code.
Goals/Use Cases
- An elegant and easy to use API. Fx devs, Jetpack and extension developers will all benefit.
- allows us to prototype the new ui for Fx.next
'Pluggable' results handlingEasy wrappable querying object and results- Focus on JS usage
Paging Support - Sounds like a great use of Generators!dropped, there is no perf gain, can be a follow-up- Fetch individual record by Id or other property
(After talking to the Labs guys about Weave, we should try to provide a plugin-interface whereby you can allow a developer to keep track of and index random JSON objects.
Dan Mills has example code that was created for the people store. Link coming soon.)
Non Goals
- Tailoring the API to tree views
- Creating the perfect API (lets iterate)
- Create an abstract datastore
Intended as a snap-in replacement of the current APIFuture follow-up through a live-updating wrapper- Wrap current sync and XPCOM API
Status
- Old prototype landed in Jetpack 0.8, currently being revised
- Team
- API: ddahl, mak
- UX/UI: not required so far, future users could though
- Implementation bugs: bug 522572 bug 545700 bug 531940 bug 543888
- Next Steps
- Iterate the feel of the API with the Places team and other interested developers. Ideas and feedback are encouraged. Build working examples to encourage feedback.
Timeline / Milestones
- 2010/02 Landed in Jetpack 0.8
- 2010/03 Work on "skeleton" API design with Marco
- 2010/05 New redesign, collecting feedback and proceeding.
Delivery Requirements
- This is purely additive.
- Coordination with Jetpack as this should be coded once, checked into places and imported into Jetpack's implementation.
Constraints
- Final implementation should use only Async Storage APIs
Dependencies
Testing
- Comprehensive xpcshell tests
Example/Documentation style Browser Chrome testsNot for now, when treeviews will use this.- TDD
Related Projects
- Jetpack
Additional Details
The initial API "sketches" are here: [1]
Faaborg has been mocking up designs and putting a lot pf thought into the UX: http://blog.mozilla.com/faaborg/2009/10/13/browsing-your-personal-web
Inspiration
Links to code we should study...
Gloda
Gloda: [2]
facet.js: [3]
Gloda Fundamental Attribute provider: [4]
Explicit Attribute Provider: [5]
FacetView: [6]
Current Sketches
function callback(results) {
// results is a simple array of ResultItem, it's pretty easy to wrap it
// if more complex management is needed.
if (results.length == 0)
dump("En empty results array indicates last results push\n");
else
dump("Collected " + results.length + " results this turn\n");
}
// Results are pushed to the callback as soon as they are available.
new PlacesQuery([object]QueryConf, [function]callback, [scope]thisObject);
// It's possible to pass multiple QueryConf objects, results will be merged
// based on the .merge attribute of each config.
// First query results are always unioned.
// In case of multiple queries, sort, group and limit of the first query will
// be used for the global result.
new PlacesQuery([QueryConf1, QueryConf2], callback, thisObject);
// It's possible to create the query, but run it later.
let query = new PlacesQuery(QueryConf);
query.execute(callback, thisObject);
//The query can be so configured:
QueryConf = {
phrase: string.
Show only pages containing this string in either title, uri or
tags. Case insensitive. Can use ^ and $ to match beginning or
end.
host: string.
Show only pages containing this string in the host. Case
insensitive. Can use ^ and $ to match beginning or end.
uri: string.
Show only pages containing this string in the uri. Case
insensitive. Can use ^ and $ to match beginning or end.
annotated: array of strings.
Show only pages with these annotations (Either page or item).
bookmarked: object {
tags: array of strings.
Show only pages tagged with these tags.
folders: array of numbers.
Show contents of these folders. (non-recursive)
items: array of numbers.
Show only these items.
when: array of 2 Date objects.
Show only bookmarks created between these times.
Can use null beginning or end time to match till epoch
or now.
modified: array of 2 Date objects.
Show only bookmarks modified between these times.
Can use null beginning or end time to match till
epoch or now.
excludeNonContainers: boolean.
Removes any non-container from results.
Default is false.
excludeReadOnlyContainers: boolean.
Removes read only containers from
results. Default is false.
}
visited: object {
howMany: array of numbers.
Show only pages with these so many visits.
Can use null minimum or maximum to match anything.
transitions: array fo transition types.
Show only pages with at least one visit with these
transitions.
when: array of 2 Date objects.
Show only pages with visits between these times.
Can use null beginning or end time to match till epoch
or now.
excludeRedirectsSources: boolean.
Removes redirects sources from results.
Default is false.
excludeRedirectsTargets: boolean.
Removes redirects targets from results.
Default is false.
includeHiddenPages: boolean.
Returns also pages marked as hidden.
Default is false.
includeVisits: boolean.
Returns all visits.
Default is false, that means visits are grouped
by uri, and no duplicates are returned.
}
sort: object {
by: string.
Either "none", "title", "time", "uri", "accessCount" or
"lastModified", "frecency". Defaults to "none".
dir: string.
Either "asc" or "desc". Defaults to "asc".
}
group: string.
Either "tags", "folders", "day", "month", "year" or "domain".
Defaults to "none".
limit: number.
Maximum umber of results to return. Defaults to all results.
merge: string.
How to merge this query's results with others in the same request.
Either "union", "intersect" or "except".
}