Options
All
  • Public
  • Public/Protected
  • All
Menu

PrimeFaces AutoComplete Widget

AutoComplete provides live suggestions while the user is entering text

Type parameters

Hierarchy

Index

Constructors

constructor

  • Creates a new instance of this widget. Please note that you should NOT override this constructor. Instead, override the init method, which is called at the end of the constructor once the instance is created.

    Type parameters

    Parameters

    • cfg: PartialWidgetCfg<TCfg>

      The widget configuration to be used for this widget instance. This widget configuration is usually created on the server by the javax.faces.render.Renderer for this component.

    Returns AutoComplete<TCfg>

Properties

active

active: boolean

Whether the autocomplete is active.

Optional cache

cache?: Record<string, string>

The cache for the results of an autocomplete search.

Optional cacheTimeout

cacheTimeout?: number

The set-interval timer ID for the cache timeout.

cfg

cfg: PartialWidgetCfg<TCfg>

The configuration of this widget instance. Please note that no property is guaranteed to be present, you should always check for undefined before accessing a property. This is partly because the value of a property is not transmitted from the server to the client when it equals the default.

Optional checkMatchedItem

checkMatchedItem?: boolean

Whether the click event is fired on the selected items when a blur occurs.

Optional colspan

colspan?: number

Column span count for the options in the overlay panel with the available completion items.

Optional currentGroup

currentGroup?: string

Current option group when creating the options in the overlay with the available completion items.

currentInputValue

currentInputValue: string

Current value in the input field where the user can search for completion items.

Optional currentItems

currentItems?: string[]

Currently selected items, when forceSelection is enabled.

Optional currentText

currentText?: string

Text currently entered in the input field.

destroyListeners

Array of registered listeners invoked when this widget is destroyed. You should normally not use modify this directly, use addDestroyListener instead.

dropdown

dropdown: JQuery<HTMLElement>

The DOM element for the container with the dropdown suggestions.

Optional hideOverlayHandler

hideOverlayHandler?: UnbindCallback

Unbind callback for the hide overlay handler.

hinput

The DOM element for the hidden input with the selected value.

id

id: string | string[]

The client-side ID of this widget, with all parent naming containers, such as myForm:myWidget. This is also the ID of the container HTML element for this widget. In case the widget needs multiple container elements (such as Paginator), this may also be an array if IDs.

input

The DOM element for the input element.

inputContainer

inputContainer: JQuery<HTMLElement>

When multiple mode is enabled that allows multiple items to be selected: The DOM element of the container with the input element used to enter text and search for an item to select.

isDynamicLoaded

isDynamicLoaded: boolean

If dynamic loading is enabled, whether the content was loaded already.

Optional isSearchWithDropdown

isSearchWithDropdown?: boolean

Whether to use a drop down menu when searching for completion options.

isTabPressed

isTabPressed: boolean

Whether the tab key is currently pressed.

Optional itemClick

itemClick?: boolean

Whether an item was clicked.

Optional itemContainer

itemContainer?: JQuery<HTMLElement>

The DOM element for the container with the suggestion items.

Optional itemSelectedWithEnter

itemSelectedWithEnter?: boolean

Whether an item was selected via the enter key.

Optional items

The DOM elements for the suggestion items.

itemtip

The DOM element for the tooltip of a suggestion item.

jq

The jQuery instance of the container element of this widget. In case id is an array, it will contain multiple elements. Please note that some widgets have got not DOM elements at all, in this case this will be an empty jQuery instance.

jqId

jqId: string

A CSS selector for the container element (or elements, in case id is an array) of this widget, This is usually an ID selector (that is properly escaped). You can select the container element or elements like this: $(widget.jqId).

Optional multiItemContainer

multiItemContainer?: JQuery<HTMLElement>

The DOM element for the container with multiple selection items.

panel

The DOM element for the overlay panel with the suggestion items.

panelId

panelId: string

The client ID of the overlay panel with the suggestion items.

placeholder

placeholder: string

Placeholder shown in the input field when no text is entered.

Optional preventInputChangeEvent

preventInputChangeEvent?: boolean

Whether to suppress the change event when the input's value changes.

Optional previousText

previousText?: string

Text previously entered in the input field.

Optional querying

querying?: boolean

Whether an AJAX request for the autocompletion items is currently in progress.

refreshListeners

Array of registered listeners invoked when this widget is refreshed. You should normally not use modify this directly, use addRefreshListener instead.

Optional resizeHandler

resizeHandler?: UnbindCallback

Unbind callback for the resize handler.

Optional scrollHandler

scrollHandler?: UnbindCallback

Unbind callback for the scroll handler.

status

The DOM element for the autocomplete status ARIA element.

suppressInput

