UrlbarParentController Reference

class UrlbarParentController(options)

The address bar controller handles queries from the address bar, obtains results and returns them to the UI for display.

In the parent/child controller split, this class owns the bits that must run in the parent process: the {@link ProvidersManager}, query lifecycle, and parent-only telemetry. UrlbarChildController reaches it directly when both run in the parent process (chrome <moz-urlbar>), or through the Urlbar JSWindowActor pair when the child runs in a content process.

Listeners may be added to listen for the results. They may support the following methods which may be called when a query is run:

  • onQueryStarted(queryContext)

  • onQueryResults(queryContext)

  • onQueryCancelled(queryContext)

  • onQueryFinished(queryContext)

  • onQueryResultRemoved(index)

  • onViewOpen()

  • onViewClose()

Initialises the controller from standalone data; the live input/view are reached at runtime through the paired UrlbarChildController.

Arguments:

  • options (object) – The initial options for UrlbarParentController.

  • options.sapName (string) – The search access point name, e.g. urlbar, searchbar.

  • options.isPrivate (boolean) – Whether the controller serves a private-browsing input.

  • options.actor (object) – The owning UrlbarParent JSWindowActor, used to resolve the chrome window. Omitted in unit tests.

  • options.manager (object) – Optional fake providers manager to override the built-in providers manager. Intended for use in unit tests only.

UrlbarParentController.UrlbarParentController

Initialises the controller from standalone data; the live input/view are reached at runtime through the paired UrlbarChildController.

UrlbarParentController.browserWindow

type: ChromeWindow

The chrome window the urlbar lives in, resolved parent-side from the actor. Parent-side providers read this (icons, speculative connect, opening help links), so it can’t come from the content-side child.

UrlbarParentController.input

type: UrlbarInput

The input, owned by the paired UrlbarChildController and read through it for the query-lifecycle and telemetry call sites that need it.

UrlbarParentController.manager

type: ProvidersManager

UrlbarParentController.platform

type: string

The platform constant.

UrlbarParentController.view

type: UrlbarView

The view.

UrlbarParentController.cancelQuery()

Cancels an in-progress query. Note, queries may continue running if they can’t be cancelled.

UrlbarParentController.clearLastQueryContextCache()

Clear the previous query context cache.

UrlbarParentController.getHeuristicResult(queryContext)

Runs a one-off query and returns its heuristic result. Mediates the input’s access to the (parent-process) providers manager, e.g. for paste-and-go and drop-and-go where the input needs the heuristic result without an open view.

Arguments:

  • queryContext (UrlbarQueryContext) – The query context to run.

Returns:

Promise.<UrlbarResult> – The heuristic result.

UrlbarParentController.getViewUpdate(result, idsByName)

Returns the view update a dynamic result’s provider produces for the given node ids. Mediates the view’s access to the (parent-process) provider.

Arguments:

  • result (UrlbarResult) – The dynamic result.

  • idsByName (object) – A map from node names to element ids.

Returns:

Promise.<object> – The view update.

UrlbarParentController.handleBounceTrigger(payload)

Records a bounce a message-path child collector triggered. The counterpart to the proxy’s handleBounceTrigger().

Arguments:

  • payload (object) – {snapshot, startTime, browsingContextId, contentData}.

Returns:

Promise.<void> –

UrlbarParentController.notify(name, ...params)

Notifies listeners of results, by dispatching through the paired UrlbarChildController, which owns the listeners.

Arguments:

  • name (string) – Name of the notification.

  • params (object) – Parameters to pass with the notification.

UrlbarParentController.onBeforeSelection(result, element)

Notifies a result’s provider that the result is about to be selected. Mediates the view’s access to the (parent-process) provider.

Arguments:

  • result (UrlbarResult) – The result being selected.

  • element (Element) – The selected element.

UrlbarParentController.onSelection(result, element)

Notifies a result’s provider that the result was selected. Mediates the view’s access to the (parent-process) provider.

Arguments:

  • result (UrlbarResult) – The selected result.

  • element (Element) – The selected element.

UrlbarParentController.receiveResults(queryContext)

Receives results from a query.

Arguments:

  • queryContext (UrlbarQueryContext) – The query details.

UrlbarParentController.recordEngagement(wire)

Records an engagement shipped by a message-path child collector. The counterpart to the proxy’s recordEngagement(): deserializes the payload and hands it to the recorder. On the direct path the child collector isn’t used, so this isn’t called.

Arguments:

  • wire (object) – The payload from UrlbarTelemetryUtils.recordedEngagementToWire().

UrlbarParentController.removeResult(result, options)

Removes a result from the current query context and notifies listeners. Heuristic results cannot be removed.

Arguments:

  • result (UrlbarResult) – The result to remove.

  • options (object) – Options object.

  • options.acknowledgeDismissalL10n (object) – When the result is being dismissed, the l10n for the acknowledgment tip that should replace its row. Passed through to the view rather than set on the result so the result stays identical on both sides of the actor boundary.

UrlbarParentController.resetEngagement()

Resets the recorder’s cross-session telemetry state. The counterpart to the proxy’s resetEngagement().

UrlbarParentController.setChild(child)

Sets the paired UrlbarChildController, which owns listener registration and notification dispatch. It must be set before any query runs, since the query lifecycle notifies through it.

Arguments:

  • child (object) – The paired UrlbarChildController.

UrlbarParentController.setLastQueryContextCache(queryContext)

Set the query context cache.

Arguments:

  • queryContext (UrlbarQueryContext) – the object to cache.

UrlbarParentController.speculativeConnect(result, context, reason)

Tries to initialize a speculative connection on a result. Speculative connections are only supported for a subset of all the results.

Speculative connect to:

  • Search engine heuristic results

  • autofill results

  • http/https results

Arguments:

  • result (UrlbarResult) – The result to speculative connect to.

  • context (UrlbarQueryContext) – The queryContext

  • reason (string) – Reason for the speculative connect request.

UrlbarParentController.startQuery(queryContext)

Takes a query context and starts the query based on the user input.

Arguments:

  • queryContext (UrlbarQueryContext) – The query details.

Returns:

Promise.<UrlbarQueryContext> – The updated query context.

UrlbarParentController.trackBounceBrowser(browserId)

Caches the live browser behind a bounce the message-path collector is tracking, so handleBounceTrigger() can resolve it once the tab is gone. The counterpart to the proxy’s trackBounceBrowser().

Arguments:

  • browserId (number) – The bounce browser’s stable browser id.