UrlbarView Reference

class UrlbarView(input)

Receives and displays address bar autocomplete results.

Arguments:

  • input (UrlbarInput) – The UrlbarInput instance belonging to this UrlbarView instance.

UrlbarView.UrlbarView
UrlbarView.isOpen

Whether the panel is open.

UrlbarView.selectedElement
UrlbarView.selectedResult
UrlbarView.visibleRowCount
UrlbarView.autoOpen(options)

This can be used to open the view automatically as a consequence of specific user actions. For Top Sites searches (without a search string) the view is opened only for mouse or keyboard interactions. If the user abandoned a search (there is a search string) the view is reopened, and we try to use cached results to reduce flickering, then a new query is started to refresh results.

Arguments:

  • options (object) – Options object

  • options.event (Event) – The event associated with the call to autoOpen.

  • options.suppressFocusBorder (boolean) – If true, we hide the focus border when the panel is opened. This is true by default to avoid flashing the border when the unfocused address bar is clicked.

Returns:

boolean – Whether the view was opened.

UrlbarView.clearSelection()

Clears selection, regardless of view status.

UrlbarView.close(options)

Closes the view, cancelling the query if necessary.

Arguments:

  • options (object) – Options object

  • options.elementPicked (boolean) – True if the view is being closed because a result was picked.

  • options.showFocusBorder (boolean) – True if the Urlbar focus border should be shown after the view is closed.

UrlbarView.getFirstSelectableElement()

Returns the first keyboard-selectable element in the view.

Returns:

Element – The first selectable element in the view.

UrlbarView.getLastSelectableElement()

Returns the last keyboard-selectable element in the view.

Returns:

Element – The last selectable element in the view.

UrlbarView.getResultAtIndex(index)
Arguments:

  • index (number) – The index from which to fetch the result.

Returns:

UrlbarResult – The result at index. Null if the view is closed or if there are no results.

UrlbarView.getResultFromElement(element)

Returns the result of the row containing the given element, or the result of the element if it itself is a row.

Arguments:

  • element (Element) – An element in the view.

Returns:

UrlbarResult – The result of the element’s row.

UrlbarView.handleEvent(event)

Passes DOM events for the view to the on_<event type> methods.

Arguments:

  • event (Event) – DOM event from the <view>.

UrlbarView.hideTemporarily()

Hide the popup that shows the Urlbar results. The popup is still considered “open”, this will not trigger abandonment telemetry but will not be shown to the user.

UrlbarView.invalidateResultMenuCommands()

Clears the result menu commands cache, removing the cached commands for all results. This is useful when the commands for one or more results change while the results remain in the view.

UrlbarView.onQueryResultRemoved(index)

Handles removing a result from the view when it is removed from the query, and attempts to select the new result on the same row.

This assumes that the result rows are in index order.

Arguments:

  • index (number) – The index of the result that has been removed.

UrlbarView.restoreVisibility()

Show the Urlbar results popup after being hidden by hideTemporarily

UrlbarView.resultIsSelected(result)
Arguments:

  • result (UrlbarResult) – A result.

Returns:

boolean – True if the given result is selected.

UrlbarView.selectBy(amount, options)

Moves the view selection forward or backward.

Arguments:

  • amount (number) – The number of steps to move.

  • options (object) – Options object

  • options.reverse (boolean) – Set to true to select the previous item. By default the next item will be selected.

  • options.userPressedTab (boolean) – Set to true if the user pressed Tab to select a result. Default false.

UrlbarView.shouldSpaceActivateSelectedElement()
Returns:

boolean – Whether the SPACE key should activate the selected element (if any) instead of adding to the input value.

static UrlbarView.addDynamicViewTemplate(name, viewTemplate)

Registers the view template for a dynamic result type. A view template is a plain object that describes the DOM subtree for a dynamic result type. When a dynamic result is shown in the urlbar view, its type’s view template is used to construct the part of the view that represents the result.

The specified view template will be available to the urlbars in all current and future browser windows until it is unregistered. A given dynamic result type has at most one view template. If this method is called for a dynamic result type more than once, the view template in the last call overrides those in previous calls.

Arguments:

  • name (string) – The view template will be registered for the dynamic result type with this name.

  • viewTemplate (object) – This object describes the DOM subtree for the given dynamic result type. It should be a tree-like nested structure with each object in the nesting representing a DOM element to be created. This tree-like structure is achieved using the children property described below. Each object in the structure may include the following properties: {string} name The name of the object. It is required for all objects in the structure except the root object and serves two important functions: (1) The element created for the object will automatically have a class named urlbarView-dynamic-${dynamicType}-${name}, where dynamicType is the name of the dynamic result type. The element will also automatically have an attribute “name” whose value is this name. The class and attribute allow the element to be styled in CSS. (2) The name is used when updating the view. See UrlbarProvider.getViewUpdate(). Names must be unique within a view template, but they don’t need to be globally unique. i.e., two different view templates can use the same names, and other DOM elements can use the same names in their IDs and classes. The name also suffixes the dynamic element’s ID: an element with name data will get the ID urlbarView-row-{unique number}-data. If there is no name provided for the root element, the root element will not get an ID. {string} tag The tag name of the object. It is required for all objects in the structure except the root object and declares the kind of element that will be created for the object: span, div, img, etc. {object} [attributes] An optional mapping from attribute names to values. For each name-value pair, an attribute is added to the element created for the object. The id attribute is reserved and cannot be set by the provider. Element IDs are passed back to the provider in getViewUpdate if they are needed. {array} [children] An optional list of children. Each item in the array must be an object as described here. For each item, a child element as described by the item is created and added to the element created for the parent object. {array} [classList] An optional list of classes. Each class will be added to the element created for the object by calling element.classList.add(). {boolean} [overflowable] If true, the element’s overflow status will be tracked in order to fade it out when needed. {string} [stylesheet] An optional stylesheet URL. This property is valid only on the root object in the structure. The stylesheet will be loaded in all browser windows so that the dynamic result type view may be styled.

static UrlbarView.removeDynamicViewTemplate(name)

Unregisters the view template for a dynamic result type.

Arguments:

  • name (string) – The view template will be unregistered for the dynamic result type with this name.