UrlbarInputBase Reference

class UrlbarInputBase()

Implements the text input part of search access points. Each access point extends this class (e.g. UrlbarInput, SearchbarInput).

UrlbarInputBase._autofillPlaceholder

type: AutofillPlaceholder|null

UrlbarInputBase._keyDownEnterDeferred

type: PromiseWithResolvers<number | void> & { loadedContent?: boolean, inputEpoch?: number, } | null

Created on Enter keydown and resolved on keyup or blur, so that input is held back until the load has started.

UrlbarInputBase.addSearchEngineHelper

Manages the Add Search Engine contextual menu entries.

UrlbarInputBase.handlesOpenInCommands

Whether pickResult() implements the result menu’s commands for opening a result in a new tab or window.

UrlbarInputBase.isComposing

Whether an IME composition is in progress. Mirrors chrome-only editor.composing.

UrlbarInputBase.isSearchbarSAP

type: boolean

Whether this is a bar dedicated to search.

See UrlbarShared.isSearchbarSAP.

UrlbarInputBase.lastQueryContextPromise

type: Promise.<(void|UrlbarQueryContext)>

UrlbarInputBase.onSearchEngineUpdate
UrlbarInputBase.placeholder

type: typeof HTMLInputElement.prototype.placeholder

UrlbarInputBase.readOnly

type: boolean

UrlbarInputBase.searchMode
UrlbarInputBase.selectionEnd

type: typeof HTMLInputElement.prototype.selectionEnd

UrlbarInputBase.selectionStart

type: typeof HTMLInputElement.prototype.selectionStart

UrlbarInputBase.variantA

type: boolean

Whether this input shows layout variant A. New Tab’s registrant sets the attribute from the urlbar’s newtabVariantA Nimbus variable.

UrlbarInputBase.variantB

type: boolean

Whether this input shows layout variant B, with the search engine button on its own row above the input. New Tab’s registrant sets the attribute from the urlbar’s newtabVariantB Nimbus variable.

UrlbarInputBase.windowMode

Gets the window mode for telemetry.

UrlbarInputBase.fragment

type: DocumentFragment

UrlbarInputBase._autofillFirstResult(result)

Called by the controller when the first result of a new search is received. If it’s an autofill result, then it may need to be autofilled, subject to a few restrictions.

Arguments:

  • result (UrlbarResult) – The first result.

UrlbarInputBase._autofillValue(options)

Autofills a value into the input. The value will be autofilled regardless of the input’s current value.

Arguments:

  • options (AutofillPlaceholder) – The autofill options.

UrlbarInputBase._maybeAutofillPlaceholder(value)

Autofills the autofill placeholder string if appropriate, and determines whether autofill should be allowed for the new search started by an input event.

Arguments:

  • value (string) – The new search string.

Returns:

boolean – Whether autofill should be allowed in the new search.

UrlbarInputBase._maybeCanonizeURL(event, value)

If appropriate, this prefixes a search string with ‘www.’ and suffixes it with Services.locale.urlFixupSuffix prior to navigating.

Arguments:

  • event (Event) – The event that triggered this query.

  • value (string) – The search string that should be canonized.

Returns:

string – Returns the canonized URL if available and null otherwise.

UrlbarInputBase._on_dragover(event)

Handles dragover events for the input.

Arguments:

  • event (DragEvent)

UrlbarInputBase._on_drop(event)

Handles dropping of data on the input.

Arguments:

  • event (DragEvent)

UrlbarInputBase._recordSearch(options)

Records search telemetry for a search and adds it to form history.

Arguments:

  • options (object)

  • options.engine (PartialSearchEngine|SearchEngine) – The engine to record the query for.

  • options.query (string) – The search query.

  • options.event (Event) – The event that triggered this query.

  • options.where (string) – Where the search opens.

  • options.searchActionDetails (SearchActionDetails) – The details associated with this search query.

  • options.opensInPrivateWindow (boolean) – Whether the search opens in a new private window.

UrlbarInputBase._resetSearchState()

Resets some state so that searches from the user’s previous interaction with the input don’t interfere with searches from a new interaction.

UrlbarInputBase._searchModeForResult(result, entry="null")

Returns a search mode object if a result should enter search mode when selected.

Arguments:

  • result (UrlbarResult) – The result to check.

  • entry (string) – If provided, this will be recorded as the entry point into search mode. See setSearchMode() documentation for details.

Returns:

SearchModeInput – The search mode to enter, or null if search mode should not be entered.

UrlbarInputBase._setPlaceholder(engineName)

Sets the URLBar placeholder to either something based on the engine name, or the default placeholder.

