Module org.omnifaces
Package org.omnifaces.component.tree

Class Tree

java.lang.Object
jakarta.faces.component.UIComponent
jakarta.faces.component.UIComponentBase
org.omnifaces.component.tree.TreeFamily
org.omnifaces.component.tree.Tree
All Implemented Interfaces:
NamingContainer, PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder, EventListener
public class Tree extends TreeFamily implements NamingContainer

The <o:tree> allows the developers to have full control over the markup of a tree hierarchy by declaring the appropriate Faces components or HTML elements in the markup. The <o:tree> does namely not render any HTML markup by itself.

The component value must point to a tree of data objects represented by a TreeModel instance, typically established via a ValueExpression. During iterative processing over the nodes of tree in the tree model, the object for the current node is exposed as a request attribute under the key specified by the var attribute. The node itself is exposed as a request attribute under the key specified by the varNode attribute.

The <o:tree> tag supports only child tags of type <o:treeNode>, representing parent tree nodes. There can be multiple <o:treeNode> tags, each representing a separate parent tree node level, so that different markup could be declared for each tree node level, if necessary. The <o:treeNode> tag in turn supports child tag <o:treeNodeItem> which represents each child of the current parent tree node. The <o:treeNodeItem> in turn supports child tag <o:treeInsertChildren> which represents the insertion point of the grand children.

Here is a basic usage example where each parent tree node level is treated the same way via a single <o:treeNode>: 

 <o:tree value="#{bean.treeModel}" var="item" varNode="node">
     <o:treeNode>
         <ul>
             <o:treeNodeItem>
                 <li>
                     #{node.index} #{item.someProperty}
                     <o:treeInsertChildren />
                 </li>
             </o:treeNodeItem>
         </ul>
     </o:treeNode>
 </o:tree>

treeNode

The <o:treeNode> represents the parent tree node. Within this component, the var attribute of the <o:tree> will expose the parent tree node. Each of its children is processed by <o:treeNodeItem> on which the var attribute of the <o:tree> in turn exposes each child of the parent tree node.

The optional level attribute can be used to specify for which tree node level as obtained by TreeModel.getLevel() the <o:treeNode> should be rendered. The root tree node has level 0. If the level attribute is unspecified, then the <o:treeNode> will be rendered for any tree node level which hasn't already a <o:treeNode level="x"> specified.

treeNodeItem

The <o:treeNodeItem> represents the child item of the parent tree note as represented by <o:treeNode>. Within this component, the var attribute of the parent <o:tree> component will expose the child tree node.

