Options
All
  • Public
  • Public/Protected
  • All
Menu

PrimeFaces Vertical Tree Widget

Tree is used for displaying hierarchical data and creating a site navigation. This implements a vertical tree.

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

container

container: JQuery<HTMLElement>

The DOM element for the tree container.

cursorNode

cursorNode: JQuery<HTMLElement>

When multiple nodes are selected, the selected node on which the user clicked most recently.

destroyListeners

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

dropRestrict

dropRestrict: DropRestrictMode

Defines parent-child restrictions when a node is dropped.

droppedNodeParams

droppedNodeParams: DroppedNodeParams[]

List of parameter describing the drag & drop operations.

filterInput

filterInput: JQuery<HTMLElement>

The DOM element for the filter input field that lets the user search the tree.

filterTimeout

filterTimeout: number

The set-timeout timer ID of the timer for the filter delay.

focusedNode

focusedNode: null | JQuery<HTMLElement>

DOM element of the node which is currently focused, if any.

iconStates

iconStates: Record<string, NodeIconSet>

A map between the type of a node and the icons for that node.

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.

invalidSourceKeys

invalidSourceKeys: string[]

A list of row keys for rows that are not valid drag sources.

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.

scrollInterval

scrollInterval: number

The set-interval time ID of the timer for scrolling.

scrollStateHolder

scrollStateHolder: JQuery<HTMLElement>

Form element that holds the current scroll state.

selectionHolder

selectionHolder: JQuery<HTMLElement>

DOM element of the hidden form element that holds the list of selected nodes.

selections

selections: string

List of nodes which are currently selected. Each item is the row key of a selected node.

shiftKey

shiftKey: boolean

For drag&drop, whether the shift is pressed.

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

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

Protected addToSelection

  • addToSelection(rowKey: string): void
  • Adds the given node to the list of selected nodes.

    Parameters

    • rowKey: string

      Row key of the node to add to the selected nodes.

    Returns void

bindContextMenu

  • Callback that is invoked when the context menu is initialized. Lets the context menu provider register the appropriate event listeners for when the context menu should be shown and hidden.

    override

    Parameters

    • menuWidget: ContextMenu<ContextMenuCfg>

      The widget instance of the context menu.

    • targetWidget: BaseTree<BaseTreeCfg>

      The widget instance of the target widget that wants to add a context menu.

    • targetId: string

      ID selector or DOM element of the target, i.e. the element the context menu belongs to.

    • cfg: ContextMenuCfg

      The current configuration of the context menu.

    Returns void

Protected bindEvents

  • bindEvents(): void
  • A sub class may perform any setup related to registering event handlers in this method, such as listening to mouse clicks or keyboard presses.

    override

    Returns void

Private bindKeyEvents

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

    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

Protected check

  • When this tree has got selectable nodes with checkboxes, selects the given checkbox. Does nothing otherwise.

    override

    Parameters

    Returns void

Private clearScrollState

  • clearScrollState(): void
  • Resets the value of the hidden input field with the current scroll position.

    Returns void

collapseNode

  • Collapses the given node, as if the user had clicked on the - icon of the node. The children of the node will now be visible.

    Parameters

    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

expandNode

  • Expands the given node, as if the user had clicked on the + icon of the node. The children of the node will now be visible.

    Parameters

    Returns void

filter

  • filter(): void
  • Applies the current filter value by sending an AJAX to the server.

    Returns void

findNodes

  • Finds the nodes with the given row keys.

    Parameters

    • rowkeys: string[]

      A list of row keys.

    Returns JQuery<HTMLElement>[]

    A list of nodes corresponding to the given row keys, in that order.

Private findSelectedParentKeys

  • findSelectedParentKeys(arr: string[]): string[]
  • Filters the given array of row keys and removes child nodes of parent node in the array.

    Parameters

    • arr: string[]

      A list of row keys to check.

    Returns string[]

    A list of parent row keys.

Private findTargetDragNode

  • Locates the target drag node, depending on the given drag mode.

    Parameters

    Returns JQuery<HTMLElement>

    The resolved target drag node.