suppressInput: boolean

Whether key input events should be ignored currently.

Optional timeout

timeout?: number

Timeout ID for the timer used to clear the autocompletion cache in regular intervals.

touchToDropdownButton

touchToDropdownButton: boolean

Whether a touch is made on the dropdown button.

Optional transition

transition?: null | CssTransitionHandler

Handler for CSS transitions used by this widget.

widgetVar

widgetVar: string

The name of the widget variables of this widget. The widget variable can be used to access a widget instance by calling PF('myWidgetVar').

wrapperEndTag

wrapperEndTag: string

The finishing HTML with the wrapper element of the suggestions box.

wrapperStartTag

wrapperStartTag: string

The starting HTML with the wrapper element of the suggestions box.

Methods

activate

  • activate(): void
  • Activates search behavior.

    Returns void

addDestroyListener

  • Lets you register a listener that is called before the component is destroyed.

    When an AJAX call is made and this component is updated, the DOM element is replaced with the newly rendered content. When the element is removed from the DOM by the update, the DOM element is detached from the DOM and all destroy listeners are called. This makes it possible to add listeners from outside the widget code.

    If you call this method twice with the same listener, it will be registered twice and later also called twice.

    Note that for this to work, you must not override the destroy method; or if you do, call super.

    Also, after this widget was detached is done, all destroy listeners will be unregistered.

    since

    7.0

    Parameters

    Returns void

addItem

  • Add the given suggestion item.

    Parameters

    Returns void

addRefreshListener

  • When an AJAX call is made and this component is updated, the DOM element is replaced with the newly rendered content. However, no new instance of the widget is created. Instead, after the DOM element was replaced, all refresh listeners are called. This makes it possible to add listeners from outside the widget code.

    If you call this method twice with the same listener, it will be registered twice and later also called twice.

    Note that for this to work, you must not override the refresh method; or if you do, call super.

    Also, after the refresh is done, all refresh listeners will be deregistered. If you added the listeners from within this widget, consider adding the refresh listeners not only in the init method, but also again in the refresh method after calling super.

    since

    7.0.0

    Parameters

    Returns void

alignPanel

  • alignPanel(): void
  • Aligns (positions) the overlay panel that shows the found suggestions.

    Returns void

Private appendPanel

  • appendPanel(): void
  • Appends the overlay panel to the DOM.

    Returns void

Private bindDropdownEvents

  • bindDropdownEvents(): void
  • Sets up all event listeners for the dropdown menu.

    Returns void

Private bindDynamicEvents

  • bindDynamicEvents(): void
  • Sets up all event listeners for mouse and click events.

    Returns void

Private bindKeyEvents

  • bindKeyEvents(): void
  • Sets up all keyboard related event listeners.

    Returns void

Private bindPanelEvents

  • bindPanelEvents(): void
  • Sets up all panel event listeners

    Returns void

Private bindStaticEvents

  • bindStaticEvents(): void
  • Sets up all global event listeners for the overlay.

    Returns void

callBehavior

  • Each widget may have one or several behaviors attached to it. This method calls all attached behaviors for the given event name. In case no such behavior exists, this method does nothing and returns immediately.

    A behavior is a way for associating client-side scripts with UI components that opens all sorts of possibilities, including client-side validation, DOM and style manipulation, keyboard handling, and more. When the behavior is triggered, the configured JavaScript gets executed.

    Behaviors are often, but not necessarily, AJAX behavior. When triggered, it initiates a request the server and processes the response once it is received. This enables several features such as updating or replacing elements dynamically. You can add an AJAX behavior via <p:ajax event="name" actionListener="#{...}" onstart="..." />.

    since

    7.0

    Parameters

    • event: string

      The name of an event to call.

    • Optional ext: Partial<ConfigurationExtender>

      Additional configuration that is passed to the AJAX request for the server-side callback.

    Returns void

clear

  • clear(): void
  • Clears the input field.

    Returns void

Private clearCache

  • clearCache(): void
  • Clears the cache with the results of an autocomplete search.

    Returns void

close

  • close(): void
  • Hides suggested items menu.

    Returns void

deactivate

  • deactivate(): void
  • Deactivates search behavior.

    Returns void

Private deleteTimeout

  • deleteTimeout(): void
  • Clears the set-timeout timer for the autocomplete search.

    Returns void

destroy

  • destroy(): void
  • Will be called after an AJAX request if the widget container will be detached.

    When an AJAX call is made and this component is updated, the DOM element is replaced with the newly rendered content. When the element is removed from the DOM by the update, the DOM element is detached from the DOM and this method gets called.

    Please note that instead of overriding this method, you should consider adding a destroy listener instead via addDestroyListener. This has the advantage of letting you add multiple listeners, and makes it possible to add additional listeners from code outside this widget.

    By default, this method just calls all destroy listeners.

    Returns void

