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. It is reached by UrlbarChildController through the Urlbar JSWindowActor pair. For chrome <moz-urlbar> instances both controllers are in the parent process and UrlbarChildController holds a direct reference to this class; future content-process consumers (e.g. about:newtab) will route calls through the actor pair instead.

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 class. The manager may be overridden here, this is for test purposes.

Arguments:

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

  • options.input (UrlbarInput) – The input this controller is operating with.

  • 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 class. The manager may be overridden here, this is for test purposes.

UrlbarParentController.input

type: unknown

UrlbarParentController.manager

type: ProvidersManager

UrlbarParentController.platform

type: string

The platform constant.

UrlbarParentController.userSelectionBehavior

Stores the selection behavior that the user has used to select a result.

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.getResultCommands(result, isPrivate)

Returns the result menu commands a result’s provider offers, if any. Mediates the view’s access to the (parent-process) provider.

Arguments:

  • result (UrlbarResult) – The result.

  • isPrivate (boolean) – Whether the query is private.

Returns:

Array.<UrlbarResultCommand> – The commands, or null/undefined.

UrlbarParentController.getViewTemplate(result)

Returns the view template a dynamic result’s provider uses to build its row. Mediates the view’s access to the (parent-process) provider.

Arguments:

  • result (UrlbarResult) – The dynamic result.

Returns:

object – The view template.

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.handleKeyNavigation(event, executeAction=true)

Receives keyboard events from the input and handles those that should navigate within the view or pick the currently selected item.

Arguments:

  • event (KeyboardEvent) – The DOM KeyboardEvent.

  • executeAction (boolean) – Whether the event should actually execute the associated action, or just be managed (at a preventDefault() level). This is used when the event will be deferred by the event bufferer, but preventDefault() and friends should still happen synchronously.

UrlbarParentController.keyEventMovesCaret(event)

Checks whether a keyboard event that would normally open the view should instead be handled natively by the input field. On certain platforms, the up and down keys can be used to move the caret, in which case we only want to open the view if the caret is at the start or end of the input.

Arguments:

  • event (KeyboardEvent) – The DOM KeyboardEvent.

Returns:

boolean – Returns true if the event should move the caret instead of opening the view.

UrlbarParentController.notify(name, ...params)

Notifies listeners of results, by dispatching through the listener host (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.removeResult(result)

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

Arguments:

  • result (UrlbarResult) – The result to remove.

UrlbarParentController.setLastQueryContextCache(queryContext)

Set the query context cache.

Arguments:

  • queryContext (UrlbarQueryContext) – the object to cache.

UrlbarParentController.setListenerHost(host)

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

Arguments:

  • host (object) – The listener host.

UrlbarParentController.setView(view)

Hooks up the controller with a view.

Arguments:

  • view (UrlbarView) – The UrlbarView instance associated with this controller.

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.