Protected fireCollapseEvent

Protected fireContextMenuEvent

  • Called when a right click was performed on a node. Fire the appropriate event.

    Parameters

    • node: JQuery<HTMLElement>

      The node for which to fire the event.

    • fnShowMenu: () => void

      Callback that is invoked once the context menu is shown.

        • (): void
        • Returns void

    Returns void

Private fireDragDropEvent

  • Callback for when a drag&drop occurred. Invokes the appropriate behaviors.

    Parameters

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

      Event that triggered the drag&drop.

    Returns void

Protected fireExpandEvent

Protected fireNodeSelectEvent

Protected fireNodeUnselectEvent

Protected focusNode

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.

getFirstNode

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.

Protected getNodeChildrenContainer

getNodeLabel

  • Finds the label element for the given node.

    Parameters

    Returns JQuery<HTMLElement>

    The element with the label for the given node.

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.

getRowKey

  • Finds the row key (unique ID) of the given node.

    Parameters

    Returns string

    The key of the given node.

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

Private initDraggable

  • initDraggable(): void
  • Sets up the drag functionality.

    Returns void

Private initDropScrollers

  • initDropScrollers(): void
  • Initializes all drop scrollers of this tree.

    Returns void

Private initDroppable

  • initDroppable(): void
  • Sets up the drop functionality.

    Returns void

Protected initSelection

  • initSelection(): void
  • Called when this tree is initialized. Performs any setup required for enabling the selection of node.

    Returns void

isCheckboxSelection

  • isCheckboxSelection(): boolean
  • Checks whether the selection mode of this tree is set to checkbox.

    Returns boolean

    true if the current selection mode is checkbox, 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.

isEmpty

  • isEmpty(): boolean
  • Checks whether this tree is empty, that is, whether it contains any nodes.

    override

    Returns boolean

    true if this tree has got no nodes, or false otherwise.

isExpanded

  • Checks whether the given node is currently expanded, that is, whether its children are visible.

    Parameters

    Returns boolean

    true if the node is expanded, or false otherwise.

isMultipleSelection

  • isMultipleSelection(): boolean
  • Checks whether the selection mode of this tree is set to multiple.

    Returns boolean

    true if the current selection mode is multiple, or false otherwise.

isNodeSelected

  • Checks whether the given node is currently selected, irrespective of the current selection mode.

    Parameters

    Returns boolean

    true if the given node is selected, or false otherwise.

isSingleSelection

  • isSingleSelection(): boolean
  • Checks whether the selection mode of this tree is set to single.

    Returns boolean

    true if the current selection mode is single, or false otherwise.

Private makeDraggable

  • Sets up the JQuery UI draggable for the given elements.

    Parameters

    Returns void

Private makeDropNodes

  • Sets up the JQuery UI dropables for the droppable nodes.

    Parameters

    Returns void

Private makeDropPoints

  • Sets up the JQuery UI drop points for the given elements.

    Parameters

    Returns void

Private makeLeaf

  • Turns the given node into a leaf node.

    Parameters

    Returns void

Private makeParent

  • Turns the given node into a parent node.

    Parameters

    Returns void

Protected nodeClick

Protected nodeRightClick

  • Invoked in response to a right click on a node.

    Parameters

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

      Event of the right click.

    • nodeContent: JQuery<HTMLElement>

      Content of the clicked node.

    • fnShowMenu: () => void

      Callback that is invoked when the context menu is shown.

        • (): void
        • Returns void

    Returns boolean

    true if the context menu was opened, or false otherwise.

Private onDropNode

Private onDropPoint

  • Callback for when a node was dropped on a drop point.

    Parameters

    Returns void

Protected partialCheck

  • When this tree has got selectable nodes with checkboxes, partially selects the given checkbox. Does nothing otherwise.

    Parameters

    Returns void

Private postCollapse

  • Callback that is invoked after a node was collapsed.

    Parameters

    Returns void

