Firefox/Projects/PlacesQueryAPIRedesign

Summary

Create a sensible, easy to use Query API for Places for Firefox 3.7/4.0

Current Status

Beginning stages - examining faaborg's mockups and blogposts

Next Steps

• Figure out if we are going to ride on top of the existing query API or not. The main goal is a sensible api.

Related Bugs

bug 522572

Team

• API: ddahl + places team
• UX/UI: faaborg
• Llama wrangling: dolske

Designs

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/

Idea Dump

Places Query Api Redesign

Priciples:
 1. Query API redesign is for the new direction/design of Places for Fx 3.7 +
 2. This design should not take into account existing Places implementation

Design in a nutshell:

  // 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){ //iterate results object } 
             };

  // 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 onResult 
  // fire the UI callback, with the results chunk

Use Cases

Location Bar bookmarks navigation:
  screenshot: people.mozilla.com/~faaborg/files/20091012-personalWeb/bookmarksLocationBar-i1.png

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

    retrun true;
  }

  // Anatomy of a (bookmark folder) 'Item':
  
  { 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
  }
  
  // Anatomy of a (history) 'Item':
  
  { 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
  }

2. Location Bar History Ranges

 screenshot: people.mozilla.com/~faaborg/files/20091012-personalWeb/historyLocationBar-i1.png

 // taken the above 'default' query object, we add a historyRange property: 
 query.historyRangeKeyword = 'Today';
 
 // - or -
 query.historyRangeFrom = new Date();
 query.historyRangeTo = new Date();  

 // optionally, we can pre-filter the results with a keyword
 query.param = 'news';
 
 // feed the query object into the Places QueryProcessor
 var qResultObj = new QueryProcessor(query);

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 3.7
• 'Pluggable' results handling
• Focus on JS usage

Non Goals

• Tailoring the API to tree views
• Creating the perfect API (lets iterate)
• Intended as a snap-in replacement of the current API