org.omnifaces.component.tree

Class Tree

java.lang.Object

javax.faces.component.UIComponent

javax.faces.component.UIComponentBase

org.omnifaces.component.tree.TreeFamily

org.omnifaces.component.tree.Tree

All Implemented Interfaces:

EventListener, NamingContainer, PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder

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 JSF 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:

TreeNode, TreeNodeItem, TreeInsertChildren, TreeFamily, TreeModel, AbstractTreeModel, ListTreeModel, SortedTreeModel

Field Summary

Fields

Modifier and Type	Field and Description
static String	COMPONENT_TYPE The standard component type.

Fields inherited from class org.omnifaces.component.tree.TreeFamily

COMPONENT_FAMILY

Fields inherited from class javax.faces.component.UIComponent

ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, CURRENT_COMPONENT, CURRENT_COMPOSITE_COMPONENT, FACETS_KEY, HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME, VIEW_LOCATION_KEY

Fields inherited from interface javax.faces.component.NamingContainer

SEPARATOR_CHAR

Constructor Summary

Constructors

Constructor and Description
Tree()

Method Summary

Modifier and Type	Method and Description
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.
String	getContainerClientId(FacesContext context) An override which appends the index of the current model node to the client ID chain, if any available.
protected TreeModel	getCurrentModelNode() Returns the current node of the tree model.
Object	getValue() Returns the tree model.
String	getVar() Returns the name of the request attribute which exposes the wrapped data of the current node of the tree model.
String	getVarNode() Returns the name of the request attribute which exposes the current node of the tree model.
protected boolean	isVisitable(VisitContext context)
protected void	process(FacesContext context, PhaseId phaseId) Set the root node as current node and delegate the call to processTreeNode(FacesContext, PhaseId).
protected void	processTreeNode(FacesContext context, PhaseId phaseId) If the current model node isn't a leaf (i.e.
void	queueEvent(FacesEvent event) An override which wraps the given faces event in a specific faces event which remembers the current model node.
protected void	setCurrentModelNode(FacesContext context, TreeModel currentModelNode) Sets the current node of the tree model.
void	setValue(Object value) Sets the tree model.
void	setValueExpression(String name, ValueExpression binding) An override which checks if this isn't been invoked on var or varNode attribute.
void	setVar(String var) Sets the name of the request attribute which exposes the wrapped data of the current node of the tree model.
void	setVarNode(String varNode) Sets the name of the request attribute which exposes the current node of the tree model.
protected void	validateHierarchy() Validate the component hierarchy.
boolean	visitTree(VisitContext context, VisitCallback callback) Set the root node as current node and delegate the call to visitTreeNode(VisitContext, VisitCallback).
protected boolean	visitTreeNode(VisitContext context, VisitCallback callback) If the current model node isn't a leaf (i.e.

Methods inherited from class org.omnifaces.component.tree.TreeFamily

encodeChildren, getFamily, getRendersChildren, processDecodes, processSuper, processUpdates, processValidators

Methods inherited from class javax.faces.component.UIComponentBase

addClientBehavior, addFacesListener, clearInitialState, decode, encodeBegin, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getListenersForEventClass, getParent, getPassThroughAttributes, getRenderer, getRendererType, getValueBinding, invokeOnComponent, isRendered, isTransient, markInitialState, processRestoreState, processSaveState, removeFacesListener, restoreAttachedState, restoreState, saveAttachedState, saveState, setId, setParent, setRendered, setRendererType, setTransient, setValueBinding, subscribeToEvent, unsubscribeFromEvent

Methods inherited from class javax.faces.component.UIComponent

encodeAll, getClientId, getCompositeComponentParent, getCurrentComponent, getCurrentCompositeComponent, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isInView, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

COMPONENT_TYPE

public static final String COMPONENT_TYPE

The standard component type.

See Also:

Constant Field Values

Constructor Detail

Tree

public Tree()

Method Detail

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:

TreeModel.getIndex()

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

Validate the component hierarchy.

Specified by:

validateHierarchy in class TreeFamily

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 UIComponent

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:

TreeModel.isLeaf(), TreeModel.getLevel(), TreeInsertChildren

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:

TreeModel.isLeaf(), TreeModel.getLevel(), TreeInsertChildren

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

Sets the name of the request attribute which exposes the wrapped data of the current node of the tree model.

Parameters:

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