disable

  • disable(): void
  • Disables the input field.

    Returns void

Private disableDropdown

  • disableDropdown(): void
  • Disables the dropdown menu.

    Returns void

Private displayAriaStatus

  • displayAriaStatus(text: string): void
  • Adds the given text to the ARIA status label element.

    Parameters

    • text: string

      Label text to display.

    Returns void

enable

  • enable(): void
  • Enables the input field.

    Returns void

Private enableDropdown

  • enableDropdown(): void
  • Enables the dropdown menu.

    Returns void

Private fetchItems

  • fetchItems(): void
  • Fetches the suggestion items for the current query from the server.

    Returns void

Private findWrapperTag

  • Finds and sets the wrapper HTML snippets on this instance.

    Parameters

    • wrapper: JQuery<HTMLElement>

      Wrapper element with the suggestions fetched from the server.

    Returns void

Private fireClearEvent

  • fireClearEvent(): void
  • Triggers the behavior for when the input was cleared.

    Returns void

getBehavior

  • getBehavior(name: string): null | Behavior
  • Each widget may have one or several behaviors attached to it. This method returns the callback function for the given event.

    Note: Do not call the method directly, the recommended way to invoke a behavior is via callBehavior.

    A behavior is a way for associating client-side scripts with UI components that opens all sorts of possibilities, including client-side validation, DOM and style manipulation, keyboard handling, and more. When the behavior is triggered, the configured JavaScript gets executed.

    Behaviors are often, but not necessarily, AJAX behavior. When triggered, it initiates a request the server and processes the response once it is received. This enables several features such as updating or replacing elements dynamically. You can add an AJAX behavior via <p:ajax event="name" actionListener="#{...}" onstart="..." />.

    Parameters

    • name: string

      The name of an event for which to retrieve the behavior.

    Returns null | Behavior

    The behavior with the given name, or null if no such behavior exists.

Private getGroupItem

  • Creates the grouped suggestion item for the given parameters.

    Parameters

    • group: string

      A group where to look for the item.

    • container: JQuery<HTMLElement>

      Container element of the group.

    • tooltip: string

      Optional tooltip for the group item.

    Returns JQuery<HTMLElement>

    The newly created group item.

getJQ

  • Each widget has got a container element, this method returns that container. This container element is usually also the element whose ID is the client-side ID of the JSF component.

    Returns JQuery<HTMLElement>

    The jQuery instance representing the main HTML container element of this widget.

getParentForm

  • Gets the closest parent form for this widget.

    since

    10.0.0

    Returns JQuery<HTMLElement>

    A JQuery instance that either contains the form when found, or an empty JQuery instance when the form could not be found.

getParentFormId

  • getParentFormId(): undefined | string
  • Gets the closest parent form ID for this widget lazily so it can be used in AJAX requests.

    since

    10.0.0

    Returns undefined | string

    Either the form ID or undefined if no form can be found.

Private groupItems

  • groupItems(): void
  • Takes the available suggestion items and groups them.

    Returns void

Private handleViewportChange

  • handleViewportChange(): void
  • Fired when the browser viewport is resized or scrolled. In Mobile environment we don't want to hider the overlay we want to re-align it. This is because on some mobile browser the popup may force the browser to trigger a resize immediately and close the overlay. See GitHub #7075.

    Returns void

hasBehavior

  • hasBehavior(event: string): boolean
  • Each widget may have one or several behaviors attached to it. This method checks whether this widget has got at least one behavior associated with given event name.

    A behavior is a way for associating client-side scripts with UI components that opens all sorts of possibilities, including client-side validation, DOM and style manipulation, keyboard handling, and more. When the behavior is triggered, the configured JavaScript gets executed.

    Behaviors are often, but not necessarily, AJAX behavior. When triggered, it initiates a request the server and processes the response once it is received. This enables several features such as updating or replacing elements dynamically. You can add an AJAX behavior via <p:ajax event="name" actionListener="#{...}" onstart="..." />.

    Parameters

    • event: string

      The name of an event to check.

    Returns boolean

    true if this widget has the given behavior, false otherwise.

Private hide

  • hide(): void
  • Hides the panel with the suggestions.

    Returns void

init

  • A widget class should not declare an explicit constructor, the default constructor provided by this base widget should be used. Instead, override this initialize method which is called after the widget instance was constructed. You can use this method to perform any initialization that is required. For widgets that need to create custom HTML on the client-side this is also the place where you should call your render method.

    Please make sure to call the super method first before adding your own custom logic to the init method:

    PrimeFaces.widget.MyWidget = PrimeFaces.widget.BaseWidget.extend({
    init: function(cfg) {
    this._super(cfg);
    // custom initialization
    }
    });
    override

    Parameters

    • cfg: PartialWidgetCfg<TCfg>

      The widget configuration to be used for this widget instance. This widget configuration is usually created on the server by the javax.faces.render.Renderer for this component.

    Returns void