Arguments:

  • engineName (string) – The name of the engine or null to use the default placeholder.

UrlbarInputBase._trimValue(val)

Shortens the given value, usually by removing http:// and trailing slashes.

Arguments:

  • val (string) – The string to be trimmed if it appears to be URI

Returns:

string – The trimmed string

UrlbarInputBase._updateSearchModeUI(searchMode)

Updates the UI so that search mode is either entered or exited.

Arguments:

  • searchMode (SearchMode) – The search mode to display, or null to exit search mode.

UrlbarInputBase.addContextMenuItems(itemSet)

Registers an item set with the text context menu, scoped to this input.

Arguments:

  • itemSet (object) – As passed to EditContextMenu.addItems(), minus matches.

UrlbarInputBase.afterTabSwitchFocusChange()

When switching tabs quickly, TabSelect sometimes happens before _adjustFocusAfterTabSwitch and due to the focus still being on the old tab, we end up flickering the results pane briefly.

UrlbarInputBase.confirmSearchMode()

Confirms the current search mode.

UrlbarInputBase.formatValue()

Applies styling to the text in the urlbar input, depending on the text.

UrlbarInputBase.getSearchMode(browser, confirmedOnly=false)

Addressbar: Gets the search mode for a specific browser instance. Searchbar: Gets the window-global search mode.

Arguments:

  • browser (MozBrowser) – The search mode for this browser will be returned. Pass the selected browser for the searchbar.

  • confirmedOnly (boolean) – Normally, if the browser has both preview and confirmed modes, preview mode will be returned since it takes precedence. If this argument is true, then only confirmed search mode will be returned, or null if search mode hasn’t been confirmed.

Returns:

SearchMode – Null if the browser/window is not in search mode.

UrlbarInputBase.getSearchSource(event)

Get search source for telemetry.

Arguments:

  • event (Event) – The event that triggered this query. This is not needed for urlbar.* telemetry.

Returns:

keyof typeof BrowserSearchTelemetry.KNOWN_SEARCH_SOURCES – The source name.

UrlbarInputBase.handleCommand(event=null)

Handles an event which might open text or a URL. If the event requires doing so, handleCommand forwards it to handleNavigation.

Arguments:

  • event (MouseEvent|KeyboardEvent) – The event triggering the open.

UrlbarInputBase.handleEmptyValueNavigation(_event)

Handles navigation when there is no URL to load. The base does nothing; subclasses such as the searchbar open the search engine page for the active or default engine.

Arguments:

  • _event (Event) – The event triggering the open.

UrlbarInputBase.handleEvent(event)

Passes DOM events to the _on_<event type> methods.

Arguments:

  • event (Event) – The event to handle.

UrlbarInputBase.handleNavigation(options)

Handles an event which would cause a URL or text to be opened.

Arguments:

  • options (object) – Options for the navigation.

  • options.event (MouseEvent|KeyboardEvent) – The event triggering the open.

  • options.oneOffParams (HandleNavigationOneOffParams) – Optional. Pass if this navigation was triggered by a one-off. Practically speaking, UrlbarSearchOneOffs passes this when the user holds certain key modifiers while picking a one-off. In those cases, we do an immediate search using the one-off’s engine instead of entering search mode.

  • options.triggeringPrincipal (object) – The principal that the action was triggered from.

UrlbarInputBase.handoff(searchString, searchEngine, newtabSessionId)

Called by inputs that resemble search boxes, but actually hand input off to the Urlbar. We use these fake inputs on the new tab page and about:privatebrowsing.

Arguments:

  • searchString (string) – The search string to use.

  • searchEngine (SearchEngine) – Optional. If included and the right prefs are set, we will enter search mode when handing searchString from the fake input to the Urlbar.

  • newtabSessionId (string) – Optional. The id of the newtab session that handed off this search.

UrlbarInputBase.initSapContextMenuItems()

Hook for subclass-specific context-menu items. Default no-op.

UrlbarInputBase.makeURIReadable(uri)

Converts an internal URI (e.g. a URI with a username or password) into one which we can expose to the user.

Arguments:

  • uri (nsIURI) – The URI to be converted

Returns:

nsIURI – The converted, exposable URI

UrlbarInputBase.maybeConfirmSearchModeFromResult(options)

Confirms search mode and starts a new search if appropriate for the given result. See also _searchModeForResult.

Arguments:

  • options (object) – Options object.

  • options.entry (string) – If provided, this will be recorded as the entry point into search mode. See setSearchMode documentation for details.

  • options.result (UrlbarResult) – The result to confirm. Defaults to the currently selected result.

  • options.checkValue (boolean) – If true, the trimmed input value must equal the result’s keyword in order to enter search mode.

  • options.startQuery (boolean) – If true, start a query after entering search mode. Defaults to true.

