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.

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

Places:History Use Cases
Bookmarks Use Cases (not specific to places)

Details

Models

Data storage is implemented via a collection of SQLite tables:

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

API
Example

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.

HTML Import/Export API
JSON Import/Export API (XXX bug 384370)

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.

@@ Line 1: / Line 1: @@
-=== Design Overview ===
+= Design Overview =
-== Note ==
+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.
-Do NOT edit this page unless you are on the Places team. Add your comments to the Discussion page.
+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.
-== Objectives ==
+Related Documents:
-Integrate bookmarks, history and other data sources into a single places view that loads inside a browser tab. Make bookmarking easier. Make it easier to find and organize visited places.
+* [[Places:AutoComplete]]
+* [[Places:Drag & Drop]]
+* [[Places:Live Bookmarks]]
-== Design Overview ==
+== Objectives ==
-Implement the new UI using a MVC approach, using SQLite for the back end, implementing a single nsIController object to handle edits across the multiple views (tree/list, toolbar, bookmarks menu, go menu)
-<center>http://www.bengoodger.com/software/mb/places/MVC.png</center>
+The primary objectives:
-== Details ==
+* Improve access to History and Bookmarks
+* Make it easier for people to Bookmark pages
-= Models =
+Secondary objectives:
-Bookmarks and History will be implemented using a collection of SQLite tables:
+* 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
-* '''Main URL metadata table''' - A large table containing all URLs that the Places system knows about. Includes all of history and bookmarks, and the key metadata about them (url, title, etc.) Keeping all URLs in a single table will make it easier to better create and rank aggregate search results across all URL types (history, bookmarks, feeds, etc)
-* '''Bookmarks folder hierarchy table''' - A table that describes the folder hierarchy of Bookmarks
-* '''Annotation metadata table''' - A separate table that holds arbitrary metadata about a given URL. This is to prevent the main table from becoming too wide (every extension that adds a custom annotation property widens the large table for all URLs, even those that do not have annotations).
-These models all supply applicable add, edit and remove APIs for use by the command controllers, and the appropriate notifications for use by third party applications that wish to observe edits, such as Clobber.
+== Background ==
-= Views =
+Studies from the late 1990s show that while revisitations of pages previously seen counted for roughly 39% of all page navigations (see [http://scholar.google.com/ 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).
-There are three primary types of view for Places:
+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.
-* '''Tree/List view''' - in the "Places" pane. Can show flat lists or hierarchical structures. Populated by the Storage Template Builder, or an implementation of the nsITreeView interface.
+== Use Cases ==
-* '''Toolbar view''' - in the Browser window. Shows folders as buttons that have dropdown menus. Populated by the Storage Template Builder, or an implementation of the nsIRDFDataSource interface.
-* '''Menu view''' - in the Browser window. Shows folders as sub menus. Populated by the Storage Template Builder, or an implementation of the nsIRDFDataSource interface.
-Each of these views will implement an Abstract View Interface (AVI) which identifies (at the least) the current selection. In the context of a tree, the current selection is a set of rows, for a toolbar it's the node the context menu was brought up on. --> beng - fill in details!
+* [[Places:History Use Cases]]
+* [[Bookmarks Use Cases]] (not specific to places)
-'''User Interface'''
-The user interface combines these views in various ways. It also presents other pieces of UI like context menus and toolbar buttons and search boxes, which execute queries and perform commands on the selection.
-= Controller =
+== Details ==
-A single command controller that advertises the list of supported commands, enabled commands, and executes commands, based on the state supplied by the AVI. The AVI also uses the API supplied by the various back ends (Places Service, Annotation Service) to perform user edits, additions and removals.
-= What it Looks Like =
-Something like this:
-<pre>
-+-----------------------------------------------------------------------+
-| +----------------------+ Search: [               :^] from: [ date ]   |
-| | @ All Bookmarks      | +------------------------------------------+ |
-| | @ Bookmarks Bar      | | Name               | Location            | |
-| | @ All History        | |--------------------+---------------------+ |
-| | @ Feeds              | |                                          | |
-| | @ Most Visited       | |                                          | |
-| | @ Recently Updated   | |                                          | |
-| | @ Bonjour            | |                                          | |
-| | @ Folder 1           | |                                          | |
-| | @ Folder 2           | |                                          | |
-| | @ Folder 3           | |                                          | |
-| | @ Folder 4           | |                                          | |
-| |                      | |                                          | |
-| |                      | |                                          | |
-| |                      | |                                          | |
-| |                      | |                                          | |
-| |                      | |                                          | |
-| |                      | |                                          | |
-| |                      | |                                          | |
-| |                      | |                                          | |
-| |                      | |                                          | |
-| +----------------------+ +------------------------------------------+ |
-| ( + New Folder )          ( @ Options ) ( Save Search... )            |
-+-----------------------------------------------------------------------+
-</pre>
-The left bar is a folders-only view of the root of the Bookmarks namespace. It can contain nested folders if folders nest, in a tree view. Users can drag folders onto it. It also contains some pre-defined virtual folders, like Most Visited and Recently Updated. Some of these folders (like History, Bookmarks, the Toolbar etc) cannot be removed because there is no way for them to be recreated once they are gone. The right side shows a filter UI at the top, and a list/tree view below showing the contents of the selection at left.
-The filter UI at top is simple, showing a text search field and a calendar widget for date range selection. It should be possible to build more complicated queries based on other metadata by clicking a "more" or "+" button to the right of the query line, which will add a new row with more query options.
+=== Models ===
-Smart queries can be saved as bookmarks using the Save Search button.
+Data storage is implemented via a collection of SQLite tables:
-Grouping can be performed using a "group by" selector (not shown).
+http://people.mozilla.com/~dietrich/places-erd.png
-To be worked out:
+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
-* What goes in the Bookmarks Menu? A non-critical detail that can be worked out at the end. Perhaps the contents of the left "Places" bar, plus all the user's bookmarks
+Source code:
-* Can the calendar widget be made any more discoverable?
-'''Sample Places Bar Idea: Feeds'''
+* Browser front-end: <code>mozilla/browser/components/places</code>
+* Toolkit Services: <code>mozilla/toolkit/components/places</code>
-A Feed folder that is a query of all URLs that have a "feed" annotation. When selected it shows the feeds in the right pane as folders, using the Feed Handler to load the content. The user can choose to sort the content based on recency, which breaks all the content out of the containing Feed folders and intermingles the individual posts from each feed, effectively creating a Feed aggregator.
+=== Views ===
-= Displaying Items and Results =
+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.
-<center>http://www.bengoodger.com/software/mb/places/LifeOfQuery.png</center>
+Source code: <code>mozilla/browser/components/places/content/tree|menu|toolbar.xml</code>
-To display results in a PlacesView, the following steps are performed:
+=== Controller ===
-'''Query Creation'''
+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.
-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!
+Source code: <code>mozilla/browser/components/places/content/controller.js</code>
-'''Query Execution'''
+== Querying History ==
-The contents of the query string are deserialized and a series of Query objects are constructed. The query objects are executed.
+See [https://developer.mozilla.org/En/Querying_Places the MDC page] for details on history querying.
-'''Result Gathering'''
+== Other Components ==
-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.
+=== Dynamic Containers ===
-'''Result Organization'''
+* [http://mxr.mozilla.org/seamonkey/source/toolkit/components/places/public/nsIDynamicContainer.idl API]
+* [http://mxr.mozilla.org/seamonkey/source/toolkit/components/places/tests/unit/nsDynamicContainerServiceSample.js Example]
-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.
+The following are some example dynamic containers:
-'''View Creation'''
-The grouped results object is passed to the View implementation which supplies the necessary structure for the user interface.
-For non-tree views, RDF will be used until such a time as a non-RDF template builder becomes available. HistoryResults can be associated with a Places RDF DataSource that registers the result with a serialization of its queries and options (forming a RDF Resource that can be used to root a piece of UI on the result):
-<center>http://www.bengoodger.com/software/mb/places/RDFWrapper.png</center>
-= Other Required Work =
-'''Remote Containers'''
-The following are some example remote Feed containers. The first two are required.
 * '''Feed Container''' - ping and parse RSS/Atom feeds and fill containers with their posts
@@ Line 135: / Line 88: @@
 * '''Address Book URLs Container''' - fill a container with URLs mentioned in the system address book
-'''Data Migration'''
+=== Data Migration ===
 Migrating data from Netscape-bookmarks-file-1, [[Mork]], etc, to the storage format.
-'''Property Editor'''
+* [http://mxr.mozilla.org/mozilla-central/source/browser/components/places/public/nsIPlacesImportExportService.idl HTML Import/Export API]
+* JSON Import/Export API (XXX {{bug|384370}})
-A property editing pane for the view pane that allows users to edit properties on individual URLs. This should be easily overlay-able so that extensions can add editors for their own custom properties that they track using the Annotation Service.
-'''Notification API'''
-A notification API for third party applications like Clobber that wish to observe edit operations on the back end.
-'''Complete Storage Template Builder'''
-The Storage Template Builder will be used for building UI based on storage statements. There is a patch to allow the template builder to become more generic but it needs review/testing, and the Storage sections of it need to be implemented.
-'''Migrate Form History'''
-After History, Form History is the only remaining component in Firefox that uses the [[Mork]] data storage format. It should be migrated to use Storage too.
+=== Observer API ===
-'''Remove Mork'''
+Observer APIs for extensions and other components that want to listen to backend activity:
-Once all Firefox dependencies on [[Mork]] have been severed, the [[Mork]] component should no longer be built, to save download size, as we predict building storage will incur a download size increase.
+* [https://developer.mozilla.org/En/NsINavBookmarkObserver Bookmark Observer API]
+* [https://developer.mozilla.org/En/NsINavHistoryObserver History Observer API]
-= Nice to Have =
-The following things would be great to have but are not requirements:
+=== Historical Documents ===
-'''In-Place Edit for Trees'''
+This documents are kept around for historical purposes only.
-It should be possible for users to edit the name and URL and other displayed properties of items in the Places tree view, without having to show another dialog. This is not implemented right now on the tree widget.
+* [[Places:User_Interface]]
+* [[Browser History]]
+* [[Places:Manager]]

Places:Design Overview: Difference between revisions