urlbar API

Audience

The initial audience for the API described here is specifically teams internal to Mozilla and Mozilla partners. See the Motivation section below for why we're creating it. While we may consider wider use cases in the future, our design initially will be guided by what Mozilla and its partners need.

Background

Firefox's urlbar implementation is spread across several layers in the codebase:

1. browser.xul is the XUL markup that makes up the main Firefox window. It includes the urlbar and its popup.

2. urlbarBindings.xml is the XBL markup that defines the urlbar and its popup, and that the urlbar in browser.xul is bound to.

3. autocomplete.xml is the toolkit XBL markup that defines toolkit's autocomplete widget, and which the binding in urlbarBindings.xml inherits from and extends.

4. nsAutoCompleteController.cpp is the toolkit implementation of a cluster of IDLs that define how autocomplete-related objects interact with each other. These objects include views, the text box and popup; the model, searches; and the controller that connects the views and model, the autocomplete controller.

5. Finally, UnifiedComplete.js provides the model part of that system, the search data. It integrates data from Firefox's Places database and other sources in Firefox, like open tabs and tabs synced from other devices.

Problems

That's a reasonable architecture for Firefox to use, but it can also make it hard for people, especially new people, to modify the look and feel of the urlbar and its popup or provide new data sources for it to integrate. Problems include the following:

• The many layers of the architecture make it hard to know which you need to modify, and your modifications may need to touch multiple layers

• Even if you know the architecture, it's just not amenable to radical visual changes

• Depending on your modifications, you may need to modify Firefox itself instead of being able to package them in an add-on

• Changes in Firefox in any one of those layers can break your modifications

• If you only need to touch the topmost layer, the XUL and XBL, if you're new to front-end Firefox development, XUL and XBL are foreign

• If you don't need to change the popup's appearance at all but do need to provide new data for it to integrate, it's still not straightforward

Motivation

Recently there's been interest at Mozilla in experimenting with novel UIs and data sources in the urlbar. For example, the Universal Search team has been running a Test Pilot experiment where the urlbar popup offers suggestions drawn from sources on the web based on what the user has typed in the urlbar. If the user types in the name of a movie for example, Universal Search might modify the popup so that it displays show times or movie reviews. The user doesn't even need to hit the Return key.

Even more recently, Mozilla's new partnership with Cliqz has created another scenario where we and the team at Cliqz would like the ability to radically alter the look of the urlbar popup and the information it displays.

Both of these cases involve teams that aren't themselves working on the urlbar. In fact the team that is working on the urlbar is quite small. We would like to be able to experiment with the urlbar without funneling everything through the urlbar team.

Solution

We are creating a new urlbar API expressly for the purpose of addressing these problems and use cases. Its goals are:

• Based on HTML/CSS/JS, not XUL/XBL/cpp/xpidl

• A single point of modification

• Consumers of the API can be packaged in add-ons, no Firefox changes necessary

• A stable platform

• The flexibility to replace the popup's entire contents

• The ability to blend in the stock Firefox results/data

• A bonus/stretch goal: a simpler way to fetch Places data than what Firefox currently offers via its XPCOM components and JSMs

There's a tradeoff for the consumer between flexibility and simplicity. The more flexible the API is, the more work potentially the consumer needs to do. The simpler the API is, the less work potentially the consumer needs to do, but obviously that would exclude more use cases.

We considered a simpler alternative where the consumer simply provides a JSON blob that describes the results with which it wants to populate the urlbar, but after speaking with some people who are target users of the API, we think that's not flexible enough. We also considered permitting consumers to modify only the topmost result in the popup, but that again would make UXes like Cliqz's impossible.

Architecture

The API consumer's code runs entirely in an iframe that the runtime injects into the urlbar popup. The entire contents of the popup are replaced with the iframe, which is sandboxed for security. Currently it is not remote, but that could change. The API is designed in such a way that if that does change, it should be able to change transparently to existing API consumers.

The API runtime comprises two pieces: (1) a small shim that lives in Firefox itself, in mozilla-central (“the shim”), and (2) the actual API implementation that is packaged in the add-on (“the runtime”).

Part (1) is a shim between Firefox and the add-on. It creates and tears down the iframe in the popup. It also provides hooks to part (2), the runtime, and insulates the runtime from breaking changes across Firefox versions. The shim is small as possible.

Part (2), the runtime, is where the API is actually implemented. Its code is kept in a non-mozilla-central repo. Consumers pull the repo and include it in their add-ons. The runtime adds a `urlbar` property to `window` inside the iframe that the consumer uses to interact with it. The runtime also fires events on the iframe. (See below.)

The distinction between these two parts means that we can iterate on the API rapidly, and consumers can use new iterations immediately, outside the Firefox release cycle. We expect these two properties to be especially useful as consumers start to use the API and find problems with it. Once the API becomes stable, we can consider shipping it as part of Firefox.

[To be determined: In 2017, traditional add-ons will be deprecated in favor of WebExtensions. Need to look into how WebExtensions work and how the API implementation can be made compatible with them.]

Contention for the iframe between Multiple Add-ons

We’re not currently planning on supporting multiple consumer add-ons at once. It will probably be the case that the first add-on wins if the user were to install multiple consumer add-ons.

The reason is that this API is intended to be used internally at Mozilla and by Mozilla partners, at least initially. In that context, we can control contention and work around any problems ad hoc that might arise.

Certainly designing for multiple add-ons and for the add-on community at large is a potential future goal.