Returns:

boolean – True if we entered search mode and false if not.

UrlbarInputBase.onFirstResult(queryContext)

Invoked by the controller when the first result changed.

Arguments:

  • queryContext (UrlbarQueryContext) – The context of the query the result belongs to.

UrlbarInputBase.onLocationChange(browser, webProgress, request, locationURI)

Function for tabs progress listener.

Arguments:

  • browser (nsIBrowser)

  • webProgress (nsIWebProgress) – The nsIWebProgress instance that fired the notification.

  • request (nsIRequest) – The associated nsIRequest. This may be null in some cases.

  • locationURI (nsIURI) – The URI of the location that is being loaded.

UrlbarInputBase.onPrefChanged(pref)

Called when a urlbar or urlbar related pref changes.

Arguments:

  • pref (string) – The name of the pref. Relative to browser.urlbar for urlbar prefs.

UrlbarInputBase.openSearchEnginePage(value, options)

If value is non-empty: open the search engine result page (SERP) for value. If value is empty: open the search engine home page (searchForm).

Arguments:

  • value (string) – The search term or empty string to open homepage.

  • options (object)

  • options.searchEngine (PartialSearchEngine)

  • options.event (Event)

  • options.where (string)

  • options.inBackground (boolean)

UrlbarInputBase.pickElement(element, event)

Called when an element of the view is picked.

Arguments:

  • element (HTMLElement) – The element that was picked.

  • event (Event) – The event that picked the element.

UrlbarInputBase.pickResult(options)

Called when a result is picked.

Arguments:

  • options (object)

  • options.result (UrlbarResult) – The result that was picked.

  • options.event (Event) – The event that picked the result.

  • options.element (HTMLElement) – The picked view element, if available.

  • options.browserId (number) – The id of the browser to load into, for a load that resolves asynchronously and must target the tab selected when it was committed. Defaults to the parent resolving the selected browser at load time.

UrlbarInputBase.removeHiddenFocus(forceSuppressFocusBorder=false)

Restore focus styles. This is used by Activity Stream and about:privatebrowsing for search hand-off.

Arguments:

  • forceSuppressFocusBorder (boolean) – Set true to suppress-focus-border attribute if this flag is true.

UrlbarInputBase.restoreSearchModeState()

Restores the current browser search mode from a previously stored state.

UrlbarInputBase.sapConnectedCallback()

Hook for subclass-specific work at the end of connection. Default no-op.

UrlbarInputBase.sapDisconnectedCallback()

Hook for subclass-specific work at the start of disconnection. Default no-op.

UrlbarInputBase.sapInit()

Hook for subclass-specific initialization work, called during #init. Default no-op.

UrlbarInputBase.search(value, options)

Sets the input’s value, starts a search, and opens the view.

Arguments:

  • value (string) – The input’s value will be set to this value, and the search will use it as its query.

  • options (object) – Object options

  • options.searchEngine (PartialSearchEngine|SearchEngine) – Search engine to use when the search is using a known alias.

  • options.searchModeEntry (string) – If provided, we will record this parameter as the search mode entry point in Telemetry. Consumers should provide this if they expect their call to enter search mode.

  • options.focus (boolean) – If true, the urlbar will be focused. If false, the focus will remain unchanged.

  • options.startQuery (boolean) – If true, start query to show urlbar result by fireing input event. If false, not fire the event.

UrlbarInputBase.searchModeForToken(token)

Returns a search mode object if a token should enter search mode when typed. This does not handle engine aliases.

Arguments:

  • token (string) – A restriction token to convert to search mode.

Returns:

SearchModeInput – Null if search mode should not be entered.

UrlbarInputBase.searchModeShortcut()

Enters search mode with the default engine.

UrlbarInputBase.setHiddenFocus()

Focus without the focus styles. This is used by Activity Stream and about:privatebrowsing for search hand-off.

UrlbarInputBase.setPageProxyState(state, updatePopupNotifications, forceUnifiedSearchButtonAvailable=false)

Updates the user interface to indicate whether the URI in the address bar is different than the loaded page, because it’s being edited or because a search result is currently selected and is displayed in the location bar.

Arguments:

  • state (string) – The string “valid” indicates that the security indicators and other related user interface elments should be shown because the URI in the location bar matches the loaded page. The string “invalid” indicates that the URI in the location bar is different than the loaded page.

  • updatePopupNotifications (boolean) – Indicates whether we should update the PopupNotifications visibility due to this change, otherwise avoid doing so as it is being handled somewhere else.

  • forceUnifiedSearchButtonAvailable (boolean) – If this parameter is true, force to make Unified Search Button available. Otherwise, the availability will be depedent on the proxy state. Default value is false.