Private initCache

  • initCache(): void
  • Initializes the cache that stores the retrieved suggestions for a search term.

    Returns void

Private invokeEmptyMessageBehavior

  • invokeEmptyMessageBehavior(): void
  • Invokes the appropriate behavior for when empty message was selected.

    Returns void

Private invokeItemSelectBehavior

  • invokeItemSelectBehavior(itemValue: string): void
  • Invokes the appropriate behavior for when a suggestion item was selected.

    Parameters

    • itemValue: string

      Value of the selected item.

    Returns void

Private invokeItemUnselectBehavior

  • invokeItemUnselectBehavior(itemValue: string): void
  • Invokes the appropriate behavior when a suggestion item was unselected.

    Parameters

    • itemValue: string

      Value of the unselected item.

    Returns void

Private invokeMoreTextBehavior

  • invokeMoreTextBehavior(): void
  • Invokes the appropriate behavior for when more text was selected.

    Returns void

isDetached

  • isDetached(): boolean
  • Checks if this widget is detached, ie whether the HTML element of this widget is currently contained within the DOM (the HTML body element). A widget may become detached during an AJAX update, and it may remain detached in case the update removed this component from the component tree.

    Returns boolean

    true if this widget is currently detached, or false otherwise.

isValid

  • isValid(value: string, shouldFireClearEvent?: boolean): undefined | boolean
  • Checks whether the given value is part of the available suggestion items.

    Parameters

    • value: string

      A value to check.

    • Optional shouldFireClearEvent: boolean

      true if clear event should be fired.

    Returns undefined | boolean

    Whether the given value matches a value in the list of available suggestion items; or undefined if AutoCompleteCfg.forceSelection is set to false.

Private processKeyEvent

  • Callback for when a key event occurred.

    Parameters

    Returns void

refresh

  • Used in ajax updates, reloads the widget configuration.

    When an AJAX call is made and this component is updated, the DOM element is replaced with the newly rendered content. However, no new instance of the widget is created. Instead, after the DOM element was replaced, this method is called with the new widget configuration from the server. This makes it possible to persist client-side state during an update, such as the currently selected tab.

    Please note that instead of overriding this method, you should consider adding a refresh listener instead via addRefreshListener. This has the advantage of letting you add multiple listeners, and makes it possible to add additional listeners from code outside this widget.

    By default, this method calls all refresh listeners, then reinitializes the widget by calling the init method.

    override

    Parameters

    Returns void

    The value as returned by the init method, which is often undefined.

removeAllItems

  • removeAllItems(): void
  • Removes all items if in multiple mode.

    Returns void

removeItem

  • Removes the given suggestion item.

    Parameters

    Returns void

removeScriptElement

  • removeScriptElement(clientId: string | string[]): void
  • Removes the widget's script block from the DOM. Currently, the ID of this script block consists of the client-side ID of this widget with the prefix _s, but this is subject to change.

    Parameters

    • clientId: string | string[]

      The client-side ID of the widget.

    Returns void

search

  • search(query: string): void
  • Initiates a search with given value, that is, look for matching options and present the options that were found to the user.

    Parameters

    • query: string

      Keyword for the search.

    Returns void

searchWithDropdown

  • searchWithDropdown(): void
  • Performs a search the same ways as if the user had opened the dropdown menu. Depending on the configured dropdownMode, performs the search either with an empty string or with the current value.

    Returns void

Private setCache

  • Adds the suggestions items in the given wrapper to the local cache of suggestion items.

    Parameters

    • wrapper: JQuery<HTMLElement>

      Wrapper element with the suggestions fetched from the server.

    Returns void

Private setupForceSelection

  • setupForceSelection(): void
  • Sets up the event listener for the blur event to force a selection, when that feature is enabled.

    Returns void

Private setupMultipleMode

  • setupMultipleMode(): void
  • Binds events for multiple selection mode.

    Returns void

Private show

  • show(): void
  • Shows the panel with the suggestions.

    Returns void

Private showItemtip

  • Shows the tooltip for the given suggestion item.

    Parameters

    Returns void

Private showSuggestions

  • showSuggestions(query: string): void
  • Performs the search for the available suggestion items.

    Parameters

    • query: string

      Keyword for the search.

    Returns void

Private unbindPanelEvents

  • unbindPanelEvents(): void
  • Unbind all panel event listeners

    Returns void

Generated using TypeDoc