Protected preselectCheckbox

  • preselectCheckbox(): void
  • Called once during widget initialization if this tree has got nodes with selectable checkboxes.

    override

    Returns void

Private propagateDNDCheckbox

  • Updates the drag&drop checkboxes.

    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.

    Parameters

    Returns unknown

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

Protected removeDescendantsFromSelection

  • removeDescendantsFromSelection(rowKey: string): void
  • Removes all chilren of the given node from the list of currently selected nodes.

    Parameters

    • rowKey: string

      Row key of a node to process.

    Returns void

Protected removeFromSelection

  • removeFromSelection(rowKey: string): void
  • Removes the given node from the list of currently selected nodes.

    Parameters

    • rowKey: string

      Row key of a node to to remove from the current selection.

    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 restoreScrollState

  • restoreScrollState(): void
  • Reads the saved scroll position from the hidden input field and applies it.

    Returns void

Private saveScrollState

  • saveScrollState(): void
  • Saves the current scroll position to the hidden input field.

    Returns void

scroll

  • scroll(step: number): void
  • Scrolls this tree by the given amount.

    Parameters

    • step: number

      Amount by which to scroll.

    Returns void

Private searchDown

  • Searches for a node to focus, starting at the given node.

    Parameters

    Returns JQuery<HTMLElement>

    A node to focus.

selectNode

  • This method must select the given node. When silent is set to true, no events should be triggered in response to this action.

    override

    Parameters

    • node: JQuery<HTMLElement>

      A node of this tree to select.

    • Optional silent: boolean

      true if no events should be triggered, or false otherwise.

    Returns void

Protected showNodeChildren

  • Makes the children of the given node visible. Called when a node is expanded.

    override

    Parameters

    Returns void

Private syncDNDCheckboxes

  • Updates all checkboxes after a drag&drop.

    Parameters

    Returns void

Private syncDragDrop

  • syncDragDrop(): void
  • Updates the tree after a drag&drop event.

    Returns void

Protected toggleCheckboxNode

  • Called when the nodes of this tree are selected via checkboxes. Must select the checkbox of the given node.

    override

    Parameters

    Returns void

toggleCheckboxState

  • When this tree has got selectable nodes with checkboxes, checks or unchecks the given checkbox.

    Parameters

    • checkbox: JQuery<HTMLElement>

      A checkbox of a node to check or uncheck.

    • checked: boolean

      true to check the given node, false to uncheck it.

    Returns void

Protected uncheck

  • When this tree has got selectable nodes with checkboxes, unselects the given checkbox. Does nothing otherwise.

    override

    Parameters

    Returns void

unselectAllNodes

  • unselectAllNodes(): void
  • This method must unselect all nodes of this tree that are selected.

    override

    Returns void

unselectNode

  • This method must unselect the given node. When silent is set to true, no events should be triggered in response to this action.

    override

    Parameters

    • node: JQuery<HTMLElement>

      A node of this tree to unselect.

    • Optional silent: boolean

      true if no events should be triggered, or false otherwise.

    Returns void

unselectSubtree

  • Unselects the node and all child nodes.

    Parameters

    Returns void

Private updateChildrenRowKeys

  • Updates the row keys of all given children.

    Parameters

    • children: JQuery<HTMLElement>

      List of children to update.

    • rowkey: null | string

      Base prefix for the new rowkey.

    Returns void

Private updateDragDropBindings

  • Updates the drag&drop settings for the given node.

    Parameters

    Returns void

Private updateRowKeys

  • updateRowKeys(): void
  • Updates the row keys of all nodes.

    Returns void

Private validateDropNode

  • After a drag&drop, validates if the drop is allowed.

    Parameters

    Returns boolean

    Whether the drop is allowed.

Private validateDropPoint

  • After a drag&drop, validates if the drop is allowed.

    Parameters

    Returns boolean

    Whether the drop is allowed.

Protected writeSelections

  • writeSelections(): void
  • Saves the list of currently selected nodes in a hidden form element.

    Returns void

Generated using TypeDoc