UrlbarProvider Reference

class UrlbarProvider()

Base class for a provider. The provider scope is to query a datasource and return results from it.

UrlbarProvider.deferUserSelection

Defines whether the view should defer user selection events while waiting for the first result from this provider.

Note: UrlbarEventBufferer has a timeout after which user events will be

processed regardless.

UrlbarProvider.name

Unique name for the provider, used by the context to filter on providers. By default, it will use the class name but it can also be overridden to use a different name. Not using a unique name will cause the newest registration to win.

UrlbarProvider.queryInstance

type: Query

This can be used by the provider to check the query is still running after executing async tasks:`  let instance = this.queryInstance;  await ...  if (instance != this.queryInstance) {    // Query was canceled or a new one started.    return;  }`

UrlbarProvider.type

The type of the provider, must be one of UrlbarShared.PROVIDER_TYPE.

UrlbarProvider.cancelQuery(_queryContext)

Cancels a running query,

Arguments:

  • _queryContext (UrlbarQueryContext) – the query context object to cancel query for.

UrlbarProvider.getPriority(_queryContext)

Gets the provider’s priority. Priorities are numeric values starting at zero and increasing in value. Smaller values are lower priorities, and larger values are higher priorities. For a given query, startQuery is called on only the active and highest-priority providers.

Arguments:

  • _queryContext (UrlbarQueryContext) – The query context object

Returns:

number – The provider’s priority for the given query.

UrlbarProvider.getResultCommands(_result, _isPrivate)

Gets the list of commands that should be shown in the result menu for a given result from the provider. All commands returned by this method should be handled by implementing onEngagement() with the possible exception of commands automatically handled by the urlbar, like “help”.

Arguments:

  • _result (UrlbarResult) – The menu will be shown for this result.

  • _isPrivate (boolean) – Whether the query was made in a private browsing context.

Returns:

Array.<UrlbarResultCommand>

UrlbarProvider.getViewTemplate(_result)

This is called only for dynamic result types.

Arguments:

  • _result (UrlbarResult) – The result whose view will be created.

Returns:

ViewTemplate – The view template describing the DOM to build for the result, or null if the provider doesn’t define one.

UrlbarProvider.getViewUpdate(_result, _controller)

This is called only for dynamic result types by the providers manager. It should return an object describing the view update that looks like this:

{
  nodeNameFoo: {
    attributes: {
      someAttribute: someValue,
    },
    style: {
      someStyleProperty: someValue,
      "another-style-property": someValue,
    },
    l10n: {
      id: someL10nId,
      args: someL10nArgs,
    },
    textContent: "some text content",
  },
  nodeNameBar: {
    ...
  },
  nodeNameBaz: {
    ...
  },
}

The object should contain a property for each element to update in the dynamic result type view. The names of these properties are the names declared in the view template of the dynamic result type; see UrlbarProvider.getViewTemplate(). The values are similar to the nested objects specified in the view template but not quite the same; see below. For each property, the element in the view subtree with the specified name is updated according to the object in the property’s value. If an element’s name is not specified, then it will not be updated and will retain its current state.

Arguments:

  • _result (UrlbarResult) – The result whose view will be updated.

  • _controller (UrlbarParentController) – The controller.

Returns:

object – A view update object as described above. The names of properties are the the names of elements declared in the view template. The values of properties are objects that describe how to update each element, and these objects may include the following properties, all of which are optional: {object} [attributes] A mapping from attribute names to values. Each name-value pair results in an attribute being added to the element. The id attribute is reserved and cannot be set by the provider. {Array} [classList] An array of CSS classes to set on the element. If this is defined, the element’s previous classes will be cleared first! {object} [dataset] Maps element dataset keys to values. Values should be strings with the following exceptions: undefined is ignored, and null causes the key to be removed from the dataset. {object} [style] A plain object that can be used to add inline styles to the element, like display: none. element.style is updated for each name-value pair in this object. {object} [l10n] An { id, args } object that will be passed to document.l10n.setAttributes(). {string} [textContent] A string that will be set as element.textContent.

UrlbarProvider.isActive(_queryContext, _controller)

Whether this provider should be invoked for the given context. If this method returns false, the providers manager won’t start a query with this provider, to save on resources.

Arguments:

  • _queryContext (UrlbarQueryContext) – The query context object

  • _controller (UrlbarParentController) – The current controller.

Returns:

Promise.<boolean> – Whether this provider should be invoked for the search.

UrlbarProvider.onAbandonment(_queryContext, _controller)

