Options
All
  • Public
  • Public/Protected
  • All
Menu

PrimeFaces SelectOneMenu Widget

SelectOneMenu is an extended version of the standard SelectOneMenu.

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 SelectOneMenu<TCfg>

Properties

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.

changed

changed: boolean

Whether the value of this widget was changed from its original value.

customInput

customInput: JQuery<HTMLElement>

The DOM element for the input field that lets the user enter a custom value which does not have to match one of the available options.

customInputVal

customInputVal: string

The custom value that was entered by the user which does not have to match one the available options.

destroyListeners

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

disabled

disabled: boolean

Whether this widget is currently disabled.

filterInput

filterInput: JQuery<HTMLElement>

The DOM element for the input field that lets the user enter a search term to filter the list of available options.

filterMatcher

filterMatcher: FilterFunction

The filter that was selected and is currently used.

filterMatchers

filterMatchers: Record<FilterMatchMode, FilterFunction>

Map between the available filter types and the filter implementation.

focusInput

focusInput: JQuery<HTMLElement>

The hidden input that can be focused via the tab key etc.

Optional hideOverlayHandler

hideOverlayHandler?: UnbindCallback

Unbind callback for the hide overlay handler.

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 hidden input with the current value.

isDynamicLoaded

isDynamicLoaded: boolean

Whether the contents of the overlay panel were loaded.

Optional items

The DOM elements for the the available selectable options.

Optional itemsContainer

itemsContainer?: JQuery<HTMLElement>

The DOM element for the container with the available selectable options.

itemsWrapper

itemsWrapper: JQuery<HTMLElement>

The DOM element for the wrapper with the container with the available selectable options.

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

label

The DOM element for the label indicating the currently selected option.

menuIcon

menuIcon: JQuery<HTMLElement>

The DOM element for the icon for bringing up the overlay panel.

optGroupsSize

optGroupsSize: number

The number of option groups.

options

The DOM elements for the available selectable options.

panel

The DOM element for the overlay panel with the available selectable options.

panelId

ID of the DOM element for the overlay panel with the available selectable options.

panelWidthAdjusted

panelWidthAdjusted: number

The adjusted width of the overlay panel.

preShowValue

preShowValue: JQuery<HTMLElement>

The DOM element for the selected option that is shown before the overlay panel is brought up.

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.

searchTimer

searchTimer: number

ID of the timeout for the delay of the filter input in the overlay panel.

Optional transition

transition?: null | CssTransitionHandler

Handler for CSS transitions used by this widget.

triggers

triggers: JQuery<HTMLElement>

The DOM elements for the buttons that can trigger (hide or show) the overlay panel with the available selectable options.

value

value: string

The current value of this select one menu.

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').

Methods

Protected _render

  • _render(): void
  • This render method is called by this deferred widget once the widget container has become visible. You may now proceed with widget initialization.

    Must be overridden, or an error will be thrown.

    override

    Returns void

Private _show

  • _show(): void
  • Brings up the overlay panel with the available selectable options. Compared this show, this does not ensure the the overlay panel is loaded already (when dynamic loading is enabled).

    Returns void

Protected addDeferredRender

  • addDeferredRender(widgetId: string, container: JQuery<HTMLElement>, callback: () => boolean): void
  • Adds a deferred rendering task for the given widget to the queue.

    Parameters

    • widgetId: string

      The ID of a deferred widget.

    • container: JQuery<HTMLElement>

      The container element that should be visible.

    • callback: () => boolean

      Callback that is invoked when the widget may possibly have become visible. Should return true when the widget was rendered, or false when the widget still needs to be rendered later.

        • (): boolean
        • Returns boolean

    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

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
  • Align the overlay panel with the available selectable options so that is is positioned next to the the button.

    Returns void

Private alignPanelWidth

  • alignPanelWidth(): void
  • Adjust the width of the overlay panel.

    Returns void

Private bindEvents

  • bindEvents(): void
  • Sets up all event listeners required by this widget.

    Returns void

Private bindFilterEvents

  • bindFilterEvents(): void
  • Sets up the event listeners for the filter input in the overlay panel.

    Returns void

Private bindItemEvents

  • bindItemEvents(): void
  • Sets up the event listeners for the selectable items.

    Returns void

