mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-08 19:04:45 +00:00
Bug 1498178 - Add in-tree documentation for the Quantum Bar r=mikedeboer
Differential Revision: https://phabricator.services.mozilla.com/D8960 --HG-- extra : moz-landing-system : lando
This commit is contained in:
parent
9498be51e6
commit
a3c4d56f39
350
browser/docs/AddressBar.rst
Normal file
350
browser/docs/AddressBar.rst
Normal file
@ -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.
|
@ -5,7 +5,8 @@ Firefox
|
||||
This is the nascent documentation of the Firefox front-end code.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:maxdepth: 2
|
||||
|
||||
AddressBar
|
||||
BrowserUsageTelemetry
|
||||
BrowserErrorReporter
|
||||
|
Loading…
Reference in New Issue
Block a user