Places:Design Overview: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
No edit summary
 
(14 intermediate revisions by the same user not shown)
Line 1: Line 1:
= Design Overview =
= Design Overview =


Implement a new back-end for Bookmarks, History and related components using the mozStorage wrapper for SQLite. Develop newer, more usable front-end components to display results, emphasizing simple search and categorization.
Places is designed to be a robust back-end for Bookmarks, History and related components using the mozStorage wrapper for SQLite. It is intended to provide useful APIs for a more usable front-end, emphasizing simple search and categorization.
 
Generally, you'll want to look at the [https://developer.mozilla.org/En/Places documentation on MDC] instead of what is here.  The documentation here is only internal API documentation that isn't generally exposed to add-on authors.


Related Documents:
Related Documents:


* [[Places:User Interface]]
* [[Places:URL Store]]
* [[Places:Bookmarks]]
* [[Places:place URIs]]
* [[Places:Results]]
* [[Places:Controller]]
* [[Browser History]]
* [[Places:AutoComplete]]
* [[Places:AutoComplete]]
* [[Places:Transactions]]
* [[Places:Drag & Drop]]
* [[Places:Drag & Drop]]
* [[Places:Manager]]
* [[Places:Bookmarks Containers]]
* [[Places:Live Bookmarks]]
* [[Places:Live Bookmarks]]


Line 48: Line 40:
* [[Bookmarks Use Cases]] (not specific to places)
* [[Bookmarks Use Cases]] (not specific to places)


== Functional Requirements ==