UrlbarInputBase.setResultForCurrentValue(result)

The input keeps track of the result associated with the current input value. This result can be set by calling either setValueFromResult or this method. Use this method when you need to set the result without also setting the input value. This can be the case when either the selection is cleared and no other result becomes selected, or when the result is the heuristic and we don’t want to modify the value the user is typing.

Arguments:

  • result (UrlbarResult) – The result to associate with the current input value.

UrlbarInputBase.setSearchMode(searchMode, browser)

Addressbar: Sets the search mode for a specific browser instance. Searchbar: Sets the window-global search mode. If the given browser is selected, then this will also enter search mode.

Arguments:

  • searchMode (SearchModeInput) – The search mode to enter, or null to exit search mode.

  • browser (MozBrowser) – The browser for which to set search mode. Pass the selected browser for the searchbar.

UrlbarInputBase.setURI(options)

Sets the URI to display in the location bar.

Arguments:

  • options (object)

  • options.uri (nsIURI) – If this is unspecified, the current URI will be used.

  • options.dueToTabSwitch (boolean) – Whether this is being called due to switching tabs.

  • options.dueToSessionRestore (boolean) – Whether this is being called due to session restore.

  • options.hideSearchTerms (boolean) – True if userTypedValue should not be overidden by search terms and false otherwise.

  • options.isSameDocument (boolean) – Whether the caller loaded a new document or not (e.g. location change from an anchor scroll or a pushState event).

UrlbarInputBase.setUnifiedSearchButtonAvailability(available)

Set Unified Search Button availability.

Arguments:

  • available (boolean) – If true Unified Search Button will be available.

UrlbarInputBase.setValue(val, options)

Sets the input field value.

Arguments:

  • val (string) – The new value to set.

  • options (object) – Options for setting.

  • options.allowTrim (boolean) – Whether the value can be trimmed.

  • options.untrimmedValue (string) – Override for this._untrimmedValue.

  • options.valueIsTyped (boolean) – Override for this.valueIsTyped.

  • options.actionType (string) – Value for the actiontype attribute.

Returns:

string – The set value.

UrlbarInputBase.setValueFromResult(options)

Called by the view when moving through results with the keyboard, and when picking a result. This sets the input value to the value of the result and invalidates the pageproxystate. It also sets the result that is associated with the current input value. If you need to set this result but don’t want to also set the input value, then use setResultForCurrentValue.

Arguments:

  • options (object) – Options.

  • options.result (UrlbarResult) – The result that was selected or picked, null if no result was selected.

  • options.event (Event) – The event that picked the result.

  • options.urlOverride (string) – Normally the URL is taken from result.payload.url, but if urlOverride is specified, it’s used instead. See #getValueFromResult().

  • options.element (HTMLElement) – The element that was selected or picked, if available. For results that have multiple selectable children, the value may be taken from a child element rather than the result. See #getValueFromResult().

Returns:

boolean – Whether the value has been canonized

UrlbarInputBase.startQuery(options)

Starts a query based on the current input value.

Arguments:

  • options (object) – Object options

  • options.allowAutofill (boolean) – Whether or not to allow providers to include autofill results.

  • options.autofillIgnoresSelection (boolean) – Normally we autofill only if the cursor is at the end of the string, if this is set we’ll autofill regardless of selection.

  • options.searchString (string) – The search string. If not given, the current input value is used. Otherwise, the current input value must start with this value.

  • options.resetSearchState (boolean) – If this is the first search of a user interaction with the input, set this to true (the default) so that search-related state from the previous interaction doesn’t interfere with the new interaction. Otherwise set it to false so that state is maintained during a single interaction. The intended use for this parameter is that it should be set to false when this method is called due to input events.

  • options.event (event) – The user-generated event that triggered the query, if any. If given, we will record engagement event telemetry for the query.

  • options.interactionType (string) – An explicit engagement interaction type for the query, used in preference to one derived from the event (e.g. “returned” when reopening a search).

UrlbarInputBase.updatePlaceholder()

Updates the urlbar placeholder based on the default engine.

UrlbarInputBase.updatePopover()

Keeps the view’s popover in the top layer, and the popover-open attribute set, for as long as the view is open. popover-open says the sheet the background paints is bigger than the input.

UrlbarInputBase.updateTextOverflow()

Invoked on overflow/underflow/scrollend events to update attributes related to the input text directionality. Overflow fade masks use these attributes to appear at the proper side of the urlbar.