Firefox/Projects/PlacesQueryAPIRedesign: Difference between revisions

Jump to navigation Jump to search

Firefox/Projects/PlacesQueryAPIRedesign (view source)

Revision as of 01:21, 7 November 2009

5,710 bytes removed ,  7 November 2009
no edit summary
No edit summary
Line 19: Line 19:
*'''API''': ddahl + places team
*'''API''': ddahl + places team
*'''UX/UI''': faaborg
*'''UX/UI''': faaborg
*'''Llama wrangling''': dolske


== Designs ==
== Designs ==
The initial API "sketches" are here: [https://wiki.mozilla.org/Firefox/Projects/PlacesQueryAPISketches]


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/
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/
== 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>


== Goals/Use Cases ==
== Goals/Use Cases ==
Ddahl
564

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/181372"

Navigation menu