Called when the user abandons a search session without selecting a result. This could be due to losing focus on the urlbar, switching tabs, or other actions that imply the user is no longer actively engaging with the search suggestions. The method is called for all providers who have implemented this method and whose results were visible at the time of the abandonment.

Arguments:

  • _queryContext (UrlbarQueryContext) – The query context at the time of abandonment.

  • _controller (UrlbarParentController) – The associated controller.

UrlbarProvider.onBeforeSelection(_result, _element)

Called before a result from the provider is selected. See onSelection for details on what that means.

Arguments:

  • _result (UrlbarResult) – The result being selected.

  • _element (Element) – The selected element. Undefined in the message path. New providers should not use this parameter!

UrlbarProvider.onEngagement(_queryContext, _controller, _details)

Called when a user engages with a result in the urlbar. This is called for all providers who have implemented this method.

Arguments:

  • _queryContext (UrlbarQueryContext) – The engagement’s query context. It will always be defined for “engagement” and “abandonment”.

  • _controller (UrlbarParentController) – The associated controller.

  • _details (object) – This object is non-empty only when state is “engagement” or “abandonment”, and it describes the search string and engaged result. For “engagement”, it has the following properties: {UrlbarResult} result The engaged result. If a result itself was picked, this will be it. If an element related to a result was picked (like a button or menu command), this will be that result. This property will be present if and only if state == “engagement”, so it can be used to quickly tell when the user engaged with a result. {Element} element The picked DOM element. {boolean} isSessionOngoing True if the search session remains ongoing or false if the engagement ended it. Typically picking a result ends the session but not always. Picking a button or menu command may not end the session; dismissals do not, for example. {string} searchString The search string for the engagement’s query. {number} selIndex The index of the picked result. {string} selType The type of the selected result. See TelemetryEvent.record() in UrlbarParentController.sys.mjs. {string} provider The name of the provider that produced the picked result. For “abandonment”, only searchString is defined.

UrlbarProvider.onImpression(_state, _queryContext, _controller, _providerVisibleResults, _details)

Called for providers whose results are visible at the time of either engagement or abandonment. The method is called when a user actively interacts with a search result. This interaction could be clicking on a suggestion, using a keyboard to select a suggestion, or any other form of direct engagement with the results displayed. It is also called when a user decides to abandon the search session without engaging with any of the presented results. This is called for all providers who have implemented this method.

Arguments:

  • _state (string) – The state of the user interaction, either “engagement” or “abandonment”.

  • _queryContext (UrlbarQueryContext) – The current query context.

  • _controller (UrlbarParentController) – The associated controller.

  • _providerVisibleResults (Array.<{index: number, result: UrlbarResult}>) – Array of visible results at the time of either an engagement or abandonment event relevant to the provider. Each object in the array contains: - index: The position of the visible result within the original list visible results. - result: The visible result itself

  • _details (object|null) – If the impression is due to an engagement, this will be the details object that’s also passed to onEngagement(). Otherwise it will be null. See onEngagement() documentation for info.

UrlbarProvider.onSearchSessionEnd(_queryContext, _controller)

Called when a search session concludes regardless of how it ends - whether through engagement or abandonment or otherwise. This is called for all providers who have implemented this method.

Arguments:

  • _queryContext (UrlbarQueryContext) – The current query context.

  • _controller (UrlbarParentController) – The associated controller.

UrlbarProvider.onSelection(_result)

Called when a result from the provider is selected. “Selected” refers to the user highlighing the result with the arrow keys/Tab, before it is picked. onSelection is also called when a user clicks a result. In the event of a click, onSelection is called just before onEngagement. Note that this is called when heuristic results are pre-selected.

Arguments:

  • _result (UrlbarResult) – The result that was selected.

UrlbarProvider.startQuery(_queryContext, _addCallback, _controller)

Starts querying.

Note: Extended classes should return a Promise resolved when the provider

is done searching AND returning results.

Arguments:

  • _queryContext (UrlbarQueryContext) – The query context object

  • _addCallback ((provider: UrlbarProvider, result: UrlbarResult) => void) – Callback invoked by the provider to add a new result.

  • _controller (UrlbarParentController) – The current controller.

Returns:

void|Promise.<void>

UrlbarProvider.tryMethod(methodName, ...args)

Calls a method on the provider in a try-catch block and reports any error. Unlike most other provider methods, tryMethod is not intended to be overridden.

Arguments:

  • methodName (string) – The name of the method to call.

  • args (any) – The method arguments.

Returns:

any – The return value of the method, or undefined if the method throws an error.