564
edits
Changes
Created page with '== Places Query Api Redesign == === Priciples: === Query API redesign is for the new direction/design of Places for Fx 3.7 + This design should not take into account existing …'
== Places Query Api Redesign ==
=== Priciples: ===
Query API redesign is for the new direction/design of Places for Fx 3.7 +
This design should not take into account existing Places implementation
== Design in a nutshell: ==
<pre class="brush:js;">
// queryObj is an object that configures the current query
queryObj = { param:'cnn',
// the following 'bookmarks' and 'history' are not
// required, defaults are true for both
bookmarks:true, // search bookmarks - yes (default)
history:true, // search bookmarks - yes (default)
// UI Callback function
uiCallback: function (results){ // results is an Iterator }
};
// qResultObj is returned by the QueryProcessor and is
// an object that has a 'fetch' method used as a callback
// this object has parsed the queryObj, built the SQL,
// and contains an (optional) UI callback to update the UI.
// (all queries are performed asynchronously)
qResultObj = new QueryProcessor(queryObj);
qResultObj.fetch();
// fetch will trigger the search in the database and
// fire the UI callback, with the results chunked
</pre>
== Use Cases ==
Location Bar bookmarks navigation:
screenshot: [http://people.mozilla.com/~faaborg/files/20091012-personalWeb/bookmarksLocationBar-i1.png]
<pre class="brush:js;">
// set up defaults for the operations at hand:
var query = { bookmarks: true, history: true };
// add the string to search
query.param = 'Bill';
// optional UI callback registration:
function uiCallbk(results){
results.length // 1
for (let item in results) {
item.title; // 'Bills, Resolutions Libary of Congress'
item.url; // 'thomas.loc.gov/home/bills_res.html'
item.id; // 123897
item.path; // 'Bookmarks/Government'
...
}
}
query.uiCallback = uiCallbk;
// feed the query object into the Places QueryProcessor
var qResultObj = new QueryProcessor(query);
qResultObj.fetch; // function that returns an iterator, used as a callback
// Usage in the wild: 'caller()' is a consumer of the QueryProcessor
function caller(qResultObj) {
...
qResultObj.fetch(); // triggers async query and uiCallback
// fetch() will throw if anything goes awry
return true;
}
</pre>
== Anatomy of a (bookmark folder) 'Item': ==
<pre class="brush:js;">
{ title: 'Bills',
url: 'bookmark://Apartment/Bills'
path: 'Bookmarks/Apartment/Bills',
node: 'folder',
id: 34678,
type: 'bookmark',
children: (property), // returns a resultTree or
// Iterator of top-level siblings
silblings: (property), // returns Iterator Obj
siblingCount (property) // returns Number
parent: (property), // returns Item
lastVisit: '2009-11-04 12:00:01',
firstVist: '2009-10-31 15:00:23',
visits: (property), // returns ordered list of visitItems
icon: (property), // returns faviconItem object
}
</pre>
== Anatomy of a (history) 'Item': ==
<pre class="brush:js;">
{ title: "Hurricane Bill's winds weaken",
url: 'news.yahoo.com/s/ap/...'
path: 'news.yahoo.com/s/ap/...',
node: 'item',
id: 34678,
type: 'history',
children: null,
silblings: null,
siblingCount: null,
parent: null,
lastVisit: '2009-11-04 12:00:01',
firstVist: '2009-10-31 15:00:23',
visits: (property) // returns ordered list of 'visitItem' objects
}
</pre>
== Location Bar History Ranges ==
screenshot: [http://people.mozilla.com/~faaborg/files/20091012-personalWeb/historyLocationBar-i1.png]
<pre class="brush:js;">
// taken the above 'default' query object, we add a historyRange property:
query.historyRangeKeyword = 'Today';
// also, phrases like: 'Last Week', 'This Month', 'Last Year', etc...
// - or -
// (in reality, these are the internally-called methods to
// handle the parsed 'historyRangeKeyword')
query.historyRangeFrom = new Date();
query.historyRangeTo = new Date();
// optionally, we can filter the results with a keyword
query.param = 'news';
query.uiCallback = function (results){
for (let item in results.next()){
displayInUserInterface(item);
}
};
// perhaps we have a negative filter as well:
query.exclude = 'cnn';
// feed the query object into the Places QueryProcessor
var qResultObj = new QueryProcessor(query);
// here it is in the wild:
function caller(qResultObj) {
qResultObj.fetch();
return true;
}
</pre>
== Faceted Searches - Perhaps this is for '4.0'? ==
<pre class="brush:js;">
// I have seen faceted search apis that do things like:
qResultObj.narrow({referrer:'mozilla.com'});
qResultObj.fetch();
// the 'narrow' call will return a new qResultObject that
// can be narrowed futher:
qResultObj.narrow({ year:2009 });
qResultObj.narrow({ tagged:'News' });
qResultObj.narrow({ month:11 });
qResultObj.widen('month', 'year');
qResultObj.widen(); // removes all facets
// What are all of the facets?
//
// times, dates, referringDomain, referringFragment, isBookmarked,
// inTraversal, tagged
//
// 'inTraversal' is any historyItem or bookmark in the traversed path
// that was taken to get to the target url/bookmark
//
// 'inTraversal' will require that we store a more comprehensive
// "browsing path" data
</pre>
=== Priciples: ===
Query API redesign is for the new direction/design of Places for Fx 3.7 +
This design should not take into account existing Places implementation
== Design in a nutshell: ==
<pre class="brush:js;">
// queryObj is an object that configures the current query
queryObj = { param:'cnn',
// the following 'bookmarks' and 'history' are not
// required, defaults are true for both
bookmarks:true, // search bookmarks - yes (default)
history:true, // search bookmarks - yes (default)
// UI Callback function
uiCallback: function (results){ // results is an Iterator }
};
// qResultObj is returned by the QueryProcessor and is
// an object that has a 'fetch' method used as a callback
// this object has parsed the queryObj, built the SQL,
// and contains an (optional) UI callback to update the UI.
// (all queries are performed asynchronously)
qResultObj = new QueryProcessor(queryObj);
qResultObj.fetch();
// fetch will trigger the search in the database and
// fire the UI callback, with the results chunked
</pre>
== Use Cases ==
Location Bar bookmarks navigation:
screenshot: [http://people.mozilla.com/~faaborg/files/20091012-personalWeb/bookmarksLocationBar-i1.png]
<pre class="brush:js;">
// set up defaults for the operations at hand:
var query = { bookmarks: true, history: true };
// add the string to search
query.param = 'Bill';
// optional UI callback registration:
function uiCallbk(results){
results.length // 1
for (let item in results) {
item.title; // 'Bills, Resolutions Libary of Congress'
item.url; // 'thomas.loc.gov/home/bills_res.html'
item.id; // 123897
item.path; // 'Bookmarks/Government'
...
}
}
query.uiCallback = uiCallbk;
// feed the query object into the Places QueryProcessor
var qResultObj = new QueryProcessor(query);
qResultObj.fetch; // function that returns an iterator, used as a callback
// Usage in the wild: 'caller()' is a consumer of the QueryProcessor
function caller(qResultObj) {
...
qResultObj.fetch(); // triggers async query and uiCallback
// fetch() will throw if anything goes awry
return true;
}
</pre>
== Anatomy of a (bookmark folder) 'Item': ==
<pre class="brush:js;">
{ title: 'Bills',
url: 'bookmark://Apartment/Bills'
path: 'Bookmarks/Apartment/Bills',
node: 'folder',
id: 34678,
type: 'bookmark',
children: (property), // returns a resultTree or
// Iterator of top-level siblings
silblings: (property), // returns Iterator Obj
siblingCount (property) // returns Number
parent: (property), // returns Item
lastVisit: '2009-11-04 12:00:01',
firstVist: '2009-10-31 15:00:23',
visits: (property), // returns ordered list of visitItems
icon: (property), // returns faviconItem object
}
</pre>
== Anatomy of a (history) 'Item': ==
<pre class="brush:js;">
{ title: "Hurricane Bill's winds weaken",
url: 'news.yahoo.com/s/ap/...'
path: 'news.yahoo.com/s/ap/...',
node: 'item',
id: 34678,
type: 'history',
children: null,
silblings: null,
siblingCount: null,
parent: null,
lastVisit: '2009-11-04 12:00:01',
firstVist: '2009-10-31 15:00:23',
visits: (property) // returns ordered list of 'visitItem' objects
}
</pre>
== Location Bar History Ranges ==
screenshot: [http://people.mozilla.com/~faaborg/files/20091012-personalWeb/historyLocationBar-i1.png]
<pre class="brush:js;">
// taken the above 'default' query object, we add a historyRange property:
query.historyRangeKeyword = 'Today';
// also, phrases like: 'Last Week', 'This Month', 'Last Year', etc...
// - or -
// (in reality, these are the internally-called methods to
// handle the parsed 'historyRangeKeyword')
query.historyRangeFrom = new Date();
query.historyRangeTo = new Date();
// optionally, we can filter the results with a keyword
query.param = 'news';
query.uiCallback = function (results){
for (let item in results.next()){
displayInUserInterface(item);
}
};
// perhaps we have a negative filter as well:
query.exclude = 'cnn';
// feed the query object into the Places QueryProcessor
var qResultObj = new QueryProcessor(query);
// here it is in the wild:
function caller(qResultObj) {
qResultObj.fetch();
return true;
}
</pre>
== Faceted Searches - Perhaps this is for '4.0'? ==
<pre class="brush:js;">
// I have seen faceted search apis that do things like:
qResultObj.narrow({referrer:'mozilla.com'});
qResultObj.fetch();
// the 'narrow' call will return a new qResultObject that
// can be narrowed futher:
qResultObj.narrow({ year:2009 });
qResultObj.narrow({ tagged:'News' });
qResultObj.narrow({ month:11 });
qResultObj.widen('month', 'year');
qResultObj.widen(); // removes all facets
// What are all of the facets?
//
// times, dates, referringDomain, referringFragment, isBookmarked,
// inTraversal, tagged
//
// 'inTraversal' is any historyItem or bookmark in the traversed path
// that was taken to get to the target url/bookmark
//
// 'inTraversal' will require that we store a more comprehensive
// "browsing path" data
</pre>
