Bug 1498178 - Add in-tree documentation for the Quantum Bar r=mikedeboer
authorMarco Bonardo <mbonardo@mozilla.com> <mbonardo@mozilla.com>
Fri, 19 Oct 2018 13:45:19 +0000
changeset 500654 8b7834399818e8a4d73d0350e493114241531a4a
parent 500653 fb372f5f22b3a8813b3c687e5a8d4ce3177fbdea
child 500655 36e622253bc438b14e6356138492f445c9360eab
push id1864
push userffxbld-merge
push dateMon, 03 Dec 2018 15:51:40 +0000
treeherdermozilla-release@f040763d99ad [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersmikedeboer
bugs1498178
milestone64.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1498178 - Add in-tree documentation for the Quantum Bar r=mikedeboer Differential Revision: https://phabricator.services.mozilla.com/D8960
browser/docs/AddressBar.rst
browser/docs/index.rst
new file mode 100644
--- /dev/null
+++ b/browser/docs/AddressBar.rst
@@ -0,0 +1,350 @@
+.. _addressbar:
+
+===========
+Address Bar
+===========
+
+The *Address Bar* component drives the browser's url bar, a specialized search
+access point (SAP) including different sources of information:
+  * Places: the History, Bookmarks, Favicons and Tags component
+  * Search Engines and Suggestions
+  * WebExtensions
+  * Open Tabs
+  * Keywords and aliases
+
+The *Address Bar* component lives in the
+`browser/components/urlbar/ <https://dxr.mozilla.org/mozilla-central/source/browser/components/urlbar/>`_ folder.
+
+.. note::
+
+  The current *Address Bar* is driven by the legacy
+  `toolkit autocomplete <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/autocomplete>`_
+  binding, along with the *Places UnifiedComplete* component. This documentation
+  describes a new rewrite of the feature, also known as the **Quantum Bar**.
+
+.. caution::
+
+  This code is under heavy development and may change abruptly.
+
+
+Global Architecture Overview
+============================
+
+The *Address Bar* is implemented as a *Model-View-Controller* (MVC) system. One of
+the scopes of this architecture is to allow easy replacement of its components,
+for easier experimentation.
+
+Each search is represented by a unique object, the *QueryContext*. This object,
+created by the *View*, describes the search and is passed through all of the
+components, along the way it gets augmented with additional information.
+The *QueryContext* is passed to the *Controller*, and finally to the *Model*.
+The model appends matches to a property of *QueryContext* in chunks, it sorts
+them through a *Muxer* and then notifies the *Controller*.
+
+See the specific components below, for additional details about each one's tasks
+and responsibilities.
+
+
+The QueryContext
+================
+
+The *QueryContext* object describes a single instance of a search.
+It is augmented as it progresses through the system, with various information:
+
+.. highlight:: JavaScript
+.. code::
+
+  QueryContext {
+    searchString; // {string} The user typed string.
+    lastKey; // {string} The last key pressed by the user. This can affect the
+             // behavior, for example by not autofilling again when the user
+             // hit backspace.
+    maxResults; // {integer} The maximum number of results requested. The Model
+                // may actually return more results than expected, so that the
+                // View and the Controller can do additional filtering.
+    isPrivate; // {boolean} Whether the search started in a private context.
+    userContextId; // {integer} The user context ID (containers feature).
+
+    // Properties added by the Model.
+    tokens; // {array} tokens extracted from the searchString, each token is an
+            // object in the form {type, value}.
+  }
+
+
+The Model
+=========
+
+The *Model* is the component responsible for retrieving search results based on
+the user's input, and sorting them accordingly to their importance.
+At the core is the `UrlbarProvidersManager <https://dxr.mozilla.org/mozilla-central/source/browser/components/urlbar/UrlbarProvidersManager.jsm>`_,
+a component tracking all the available search providers, and managing searches
+across them.
+
+The *UrlbarProvidersManager* is a singleton, it registers internal providers on
+startup and can register/unregister providers on the fly.
+It can manage multiple concurrent queries, and tracks them internally as
+separate *Query* objects.
+
+The *Controller* starts and stops queries through the *ProvidersManager*. It's
+possible to wait for the promise returned by *startQuery* to know when no more
+matches will be returned, it is not mandatory though. Queries can be canceled.
+
+.. note::
+
+  Canceling a query will issue an interrupt() on the database connection,
+  terminating any running and future SQL query, unless a query is running inside
+  a *runInCriticalSection* task.
+
+The *searchString* gets tokenized by the `UrlbarTokenizer <https://dxr.mozilla.org/mozilla-central/source/browser/components/urlbar/UrlbarTokenizer.jsm>`_
+component into tokens, some of these tokens have a special meaning and can be
+used by the user to restrict the search to specific type of matches (See the
+*UrlbarTokenizer::TYPE* enum).
+
+.. caution::
+
+  The tokenizer uses heuristics to determine each token's type, as such the
+  consumer may want to check the value before applying filters.
+
+.. highlight:: JavaScript
+.. code::
+
+  UrlbarProvidersManager {
+    registerProvider(providerObj);
+    unregisterProvider(providerObj);
+    async startQuery(queryContext);
+    cancelQuery(queryContext);
+    // Can be used by providers to run uninterruptible queries.
+    runInCriticalSection(taskFn);
+  }
+
+UrlbarProvider
+--------------
+
+A provider is specialized into searching and returning matches from different
+information sources. Internal providers are usually implemented in separate
+*jsm* modules with a *UrlbarProvider* name prefix. External providers can be
+registered as *Objects* through the *UrlbarProvidersManager*.
+Each provider is independent and must satisfy a base API, while internal
+implementation details may vary deeply among different providers.
+
+.. important::
+
+  Providers are singleton, and must track concurrent searches internally, for
+  example mapping them by QueryContext.
+
+.. note::
+
+  Internal providers can access the Places database through the
+  *PlacesUtils.promiseLargeCacheDBConnection* utility.
+
+.. highlight:: JavaScript
+.. code::
+
+  UrlbarProvider {
+    name; // {string} A simple name to track the provider.
+    type; // {integer} One of UrlbarUtils.PROVIDER_TYPE.
+    // The returned promise should be resolved when the provider is done
+    // searching AND returning matches.
+    // Each new UrlbarMatch should be passed to the AddCallback function.
+    async startQuery(QueryContext, AddCallback);
+    // Any cleaning/resetting task should happen here.
+    cancelQuery(QueryContext);
+  }
+
+UrlbarMuxer
+-----------
+
+The *Muxer* is responsible for sorting matches based on their importance and
+additional rules that depend on the QueryContext.
+
+.. caution
+
+  The Muxer is a replaceable component, as such what is described here is a
+  reference for the default View, but may not be valid for other implementations.
+
+*Content to be written*
+
+
+The Controller
+==============
+
+`UrlbarController <https://dxr.mozilla.org/mozilla-central/source/browser/components/urlbar/UrlbarController.jsm>`_
+is the component responsible for reacting to user's input, by communicating
+proper course of action to the Model (e.g. starting/stopping a query) and the
+View (e.g. showing/hiding a panel). It is also responsible for reporting Telemetry.
+
+.. note::
+
+  Each *View* has a different *Controller* instance.
+
+.. highlight:: JavaScript
+.. code:
+
+  UrlbarController {
+    async startQuery(QueryContext);
+    cancelQuery(queryContext);
+    // Invoked by the ProvidersManager when matches are available.
+    receiveResults(queryContext);
+    // Used by the View to listen for matches.
+    addQueryListener(listener);
+    removeQueryListener(listener);
+    // Used to indicate the View context changed, as such any cached information
+    // should be reset.
+    tabContextChanged();
+  }
+
+
+The View
+=========
+
+The View is the component responsible for presenting search results to the
+user and handling their input.
+
+.. caution
+
+  The View is a replaceable component, as such what is described here is a
+  reference for the default View, but may not be valid for other implementations.
+
+`UrlbarInput.jsm <https://dxr.mozilla.org/mozilla-central/source/browser/components/urlbar/UrlbarInput.jsm>`_
+----------------
+
+Implements an input box *View*, owns an *UrlbarView*.
+
+.. highlight:: JavaScript
+.. code::
+
+  UrlbarInput {
+    constructor(options = { textbox, panel, controller });
+    // Used to trim urls when necessary (e.g. removing "http://")
+    trimValue();
+    // Uses UrlbarValueFormatter to highlight the base host, search aliases
+    // and to keep the host visible on overflow.
+    formatValue(val);
+    // Manage view visibility.
+    closePopup();
+    openResults();
+    // Converts an internal URI (e.g. a wyciwyg URI) into one which we can
+    // expose to the user.
+    makeURIReadable(uri);
+    // Handles an event which would cause a url or text to be opened.
+    handleCommand();
+    // Called by the view when a result is selected.
+    resultsSelected();
+    // The underlying textbox
+    textbox;
+    // The results panel.
+    panel;
+    // The containing window.
+    window;
+    // The containing document.
+    document;
+    // An UrlbarController instance.
+    controller;
+    // An UrlbarView instance.
+    view;
+    // Whether the current value was typed by the user.
+    valueIsTyped;
+    // Whether the input box has been focused by a user action.
+    userInitiatedFocus;
+    // Whether the context is in Private Browsing mode.
+    isPrivate;
+    // Whether the input box is focused.
+    focused;
+    // The go button element.
+    goButton;
+    // The current value, can also be set.
+    value;
+  }
+
+`UrlbarView.jsm <https://dxr.mozilla.org/mozilla-central/source/browser/components/urlbar/UrlbarView.jsm>`_
+---------------
+
+Represents the base *View* implementation, communicates with the *Controller*.
+
+.. highlight:: JavaScript
+.. code::
+
+  UrlbarView {
+    // Manage View visibility.
+    open();
+    close();
+    // Invoked when the query starts.
+    onQueryStarted(queryContext);
+    // Invoked when new matches are available.
+    onQueryResults(queryContext);
+  }
+
+UrlbarMatch
+===========
+
+An `UrlbarMatch <https://dxr.mozilla.org/mozilla-central/source/browser/components/urlbar/UrlbarMatch.jsm>`_
+instance represents a single match (search result) with a match type, that
+identifies specific kind of results.
+Each kind has its own properties, that the *View* may support, and a few common
+properties, supported by all of the matches.
+
+.. note::
+
+  Match types are also enumerated by *UrlbarUtils.MATCH_TYPE*.
+
+.. highlight:: JavaScript
+.. code::
+
+  UrlbarMatch {
+    constructor(matchType, payload);
+
+    // Common properties:
+    url: {string} The url pointed by this match.
+    title: {string} A title that may be used as a label for this match.
+  }
+
+
+Shared Modules
+==============
+
+Various modules provide shared utilities to the other components:
+
+`UrlbarPrefs.jsm <https://dxr.mozilla.org/mozilla-central/source/browser/components/urlbar/UrlbarPrefs.jsm>`_
+----------------
+
+Implements a Map-like storage or urlbar related preferences. The values are kept
+up-to-date.
+
+.. highlight:: JavaScript
+.. code::
+
+  // Always use browser.urlbar. relative branch, except for the preferences in
+  // PREF_OTHER_DEFAULTS.
+  UrlbarPrefs.get("delay"); // Gets value of browser.urlbar.delay.
+
+.. note::
+
+  Newly added preferences should always be properly documented in UrlbarPrefs.
+
+`UrlbarUtils.jsm <https://dxr.mozilla.org/mozilla-central/source/browser/components/urlbar/UrlbarUtils.jsm>`_
+----------------
+
+Includes shared utils and constants shared across all the components.
+
+
+Telemetry Probes
+================
+
+*Content to be written*
+
+
+Debugging & Logging
+===================
+
+*Content to be written*
+
+
+Getting in Touch
+================
+
+For any questions regarding the Address Bar, the team is available through
+the #fx-search channel on irc.mozilla.org and the fx-search@mozilla.com mailing
+list.
+
+Issues can be `filed in Bugzilla <https://bugzilla.mozilla.org/enter_bug.cgi?product=Firefox&component=Address%20Bar>`_
+under the Firefox / Address Bar component.
--- a/browser/docs/index.rst
+++ b/browser/docs/index.rst
@@ -1,11 +1,12 @@
 =======
 Firefox
 =======
 
 This is the nascent documentation of the Firefox front-end code.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
+   AddressBar
    BrowserUsageTelemetry
    BrowserErrorReporter