Within <o:treeNodeItem> you can use <o:treeInsertChildren> to declare the place where to recursively render the <o:treeNode> whereby the current child item is in turn interpreted as a parent tree node (i.e. where you'd like to insert the grand-children).

treeInsertChildren

The <o:treeInsertChildren> represents the insertion point for the grand children. This is in turn further interpreted as <o:treeNode>.

Author:
Bauke Scholtz
See Also:

  • Field Details

    • COMPONENT_TYPE

      public static final String COMPONENT_TYPE
      The component type, which is "org.omnifaces.component.tree.Tree".
      See Also:

  • Constructor Details

    • Tree

      public Tree()

  • Method Details

    • getContainerClientId

      public String getContainerClientId(FacesContext context)
      An override which appends the index of the current model node to the client ID chain, if any available.
      Overrides:
      getContainerClientId in class UIComponent
      See Also:

    • setValueExpression

      public void setValueExpression(String name, ValueExpression binding)
      An override which checks if this isn't been invoked on var or varNode attribute. Finally it delegates to the super method.
      Overrides:
      setValueExpression in class UIComponent
      Throws:
      IllegalArgumentException - When this value expression is been set on var or varNode attribute.

    • queueEvent

      public void queueEvent(FacesEvent event)
      An override which wraps the given faces event in a specific faces event which remembers the current model node.
      Overrides:
      queueEvent in class UIComponentBase

    • validateHierarchy

      protected void validateHierarchy(FacesContext context)
      Validate the component hierarchy.
      Specified by:
      validateHierarchy in class TreeFamily
      Parameters:
      context - The faces context to work with.
      Throws:
      IllegalStateException - When this component is nested in another Tree, or when there aren't any children of type TreeNode.

    • process

      protected void process(FacesContext context, PhaseId phaseId)
      Set the root node as current node and delegate the call to processTreeNode(FacesContext, PhaseId).
      Specified by:
      process in class TreeFamily
      Parameters:
      context - The faces context to work with.
      phaseId - The current phase ID.

    • visitTree

      public boolean visitTree(VisitContext context, VisitCallback callback)
      Set the root node as current node and delegate the call to visitTreeNode(VisitContext, VisitCallback).
      Overrides:
      visitTree in class UIComponentBase
      Parameters:
      context - The visit context to work with.
      callback - The visit callback to work with.
      Returns:
      The visit result.

    • isVisitable

      protected boolean isVisitable(VisitContext context)
      Overrides:
      isVisitable in class UIComponent

    • broadcast

      public void broadcast(FacesEvent event)
      If the given event is an instance of the specific faces event which was created during our queueEvent(FacesEvent), then extract the node from it and set it as current node and delegate the call to the wrapped faces event.
      Overrides:
      broadcast in class UIComponentBase

    • processTreeNode

      protected void processTreeNode(FacesContext context, PhaseId phaseId)
      If the current model node isn't a leaf (i.e. it has any children), then obtain the TreeNode associated with the level of the current model node. If it isn't null, then process it according to the rules of the given phase ID. This method is also called by TreeInsertChildren.process(FacesContext, PhaseId).
      Parameters:
      context - The faces context to work with.
      phaseId - The current phase ID.
      See Also:

    • visitTreeNode

      protected boolean visitTreeNode(VisitContext context, VisitCallback callback)
      If the current model node isn't a leaf (i.e. it has any children), then obtain the TreeNode associated with the level of the current model node. If it isn't null, then visit it according to the given visit context and callback. This method is also called by TreeInsertChildren.visitTree(VisitContext, VisitCallback).
      Parameters:
      context - The visit context to work with.
      callback - The visit callback to work with.
      Returns:
      true if the visit is complete.
      See Also:

    • setCurrentModelNode

      protected void setCurrentModelNode(FacesContext context, TreeModel currentModelNode)
      Sets the current node of the tree model. Its wrapped data will be set as request attribute associated with the var attribute, if any. The node itself will also be set as request attribute associated with the varNode attribute, if any.
      Parameters:
      context - The faces context to work with.
      currentModelNode - The current node of the tree model.

    • getCurrentModelNode

      protected TreeModel getCurrentModelNode()
      Returns the current node of the tree model.
      Returns:
      The current node of the tree model.

    • getValue

      public Object getValue()
      Returns the tree model.
      Returns:
      The tree model

    • setValue

      public void setValue(Object value)
      Sets the tree model.
      Parameters:
      value - The tree model.

    • getVar

      public String getVar()
      Returns the name of the request attribute which exposes the wrapped data of the current node of the tree model.
      Returns:
      The name of the request attribute which exposes the wrapped data of the current node of the tree model.

    • setVar

      public void setVar(String varName)
      Sets the name of the request attribute which exposes the wrapped data of the current node of the tree model.
      Parameters:
      varName - The name of the request attribute which exposes the wrapped data of the current node of the tree model.

    • getVarNode

      public String getVarNode()
      Returns the name of the request attribute which exposes the current node of the tree model.
      Returns:
      The name of the request attribute which exposes the current node of the tree model.

    • setVarNode

      public void setVarNode(String varNode)
      Sets the name of the request attribute which exposes the current node of the tree model.
      Parameters:
      varNode - The name of the request attribute which exposes the current node of the tree model.