Current State

Part (1), the shim, is being implemented in https://bugzilla.mozilla.org/show_bug.cgi?id=1257550. We want to land that by the end of 2016.

Part (2), the API runtime, is partially implemented in this repo, along with a toy consumer add-on that uses it: https://hg.mozilla.org/users/dwillcoxon_mozilla.com/urlbar-api-toy-addon/

Intended Use & Long Term

The API and runtime should work well enough that experimental, non-production UXes can be shipped with it as part of Shield studies, Test Pilot, etc.

It's unlikely that we'll want to ship real Firefox features with it. It's possible that we might use the API to prototype real features, but we'll probably want to reimplement them in XUL, etc. before shipping them.

It's also possible that we take lessons learned from consumers of this API and apply them to a "version 2.0" API that from the beginning is designed and intended for wide use or specific cases.

API: Entry Point

To initialize the iframe in the popup, a consumer add-on imports UrlbarAPI.jsm and calls UrlbarAPI.init() (in its bootstrap.js file, for example):

• UrlbarAPI.init(runtimePath, iframeHTMLPath)
  
  runtimePath is the chrome URL of the directory inside the add-on that contains the API runtime code. The runtime implementation consists of multiple JSMs that it needs to load internally, which is why this is necessary.
  
  iframeHTMLPath is the chrome URL of the HTML file that the add-on wants to load in the iframe. Aside from the urlbar API that’s injected into the iframe, there’s nothing special about this HTML. It can use JS and CSS like any content page.

API: window.urlbar

The runtime injects a `window.urlbar` object into the JS running in the iframe. It has the following API.

• urlbar.getValue() -> String
  
  The string in the text box.

• urlbar.setValue(value)
  
  Sets the value in the text box.

• urlbar.enter()
  
  Tells the urlbar to simulate an Enter/Return keypress in the urlbar, i.e., to navigate to the value currently in the urlbar.

• urlbar.getMaxResults() -> Number
  
  The number of stock Firefox results that the runtime will notify the consumer of via the result event (see below).

• urlbar.setMaxResults(value)
  
  Sets the number of stock Firefox results that the runtime will notify the consumer of.

• urlbar.getPanelHeight() -> Number
  
  The height of the urlbar popup in CSS pixels.

• urlbar.setPanelHeight(value)
  
  The height of the popup is controlled by the add-on, since the add-on determines what is shown in the iframe. The given value is in CSS pixels.

• urlbar.showSearchButtons(show)
  
  Shows or hides the one-off search buttons that are normally present in the popup (on Nightly anyway). By default they are hidden so that the consumer can fully take over the popup, but simpler add-ons that want to blend in with the stock results may want to show them.

API: Events

The runtime notifies the consumer of various events by firing DOM events on the window. The text box retains focus while the popup is open; that’s the usual behavior in Firefox and the runtime doesn’t change that. Therefore, the consumer needs to be notified when keypresses and input happen in the text box, for example.

To be notified when the iframe is moused over and of other events inside the iframe, the consumer can add event listeners on `window` or elsewhere, as web pages normally do.

The events fired by the runtime are:

• urlbar:input
  
  The value of the text box has changed.

• urlbar:keydown
  
  The user has pressed a key (in the text box -- keep in mind that the text box retains focus).
  
  event.detail: {

  code,

  key,

  altKey,

  ctrlKey,

  metaKey,

  shiftKey,

}

• urlbar:reset
  
  A new search has started and the consumer should respond accordingly, for example by clearing the contents of the iframe.

• urlbar:result
  
  Firefox has fetched a "stock" result based on the user's search string. The consumer can show it if it likes or ignore it. The number of such results sent to the consumer is at most the value returned by urlbar.getMaxResults().
  
  event.detail: {

  url,

  faviconURI,

  title,

  type,

  searchStr,

}

To Be Determined

• There needs to be some way for the consumer to be able to style results the same as Firefox styles its stock results so that it can simulate blending in with the stock urlbar. This is especially important for simple add-ons that for example only add an extra result or two to the stock results.

• Aside from the previous point, there needs to be a way for the consumer to access the styles, colors, etc. that Firefox normally uses, and also icons like the magnifying glass, globe, etc.

What about the one-off search buttons/settings? Are they expected to be part of the iframe or part of the popup and not changeable? [urlbar.showSearchButtons() should cover this.]

If they are contained within the iframe, we’ll also need to consider about allowing a context menu to be created via the API. Otherwise you’ll be constrained to having the context menu within the iframe boundaries (i.e. different results to what we have on nightly today).

What about search suggestions? Would those still stream in to fill up the popup if the total number of results is less than maxResults? If so, what would the event look like, since it’s not a complete result? [“Result” means any entry that’s normally shown in the urlbar popup, including search suggestions. There’s a `type` property on the event detail object to tell you the type (search, history, etc.)]

How do we handle a11y? I never did figure out if an iframe inside a XUL popup is accessible to screen readers. [Yikes, dunno. Would need to look into it.]

What happens to the history popup (the popup shown if you click the down caret in the urlbar)? [Good question! Right now you would get a reset and result events, but without any input event. Maybe worth handling separately.]

Is it possible to build our current awesomebar results list using this API. Is there any benefit or drawback to doing so? Not saying that we should, yet, but if we can’t it suggests the API is missing something. [Good question. The toy add-on I have basically does that. There are some uncanny valley problems to solve though. This is a good way to test the API, I agree.]