Private bindKeyEvents

  • bindKeyEvents(): void
  • Sets up the event listeners for all keyboard related events other than the overlay panel, such as pressing space to bring up the overlay panel.

    Returns void

Private bindPanelEvents

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

    Returns void

blur

  • blur(): void
  • Removes focus from this widget.

    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

Private callHandleMethod

  • Invokes the given method after making sure that the overlay panel was loaded (in case dynamic mode is enabled).

    Parameters

    • handleMethod: (event: TriggeredEvent<any, any, any, any>) => void

      Callback method to invoke after the dynamic overlay panel was loaded.

    • event: TriggeredEvent<any, any, any, any>

      An event that is passed to the callback.

    Returns void

Private changeAriaValue

  • Adjusts the value of the aria attributes for the given selectable option.

    Parameters

    Returns void

containsFilter

  • containsFilter(value: string, filter: string): boolean
  • Implementation of a PrimeFaces.widget.SelectOneMenu.FilterFunction that matches the given option when it contains the given search text.

    Parameters

    • value: string

      Text of an option.

    • filter: string

      Value of the filter.

    Returns boolean

    true when the text of the contains the filter value, or false otherwise.

destroy

  • destroy(): void
  • Cleans up deferred render tasks. When you extend this class and override this method, make sure to call super.

    override

    Returns void

disable

  • disable(): void
  • Disables this widget so that the user cannot select any option.

    Returns void

Private dynamicPanelLoad

  • dynamicPanelLoad(): void
  • Loads the overlay panel with the selectable options, if dynamic mode is enabled.

    Returns void

enable

  • enable(): void
  • Enables this widget so that the user can select an option.

    Returns void

endsWithFilter

  • endsWithFilter(value: string, filter: string): boolean
  • Implementation of a PrimeFaces.widget.SelectOneMenu.FilterFunction that matches the given option when it ends with the given search text.

    Parameters

    • value: string

      Text of an option.

    • filter: string

      Value of the filter.

    Returns boolean

    true when the text of the options ends with the filter value, or false otherwise.

filter

  • filter(value: string): void
  • Filters the available options in the overlay panel by the given search value. Note that this does not bring up the overlay panel, use show for that.

    Parameters

    • value: string

      A value against which the available options are matched.

    Returns void

focus

  • focus(): void
  • Puts focus on this widget.

    Returns void

focusFilter

  • focusFilter(timeout?: number): void
  • Puts focus on the filter input in the overlay panel.

    Parameters

    • Optional timeout: number

      Amount of time in milliseconds to wait before attempting to focus the input.

    Returns void

getActiveItem

  • Finds the element for the currently select option of this select one menu.

    Returns JQuery<HTMLElement>

    The DOM element that represents the currently selected option.

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.

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.

Private getLabelToDisplay

  • getLabelToDisplay(value: string): string
  • Finds the label of the option with the given value.

    Parameters

    • value: string

      The value of a selectable option.

    Returns string

    The label of the option with the given value.

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.

getSelectedLabel

  • getSelectedLabel(): string
  • Finds the label of the currently selected item, if any.

    Returns string

    The label of the currently selected item. Empty string if none is selected.

getSelectedValue

  • getSelectedValue(): string
  • Finds the value of the currently selected item, if any.

    Returns string

    The value of the currently selected item. Empty string if none is selected.

Private handleEnterKey

  • Callback for when the enter key was pressed. Brings up the overlay panel or accepts the highlighted option.

    Parameters

    Returns void

Private handleEscapeKey

  • Callback for when the escape key was pressed. Hides the overlay panel.

    Parameters

    Returns void

Private handleLabelChange

  • Callback that adjusts the label, invoked when the selected option has changed.

    Parameters

    • event: TriggeredEvent<any, any, any, any>

      The event that triggered the change.

    Returns void

Private handleSpaceKey

  • Callback for when the space key was pressed. Brings up or hides the overlay panel.

    Parameters

    Returns void

Private handleTabKey

  • handleTabKey(): void
  • Callback for when the tab key was pressed. Selects the next option.

    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.

hide

  • hide(): void
  • Hides the overlay panel with the available selectable options.

    Returns void

