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(resultId)

  • 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._lastAutofillReintegrationPromise

type: Promise.<void>

Resolves with the most recent handleAutofillReintegration() call’s work, including its Glean recording. The input fires re-integration without awaiting it, so tests await this to sequence on the cleared block and the recorded telemetry.

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.observe
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.checkKeywordURIFixup(searchString, browserId)

Runs the single-word keyword URI fixup DNS check for a search picked in the address bar. When a single word is turned directly into a search (bypassing the docShell), this reproduces the docShell’s DNS lookup that offers to visit the word as a host instead (see gKeywordURIFixup). Routed here because it shows a per-window infobar the content input can’t, and it needs the parent’s search service to fix up the string.

Arguments:

  • searchString (string) – The string being searched.

  • browserId (number) – The browser the search loads into, or null for the selected browser.

UrlbarParentController.clearAutofillBackspaceEntryForUrl(url)

Clears the backspace bookkeeping for an autofilled URL the user accepted. The bookkeeping is parent state, so the input hands the URL over here.

Arguments:

  • url (string) – The accepted autofill result’s URL.

UrlbarParentController.clearLastQueryContextCache()

Clear the previous query context cache.

UrlbarParentController.destroy()

Tears down the controller’s process-wide registrations, so nothing reaches it once the input it serves is gone.

UrlbarParentController.dismissAutofill(url, action)

Dismisses an autofilled URL on the user’s behalf, blocking the autofill pairing or removing the URL from history. Async so callers can await the write before re-running their query on either transport.

Arguments:

  • url (string) – The dismissed autofill result’s URL.

  • action ("dismiss"|"forget") – “dismiss” blocks the autofill pairing for a period of time. “forget” removes the URL from history entirely.

UrlbarParentController.focusBrowser(browserId)

Focuses the browser a deferred-Enter load targeted, once the load’s keyup fires, but only if it is still the selected browser. Reaching the browser element and comparing it against the selection is parent-only work.

Arguments:

  • browserId (number) – The browser the load resolved to, as returned by loadURL.

Returns:

Object – Whether the browser was focused, so the child can keep the domain name visible.

UrlbarParentController.getEngineIconURL(engineId)

Returns the icon URL of the engine with the given id. This can be a blob URL, which only resolves in this process, so UrlbarParent serializes it before handing it to another process.

Arguments:

  • engineId (string)

Returns:

Promise.<?string> – The icon URL, or null if the engine or its icon could not be found.

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.handleAutofillReintegration(url)

Re-integrates an autofill URL the user navigated to anyway: clears its autofill block and records how long the block had been in place. Both the block state and Glean are parent-side, so the input only decides when a navigation counts as a re-integration and hands the URL over here.

Arguments:

  • url (string) – The URL being re-integrated.

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.loadURL(loadData)

Loads a URL in the browser window resolved from the actor. The content child supplies the serializable load parameters; the parent fills in the ones that reference the chrome window (the target browser and initiating document) and reports back whether the load failed in a way that should revert the input.

Arguments:

  • loadData (object)

  • loadData.url (string) – The URL to load.

  • loadData.where (string) – Where to open, per openTrustedLinkIn.

  • loadData.params (object) – The serializable openTrustedLinkIn params.

  • loadData.browserId (number) – The target browser’s id; defaults to the selected browser.

  • loadData.userTypedValue (string) – The value to record as the browser’s typed value, for a current load.

Returns:

Object – Whether the load threw without showing an error page, so the input should revert, and the id of the browser the load resolved to. The latter is not an echo of the optional browserId param: a default current load omits it and the target is resolved here, so this is how the child learns which browser to hand focusBrowser on the deferred-Enter keyup – a content-process input can’t resolve the selected browser itself.

UrlbarParentController.markEngineAsUsed(engineId)

Marks the engine with the given id as used if it’s a config engine that hasn’t been used already.

Arguments:

  • engineId (string)

UrlbarParentController.maybeInitEngineStore()

Initializes the engine store synchronously if the search service is already loaded and initialized.

Since this is only useful if it can be called synchronously, it’s intentionally not exposed in UrlbarParentControllerProxy.

Returns:

boolean – Whether the engine store was initialized successfully.

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.openSERP(engineId, searchTerms, where, inBackground=false, browserId=null)

Opens a search engine result page (SERP) for the specified search engine and search query.

Does not record telemetry, so it should be recorded by the caller.

Arguments:

  • engineId (string)

  • searchTerms (string)

  • where (string)

  • inBackground (boolean)

  • browserId (number) – The target browser’s id. Only used if where == current and the call isn’t coming from a content process. If it’s not specified and where == current, the currently selected tab is used.

