Options
All
  • Public
  • Public/Protected
  • All
Menu

PrimeFaces PickList Widget

PickList is used for transferring data between two different collections.

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

Properties

ariaRegion

ariaRegion: JQuery<HTMLElement>

The DOM element for the aria region with the aria-* attributes

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.

checkboxClick

checkboxClick: boolean

UI state indicating whether a checkbox was just clicked.

checkboxes

checkboxes: JQuery<HTMLElement>

The DOM elements for the checkboxes next to each pick list item.

cursorItem

cursorItem: JQuery<HTMLElement>

The currently selected item.

destroyListeners

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

dragging

dragging: boolean

Whether the user is currently transferring an item via drag&drop.

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.

filterTimeout

filterTimeout: number

The set-timeout timer ID of the timer for the delay when filtering the source or target list.

focusedItem

focusedItem: JQuery<HTMLElement>

The DOM element for the currently focused pick list item, if any.

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.

itemListName

itemListName: ListName

When sorting items: to which list the items belong.

items

The DOM elements for the pick list items in the source and target list.

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

refreshListeners

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

sourceFilter

sourceFilter: JQuery<HTMLElement>

The DOM element for the filter input for the source list.

sourceInput

sourceInput: JQuery<HTMLElement>

The DOM element for the hidden input storing the value of the source list.

sourceList

sourceList: JQuery<HTMLElement>

The DOM element for the source list.

targetFilter

targetFilter: any

The DOM element for the filter input for the target list.

targetInput

targetInput: any

The DOM element for the hidden input storing the value of the target list.

targetList

targetList: JQuery<HTMLElement>

The DOM element for the target list.

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

add

  • add(): void
  • Adds all selected items in the source list by transferring them to the target list.

    Returns void

addAll

  • addAll(): void
  • Adds all items to the target list by transferring all items from the source list to the target list.

    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

Private bindButtonEvents

  • bindButtonEvents(): void
  • Sets tup the event listeners for when the command buttons (move up, move down etc.) are pressed.

    Returns void

Private bindEnterKeyFilter

  • Sets up the event listeners for when the enter key is pressed while inside a filter input of the source or target list.

    Parameters

    Returns void

Private bindFilterEvent

  • Sets up the event listeners for filtering the source and target lists.

    Parameters

    Returns void

Private bindFilterEvents

  • bindFilterEvents(): void
  • Sets up all event listeners for filtering the source and target lists.

    Returns void

Private bindItemEvents

  • bindItemEvents(): void
  • Sets up the event listeners for selecting and transferring pick list items.

    Returns void

Private bindKeyEvents

  • bindKeyEvents(): void
  • Sets up the keyboard event listeners for navigating the pick list via keyboard keys.

    Returns void

Private bindTextFilter

  • Sets up the event listeners for when text is entered into the filter input of the source or target list.

    Parameters

    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

containsFilter

  • containsFilter(value: string, filter: string): boolean
  • Implementation of a PrimeFaces.widget.PickList.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
  • 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

Private disableButton

  • Disables the given button belonging to this pick list.

    Parameters

    Returns void

Private enableButton

  • Enables the given button belonging to this pick list.

    Parameters

    Returns void

endsWithFilter

  • endsWithFilter(value: string, filter: string): boolean
  • Implementation of a PrimeFaces.widget.PickList.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

  • Filters the available options in the source or target list.

    Parameters

    • value: string

      A value against which the available options are matched.

    • list: JQuery<HTMLElement>

      The source or target list that is to be filtered.

    • Optional animate: boolean

      If it should be animated.

    Returns void

Private fireItemSelectEvent

  • Triggers the behavior for when pick list items are selected.

    Parameters

    Returns void

Private fireItemUnselectEvent

  • Triggers the behavior for when pick list items are unselected.

    Parameters

    Returns void

Private fireReorderEvent

  • fireReorderEvent(): void
  • Triggers the behavior for when pick list items are reordered.

    Returns void

