Utilities

Various modules provide shared utilities to the other components. Code that runs only in the parent process can use any of them. Code that can also run in a content process, such as the input and the view, imports system modules only behind a check for a privileged realm, and otherwise uses the modules that are safe in a content realm: UrlbarShared, UrlbarContentPrefs and UrlbarContentUtils. When adding a helper, put it in UrlbarShared if both sides need it and it uses nothing privileged, and in UrlbarUtils otherwise.

UrlbarPrefs.sys.mjs

Implements a Map-like storage or urlbar related preferences. The values are kept up-to-date.

import { UrlbarPrefs } from "moz-src:///browser/components/urlbar/UrlbarPrefs.sys.mjs";

// 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.

UrlbarContentPrefs.mjs

A content-side module imports this instead of UrlbarPrefs. In a privileged realm it re-exports UrlbarPrefs itself. In a content process it forwards to the port that the Urlbar actor publishes on the window, which offers only a subset of UrlbarPrefs, such as get, addObserver and removeObserver. Exposing another method requires changing the actor.

import UrlbarPrefs from "chrome://browser/content/urlbar/UrlbarContentPrefs.mjs";

UrlbarPrefs.get("delay"); // Gets value of browser.urlbar.delay.

UrlbarUtils.sys.mjs

Includes helpers that need privileged code, such as the search service, Places or form history. It is a system module, so a content realm can’t import it.

import { UrlbarUtils } from "moz-src:///browser/components/urlbar/UrlbarUtils.sys.mjs";

UrlbarShared.mjs

Holds the constants shared across all the components, such as the result types and sources, and the helpers that both sides of the message path need. It can be imported into system and content realms alike, so it must not use privileged APIs or content-only globals like window. Each realm that imports it gets its own copy of the module, so any state it holds is per-realm.

import { UrlbarShared } from "chrome://browser/content/urlbar/UrlbarShared.mjs";

To check whether a value implements a DOM interface, use UrlbarShared.isInstance(value, iface). The interface’s own isInstance() is chrome-only, so it throws in a content realm, and instanceof fails for a value from another global, such as an event from another window. UrlbarShared.isInstance() calls the interface’s isInstance() where it exists, and in a content realm falls back to instanceof, which compares against that realm’s own interface object.

UrlbarContentUtils.mjs

Accessors for things a content module can’t reach for itself, such as the platform, the containers, or whether a window is private. Each accessor goes through the Urlbar actor’s port when one is published on the window, and reaches the value directly otherwise. Because it checks for the port rather than for the process, an input in the parent process that uses the message path takes the same route as one in a content process.

import { UrlbarContentUtils } from "chrome://browser/content/urlbar/UrlbarContentUtils.mjs";
class UrlbarContentUtils()

Per-realm accessors for things a content module can’t reach for itself. Where the Urlbar actor has published a port on the window, they go through it; otherwise this realm reaches them directly. Keying on the port rather than on the realm means the chrome message path takes the same route an unprivileged input does. One class for all of them, so the branch isn’t duplicated per accessor.

static UrlbarContentUtils.getContainers()

The public containers, in display order. Async because ContextualIdentityService reads the profile, which only the parent process can do, so a content realm takes them over the actor.

Returns:

Promise.<Array.<ContainerInfo>>

static UrlbarContentUtils.getDisplaySpec(url)

A URL’s display spec: the IDN-safe Unicode form the URL parser can’t produce.

Arguments:

  • url (string) – The URL to parse.

Returns:

string|null – The display spec, or null if the URL can’t be parsed.

static UrlbarContentUtils.getFixupPrimitives(searchString, isPrivate)

URI fixup primitives for a string, so a caller never holds an nsIURIFixupInfo.

Arguments:

  • searchString (string) – The string to fix up.

  • isPrivate (boolean) – Whether the fixup runs for a private context.

Returns:

URIFixupPrimitives|null – The primitives, or null if fixup threw.

static UrlbarContentUtils.getPlatform()

The platform, as AppConstants.platform names it. Read on first use rather than on import: a content realm has no port until the actor publishes one.

Returns:

string – The platform, e.g. “macosx”, “win” or “linux”.

static UrlbarContentUtils.getSupportUrl(topic)

The SUMO URL for a support topic.

Arguments:

  • topic (string) – The support page slug to append to the SUMO base URL.

Returns:

string

static UrlbarContentUtils.isTextDirectionRTL(value, win)

Whether a string reads right-to-left.

Arguments:

  • value (string) – The text to check.

  • win (Window) – Any window. When calling from a content global, this window must have a UrlbarActorPort.

Returns:

boolean

static UrlbarContentUtils.isWindowPrivate(win)

Whether a window is private.

Arguments:

  • win (Window) – The window to check.

Returns:

boolean

static UrlbarContentUtils.unEscapeURIForUI(uri)

Unescapes a URI’s percent-encoding for display, applying the spoofing protections decodeURIComponent doesn’t.

Arguments:

  • uri (string) – The URI fragment to unescape.

Returns:

string

static UrlbarContentUtils.usesMessagePath()

Whether the message path or direct path should be used.

Returns:

boolean

Where an event says a link should be opened.

Arguments:

  • event (KeyboardEvent|MouseEvent) – The event that triggered the opening.

Returns:

“current”|”tabshifted”|”tab”|”save”|”window”

static UrlbarContentUtils.willLoadInBackground(where, params)

Whether a pick opened with the given where will load in the background.

Arguments:

  • where (string) – Where the pick will open, as returned by whereToOpenLink.

  • params (object) – The params that will be passed to openLinkIn.

Returns:

boolean