UrlbarParentController.openSearchForm(engineId, where, inBackground=false, browserId=null)

Opens the homepage (also known as searchForm) of the specified search engine and records telemetry.

Arguments:

  • engineId (string)

  • where (string)

  • inBackground (boolean)

  • browserId (number) – The target browser’s id. Only used if where == current and the call isn’t coming from a content process. If it’s not specified and where == current, the currently selected tab is used.

UrlbarParentController.receiveResults(queryContext)

Receives results from a query.

Arguments:

  • queryContext (UrlbarQueryContext) – The query details.

UrlbarParentController.recordAutofillBackspace(url)

Records a backspace over an autofilled URL, which past a threshold blocks autofill for it. The bookkeeping and its Places write are parent-state, so the input hands the URL over here.

Arguments:

  • url (string) – The autofill result URL whose backspace is being recorded.

UrlbarParentController.recordAutofillDeletion()

Records that the user deleted a whole autofilled value.

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.recordSearch(options)

Records that a search is being loaded: bumps the search-count prefs, informs ASRouter, records search telemetry and adds the search query to form history. The parent-side counterpart to the content-side _recordSearch().

Arguments:

  • options (object)

  • options.engineId (string) – The id of the engine handling the search.

  • options.query (string)

  • options.searchSource (string) – Where the search originated from.

  • options.details (object) – The search action details, per BrowserSearchTelemetry.recordSearch().

  • options.browserId (number) – The id of the browser where the search is being opened; defaults to the selected browser.

  • options.opensInPrivateWindow (boolean) – Whether the search opens in a new private window, in which case it’s not added to form history. If this is false but the current window is private, it’s not added either.

UrlbarParentController.recordSearchForm(engineId)

Records a visit to an engine’s search form. The parent-side counterpart to the content-side BrowserSearchTelemetry.recordSearchForm() call; the engine is shipped by id and resolved here, and the source is this controller’s SAP.

Arguments:

  • engineId (string) – The id of the engine whose search form was visited.

UrlbarParentController.recordSearchInOpenedTab(searchData)

Records a search that opens in a new tab, against that tab’s browser. The load opens the tab right after this call; TabOpen fires synchronously, so the next-opened tab is the search tab. Reaching its browser is parent-only.

UrlbarParentController.recordSearchMode(searchMode)

Records entry into a search mode. The parent-side counterpart to the content-side BrowserSearchTelemetry.recordSearchMode() call.

Arguments:

  • searchMode (object) – The search mode being entered. See UrlbarInput.setSearchMode.

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.resolveFallbackNavigation(details)

Resolves the navigation for an Enter with no result available to pick, entirely parent-side: it fetches the heuristic result for the typed value, and if that fails (a corrupt profile) falls back to uriFixup. Both the query and uriFixup are parent-only, and the target browser’s per-tab data and navigation epoch can’t be read from a content urlbar, so this owns all of it and hands the content side only what it needs to pick or load.

The epoch guards against the browser navigating while the heuristic query awaited: for a current load, a changed epoch means the user moved on, so neither the pick nor the fixup load should happen.

Arguments:

  • details (object)

  • details.searchString (string) – The typed value to resolve.

  • details.where (string) – Where the result will open, per openTrustedLinkIn.

  • details.searchMode (object) – The input’s search mode, if any.

  • details.browserId (number) – The id of the browser committed at Enter; its per-tab data and navigation epoch are read here, defaulting to the selected browser.

Returns:

Promise.<object> – { heuristicResult } to pick, { fixup: { url, postData, keywordAsSent } } to load, or {} when the browser navigated in the meanwhile.

UrlbarParentController.resolveTargetBrowser(browserId)

Resolves the <browser> a browserId refers to. A content sender always targets its own tab, so its browserId is ignored; only a chrome sender resolves a pinned id globally.

Arguments:

  • browserId (number) – The browser id a chrome sender pinned, if any.

Returns:

MozBrowser – The target <browser>, or null if there’s nothing to resolve.

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.switchToTab(loadData)

Switches to a tab already showing the URL (or opens it), doing the tabbrowser bookkeeping and the follow-up history/open-tab writes that only the parent can: reading the previous tab and its split view, closing the previous tab if it was left empty, recording input history on success, and unregistering a stale open-tab entry on a miss.

Arguments:

  • loadData (object)

  • loadData.url (string) – The URL to switch to.

  • loadData.searchString (string) – The search string that produced the result, for input history.

  • loadData.userContextId (number) – The id of the container the target tab belongs to; 0 for the default container.

  • loadData.tabGroup (string) – The id of the tab group the target tab belongs to, or null for none.

  • loadData.heuristic (boolean) – Whether the result was the heuristic one.

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.