Private fireTransferEvent

  • Triggers the behavior for when pick list items are transferred from the source to the target list or vice-versa.

    Parameters

    Returns void

Private generateItems

  • Stores the current items in the given list in a hidden form field. Used for submitting the current value of this pick list.

    Parameters

    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 getFilteredList

  • Finds the list belonging to the given filter input.

    Parameters

    Returns JQuery<HTMLElement>

    The list to which the given filter input applies.

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 getListName

  • Finds the type of the given list, i.e. whether the list represents the source or target list.

    Parameters

    Returns ListName

    Whether the element represents the source or target list.

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 getTabIndex

  • getTabIndex(): string
  • Finds the tab index of this pick list widget.

    Returns string

    The tab index of this pick list.

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.

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

isAnimated

  • isAnimated(): boolean
  • Checks whether UI actions of this pick list are animated.

    Returns boolean

    true if this pick list is animated, or false otherwise.

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.

moveBottom

  • Moves the items that are currently selected to the bottom of the source of target list.

    Parameters

    • list: JQuery<HTMLElement>

      The source or target list with items to move to the bottom.

    Returns void

moveDown

  • Moves the items that are currently selected down by one.

    Parameters

    Returns void

moveTop

  • Moves the items that are currently selected to the top of the source of target list.

    Parameters

    Returns void

moveUp

  • Moves the items that are currently selected up by one.

    Parameters

    Returns void

Private refilterSource

  • refilterSource(): void
  • Reapply filtering the current source list.

    Returns void

Private refilterTarget

  • refilterTarget(): void
  • Reapply filtering to the current target list.

    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.

    Parameters

    Returns unknown

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

remove

  • remove(): void
  • Removes all selected items in the target list by transferring them to the source list.

    Returns void

removeAll

  • removeAll(): void
  • Removes all items in the target list by transferring all items from the target list to the source list.

    Returns void

Private removeOutline

  • removeOutline(): void
  • Removes the outline from the item that is currently focused.

    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

Private saveState

  • saveState(): void
  • Saves the current state of this widget, i.e. to which list the items are currently assigned. Clears inputs and repopulates them from the list states.

    Returns void

Private selectCheckbox

  • Selects the given checkbox that belongs to a pick list item.

    Parameters

    • chkbox: JQuery<HTMLElement>

      The hidden checkbox of a pick list item that was selected.

    Returns void

selectItem

  • Select the given pick list item in the source or target list.

    Parameters

    • item: JQuery<HTMLElement>

      A picklist item to select, with the class ui-picklist-item.

    • Optional silent: boolean

      true to imit triggering event listeners and behaviors, or false otherwise.

    Returns void

Private setTabIndex

  • setTabIndex(): void
  • Applies the tab index to this pick list widget.

    Returns void

Private setupFilterMatcher

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

    Returns void

startsWithFilter

  • startsWithFilter(value: string, filter: string): boolean
  • Implementation of a PrimeFaces.widget.PickList.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.

transfer

  • Transfers the given items from the source or target list to the other list.

    Parameters

    Returns void

unselectAll

  • unselectAll(): void
  • Unselects all items in the source and target list.

    Returns void

Private unselectCheckbox

  • Unselects the given checkbox that belongs to a pick list item.

    Parameters

    • chkbox: JQuery<HTMLElement>

      The hidden checkbox of a pick list item that was unselected.

    Returns void

unselectItem

  • Unselect the given pick list item in the source or target list.

    Parameters

    • item: JQuery<HTMLElement>

      A picklist item to unselect, with the class ui-picklist-item.

    • Optional silent: boolean

      true to imit triggering event listeners and behaviors, or false otherwise.

    Returns void

Private updateButtonsState

  • updateButtonsState(): void
  • Updates the state of all buttons of this pick list, such as whether they are disabled or enabled.

    Returns void

Private updateListRole

  • updateListRole(): void
  • Updates the role attribute of the source and target pick list items.

    Returns void

Generated using TypeDoc