The original requirements for Places in Firefox 3 are detailed in the [[Firefox3/Product_Requirements_Document#Places|Firefox 3 PRD]]


== Details ==
== Details ==
Line 70: Line 60:
=== Views ===
=== Views ===


There are three primary types of view for Places:  
The [https://developer.mozilla.org/En/Displaying_Places_information_using_views MDC page] has the most up-to-date information on how to use views to display information from places.
 
* '''Tree/List view''' - Can show flat lists or hierarchical structures. e.g. the panes in the Places Organizer window.
* '''Toolbar view''' - Shows folders as buttons that have dropdown menus. e.g. the Bookmarks Toolbar in the browser window.
* '''Menu view''' - Shows folders as sub menus. e.g. the Bookmarks Menu in the browser window.
 
Each of these views implement a Places View interface which provides view-agnostic means for obtaining the current selection and other information. The Views themselves take on no controller-like responsibilities. They are not responsible for handling user clicks and opening links, etc - just presenting a list of places.  
 
XXXben - fill in details!


Source code: <code>mozilla/browser/components/places/content/tree|menu|toolbar.xml</code>
Source code: <code>mozilla/browser/components/places/content/tree|menu|toolbar.xml</code>
Line 90: Line 72:
== Querying History ==
== Querying History ==


<center>http://www.bengoodger.com/software/mb/places/LifeOfQuery.png</center>
See [https://developer.mozilla.org/En/Querying_Places the MDC page] for details on history querying.
 
To display results in a PlacesView, the following steps are performed:
 
=== Query Creation ===
 
Any list of items is the result of a query. e.g. the contents of a particular bookmark folder is a request for all URLs with the bookmark flag set that are contained by a named folder. Or all pages in a specific date range. And so on. Queries are represented as strings (which can be Bookmarked - "saved searches" or "virtual folders") containing all the parameters. -->brettw - fill in details!
 
=== Query Execution ===
 
The contents of the query string are deserialized and a series of Query objects are constructed. The query objects are executed.
 
=== Result Gathering ===
 
The results of the execution are gathered. --> brettw - fill in details! Not all queries produce results in the form of rows from the main URL table. Some produce results dynamically by consulting the contents of a directory on the user's file system (e.g. a new implementation of the old File System Datasource), for example. There are potentially other examples of remote data sources being used to feed data into the places view. Data sources like the Feed handler and the Bonjour listener would work slightly differently however. They would have their own timeout/notification based system by which they would detect new content, and then push URLs/rows into the main URL table whenever there was new data, so that when their containers were opened static content from the last dump is shown.
 
=== Result Organization ===
 
The results object is passed to a "Grouper" which organizes the results into a hierarchy based on a set of rules specified by the user interface. These rules form a kind of filter, for example: show all bookmarks organized into their appropriate folders; show history from last week, grouped by site; show all URLs matching the string "goats" in a flat, ungrouped list.
 
=== View Creation ===
 
The grouped results object is passed to the View implementation which supplies the necessary structure for the user interface.


== Other Components ==
== Other Components ==
Line 132: Line 92:
Migrating data from Netscape-bookmarks-file-1, [[Mork]], etc, to the storage format.  
Migrating data from Netscape-bookmarks-file-1, [[Mork]], etc, to the storage format.  


* [http://mxr.mozilla.org/seamonkey/source/browser/components/places/public/nsIPlacesImportExportService.idl HTML Import/Export API]
* [http://mxr.mozilla.org/mozilla-central/source/browser/components/places/public/nsIPlacesImportExportService.idl HTML Import/Export API]
* JSON Import/Export API (XXX {{bug|384370}})
* JSON Import/Export API (XXX {{bug|384370}})


Line 139: Line 99:
Observer APIs for extensions and other components that want to listen to backend activity:
Observer APIs for extensions and other components that want to listen to backend activity:


* [http://mxr.mozilla.org/seamonkey/source/toolkit/components/places/public/nsINavBookmarksService.idl#56 Bookmark Observer API]
* [https://developer.mozilla.org/En/NsINavBookmarkObserver Bookmark Observer API]
* [http://mxr.mozilla.org/seamonkey/source/toolkit/components/places/public/nsINavHistoryService.idl#703 History Observer API]
* [https://developer.mozilla.org/En/NsINavHistoryObserver History Observer API]
 
 
=== Historical Documents ===
 
This documents are kept around for historical purposes only.
 
* [[Places:User_Interface]]
* [[Browser History]]
* [[Places:Manager]]

Latest revision as of 22:27, 29 January 2009

Design Overview

Places is designed to be a robust back-end for Bookmarks, History and related components using the mozStorage wrapper for SQLite. It is intended to provide useful APIs for a more usable front-end, emphasizing simple search and categorization.

Generally, you'll want to look at the documentation on MDC instead of what is here. The documentation here is only internal API documentation that isn't generally exposed to add-on authors.

Related Documents:

Objectives

The primary objectives:

  • Improve access to History and Bookmarks
  • Make it easier for people to Bookmark pages

Secondary objectives:

  • Consolidating user data formats
  • Providing a platform for using interesting per-URL metadata
  • Improving the capabilities of Live Bookmarks
  • Providing a solid architecture for bookmark sync and remote storage
  • Extensible Bookmark Providers for customization
  • Flexible Query System
  • Clean Architecture for ease of code reuse and maintainability


Background

Studies from the late 1990s show that while revisitations of pages previously seen counted for roughly 39% of all page navigations (see Google Scholar), Bookmarks and History usage was low (1-3%), despite the fact that roughly 20% of those revisitations were to pages seen > 10 URLs ago (and thus outside the usefulness range of the Back button or menu).

Autocomplete in the URL bar is a useful tool but fails to address some common desires when looking up visited pages. There is a gulf between the capabilities of that tool, the capabilities of the Bookmarks and History systems today, and the desired capabilities of those systems.

Use Cases


Details

Models

Data storage is implemented via a collection of SQLite tables:

places-erd.png

A detailed database schema complete with associations between the various tables within places.sqlite: https://wiki.mozilla.org/images/d/d5/Places.sqlite.schema3.pdf

Source code:

  • Browser front-end: mozilla/browser/components/places
  • Toolkit Services: mozilla/toolkit/components/places

Views

The MDC page has the most up-to-date information on how to use views to display information from places.

Source code: mozilla/browser/components/places/content/tree|menu|toolbar.xml

Controller

The Controller connects the Views to the Model. It is responsible for telling the UI what commands are available, enabled and executing them on the back end services.

Source code: mozilla/browser/components/places/content/controller.js

Querying History

See the MDC page for details on history querying.

Other Components

Dynamic Containers

The following are some example dynamic containers:

  • Feed Container - ping and parse RSS/Atom feeds and fill containers with their posts
  • File System Container - show folders and files from the local hard disk
  • Bonjour Container - fill a container with available network resources discovered by Bonjour Zero-Configuration Networking.
  • Address Book URLs Container - fill a container with URLs mentioned in the system address book

Data Migration

Migrating data from Netscape-bookmarks-file-1, Mork, etc, to the storage format.

Observer API

Observer APIs for extensions and other components that want to listen to backend activity:


Historical Documents

This documents are kept around for historical purposes only.

Retrieved from "https://wiki.mozilla.org/index.php?title=Places:Design_Overview&oldid=126159"