UrlbarView Reference

class UrlbarView(input)

Receives and displays address bar autocomplete results.

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

UrlbarView._addTextContentWithHighlights(parentNode, textContent, highlights)

Adds text content to a node, placing substrings that should be highlighted inside <em> nodes.

Arguments
  • parentNode (Node()) – The text content will be added to this node.

  • textContent (string()) – The text content to give the node.

  • highlights (array()) – The matches to highlight in the text.

UrlbarView._cacheL10nIDArgsForSearchService()

A helper for l10n string caching that returns { id, args } objects for strings that depend on the search service.

Returns

array – Array of { id, args } objects, possibly empty.

UrlbarView._cacheL10nStrings()

Caches some l10n strings used by the view. Strings that are already cached are not cached again.

UrlbarView._fillTailSuggestionPrefix(item, result)

Adds markup for a tail suggestion prefix to a row.

Arguments
  • item (Node()) – The node for the result row.

  • result (UrlbarResult()) – A UrlbarResult representing a tail suggestion.

UrlbarView._getFirstSelectableElement()

Returns the first selectable element in the view.

Returns

Element – The first selectable element in the view.

UrlbarView._getLastSelectableElement()

Returns the last selectable element in the view.

Returns

Element – The last selectable element in the view.

UrlbarView._getNextSelectableElement(element)

Returns the next selectable element after the given element. If the element is the last selectable element, returns null.

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

Returns

Element – The next selectable element after element or null if element is the last selectable element.

UrlbarView._getPreviousSelectableElement(element)

Returns the previous selectable element before the given element. If the element is the first selectable element, returns null.

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

Returns

Element – The previous selectable element before element or null if element is the first selectable element.

UrlbarView._getRowFromElement(element)
Arguments
  • element (Element()) – An element that is potentially a row or descendant of a row.

Returns

Element – The row containing element, or element itself if it is a row.

UrlbarView._getSelectedRow()

Returns the currently selected row. Useful when this._selectedElement may be a non-row element, such as a descendant element of RESULT_TYPE.TIP.

Returns

Element – The currently selected row, or ancestor row of the currently selected item.

UrlbarView._isElementVisible(element)

Returns true if the given element and its row are both visible.

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

Returns

boolean – True if the given element and its row are both visible.

UrlbarView._isSelectableElement(element)

Returns true if the given element is selectable.

Arguments
  • element (Element()) – The element to test.

Returns

boolean – True if the element is selectable and false if not.

UrlbarView._pickSearchTipIfPresent(event)

If the view is open and showing a single search tip, this method picks it and closes the view. This counts as an engagement, so this method should only be called due to user interaction.

Arguments
  • event (event()) – The user-initiated event for the interaction. Should not be null.

Returns

boolean – True if this method picked a tip, false otherwise.

UrlbarView._removeElementL10n(element, options)

Removes textContent and attributes set by _setElementL10n.

Arguments
  • element (Element()) –

  • options.attribute (string()) – If you passed an attribute to _setElementL10n, then pass it here too.

UrlbarView._resultIsSearchSuggestion(result)

Whether a result is a search suggestion.

Arguments
  • result (UrlbarResult()) – The result to examine.

Returns

boolean – Whether the result is a search suggestion.

UrlbarView._rowCanUpdateToResult(rowIndex, result, seenSearchSuggestion)

Checks whether the given row index can be update to the result we want to apply. This is used in _updateResults to avoid flickering of results, by reusing existing rows.

Arguments
  • rowIndex (number()) – Index of the row to examine.

  • result (UrlbarResult()) – The result we’d like to apply.

  • seenSearchSuggestion (boolean()) – Whether the view update has encountered an existing row with a search suggestion result.

Returns

boolean – Whether the row can be updated to this result.

UrlbarView._rowLabel(row, currentLabel)

Returns the group label to use for a row. Designed to be called iteratively over each row.

Arguments
  • row (Element()) – A row in the view.

  • currentLabel (object()) – The current group label during row iteration.

Returns

object – If the current row should not have a label, returns null. Otherwise returns an l10n object for the label’s l10n string: { id, args }

UrlbarView._setElementL10n(element, options)

Sets an element’s textContent or attribute to a cached l10n string. If the string isn’t cached, then this falls back to the async l10n.setAttributes using the given l10n ID and args. The string will pop in as a result, but there’s no way around it.

Arguments
  • element (Element()) –

  • options.id (string()) – The l10n string ID.

  • options.args (object()) – The l10n string arguments.

  • options.attribute (string()) – If you’re setting an attribute string, then pass the name of the attribute. In that case, the string in the Fluent file should define a value for the attribute, like “.foo = My value for the foo attribute”. If you’re setting the element’s textContent, then leave this undefined.

UrlbarView._setResultTitle(result, titleNode)

Sets result’s title in titleNode’s DOM.

Arguments
  • result (UrlbarResult()) – The result for which the title is being set.

  • titleNode (Node()) – The DOM node for the result’s tile.

UrlbarView._updateIndices()

Performs a final pass over all rows in the view after a view update, stale rows are removed, and other changes to the number of rows. Sets rowIndex on each result, updates row labels, and performs other tasks that must be deferred until all rows have been updated.

UrlbarView.autoOpen(event, suppressFocusBorder)

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
  • event (Event()) – The event associated with the call to autoOpen.

  • 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(elementPicked, showFocusBorder)

Closes the view, cancelling the query if necessary.

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

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

UrlbarView.getClosestSelectableElement(element)

Returns the element closest to the given element that can be selected/picked. If the element itself can be selected, it’s returned. If there is no such element, null is returned.

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

Returns

Element – The closest element that can be picked including the element itself, or null if there is no such element.

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.isOpen

Whether the panel is open.

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.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.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.selectedElement
UrlbarView.selectedResult
UrlbarView.visibleElementCount
UrlbarView.visibleRowCount
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(). {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.

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.