Private highlightItem

  • Highlight the given selectable option.

    Parameters

    Returns void

Private highlightNext

  • Highlights the next option after the currently highlighted option in the overlay panel.

    Parameters

    Returns void

Private highlightPrev

  • Highlights the previous option before the currently highlighted option in the overlay panel.

    Parameters

    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 initContents

  • initContents(): void
  • Finds and initializes the DOM elements that make up this widget.

    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.

Private matchOptions

  • Finds all options that match the given search string.

    Parameters

    • text: string

      The search string against which to match the options.

    Returns JQuery<HTMLElement>

    All selectable options that match (contain) the given search string.

Protected postRender

  • postRender(): void
  • Called after the widget has become visible and after it was rendered. May be overridden, the default implementation is a no-op.

    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.

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

render

  • This render method to check whether the widget container is visible. Do not override this method, or the deferred widget functionality may not work properly anymore.

    Returns ReturnOrVoid<undefined | boolean>

    true if the widget container is visible, false or undefined otherwise.

renderDeferred

  • renderDeferred(): void
  • Call this method in the init method if you want deferred rendering support. This method checks whether the container of this widget is visible and call _render only once it is.

    Returns void

Private renderPanelContentFromHiddenSelect

  • renderPanelContentFromHiddenSelect(initContentsAndBindItemEvents: boolean): void
  • Renders panel content based on hidden select.

    Parameters

    Returns void

Private renderSelectItem

  • Renders panel HTML code for one select item (group).

    Parameters

    • item: JQuery<HTMLElement>

      An option (group) for which to render HTML code.

    • Optional isGrouped: boolean

      Indicates whether the item is part of a group.

    Returns string

    The rendered HTML string.

Private renderSelectItems

  • Renders panel HTML-code for all select items.

    Parameters

    • parentItem: JQuery<HTMLElement>

      A parent item (select, optgroup) for which to render HTML code.

    • Optional isGrouped: boolean

      Indicated whether the elements of the parent item should be marked as grouped.

    Returns string

    The rendered HTML string.

resolveItemIndex

  • Finds the index of the given selectable option.

    Parameters

    Returns number

    The index of the given item.

revert

  • revert(): void
  • Unselect the selected item, if any, and select the please select option.

    Returns void

Private selectItem

  • Callback for when the user selects an item with the mouse.

    Parameters

    • item: JQuery<HTMLElement>

      The option to select.

    • silent: boolean

      true to suppress triggering event listeners, or false otherwise.

    Returns void

selectValue

  • selectValue(value: string): void
  • Selects the option with the given value.

    Parameters

    • value: string

      Value of the option to select.

    Returns void

Private setLabel

  • setLabel(value: string): void
  • Sets the label text that indicates the currently selected item to the item with the given value.

    Parameters

    • value: string

      Value of the item that was selected.

    Returns void

Private setupFilterMatcher

  • setupFilterMatcher(): void
  • Finds and stores the filter function which is to be used for filtering the options of this select one menu.

    Returns void

show

  • show(): void
  • Brings up the overlay panel with the available selectable options.

    Returns void

startsWithFilter

  • startsWithFilter(value: string, filter: string): boolean
  • Implementation of a PrimeFaces.widget.SelectOneMenu.FilterFunction that matches the given option when it starts with the given search text.

    Parameters

    • value: string

      Text of an option.

    • filter: string

      Value of the filter.

    Returns boolean

    true when the text of the options starts with the filter value, or false otherwise.

Private syncTitle

  • Adjust the value of the title attribute to match selected option.

    Parameters

    Returns void

Private triggerChange

  • triggerChange(edited: boolean): void
  • Triggers the event listeners when the value of this widget changed.

    Parameters

    • edited: boolean

      Whether the value was edited by the user. If it was, checks which option is now selected.

    Returns void

Private unbindEvents

  • unbindEvents(): void
  • Removes some event listeners when this widget was disabled.

    Returns void

Private unbindPanelEvents

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

    Returns void

updatePlaceholderClass

  • updatePlaceholderClass(add: boolean): void
  • Updates the style class of the label that indicates the currently selected item.

    Parameters

    • add: boolean

      true if a placeholder should be displayed, or false otherwise.

    Returns void

Generated using TypeDoc