webuijsf
Tag tree


Use the webuijsf:tree tag to display a tree structure in the rendered HTML page. The nodes of the tree are defined with webuijsf:treeNode tags. Trees are often used for navigating in a web application.

HTML Elements and Layout

The Tree component defines and renders a tree structure. A tree structure is commonly used for navigation through data, as in file system navigators. The base, or root, of the tree is shown at the top, with the branches going downward. The webuijsf:tree tag defines the root of the tree.

The tree is rendered with <div> XHTML elements which define rows as well as nesting within the tree.

The webuijsf:tree tag is the root of the tree, and is also a container for the webuijsf:treeNode tags. The webuijsf:treeNode tags add branches, or nodes, to the tree. The webuijsf:tree tag is also a special type of webuijsf:treeNode that has the ability to create a title bar for the root. The root of the tree is only visible when it includes a title bar.

In the rendered web page, a node can be expanded and collapsed when you click on the small icon next to the node, or when you click the node's hyperlink text. In addition, the node is highlighted when you click on the node's hyperlink to indicate the node has focus.

When the root of the tree is visible, it does not have handle icons, and cannot be expanded and collapsed.

Configuring the webuijsf:tree Tag

The webuijsf:tree tag creates the topmost tree node and can optionally render a title bar. If the title bar is not rendered, the tree component is not visible in the rendered HTML page. See Defining a Title Bar for more information.

The webuijsf:tree tag provides the ability to render the tree root in any of the following ways:

Defining a Title Bar

The title bar consists of the following elements:

The title bar can be defined with either webuijsf:tree tag attributes or facets. The title bar is rendered if the tree component includes imageURL property for the graphic, the text property for the title text, the content facet, or the image facet.

The title bar can be defined with either webuijsf:tree tag attributes or facets. The title bar is rendered if the tree component includes any of the following: the imageURL attribute for the graphic, the text attribute for the title text, the content facet, or the image facet.

Defining a Tree with Multiple Roots

To define a tree that has multiple roots rather than a single top root, you must use the webuijsf:tree tag only as a container. You should not specify attributes for the graphic or title text, or use facets in the webuijsf:tree tag.

You can use webuijsf:treeNode tags as containers for other webuijsf:treeNode tags, but should not use one to contain all the others to avoid the appearance of a single root.

Client-side and Server-side Trees

The webuijsf:tree tag can be used to create a client-side tree or server-side tree. By default the rendered tree is a server-side tree, and a request will be made to the server each time the tree is expanded or collapsed. Set the clientSide attribute to true to create a tree that handles expanding and collapsing in the browser. Client-side trees are most useful for navigating through the application.

If your tree needs to maintain its state across requests, you should use the server side tree. The server side tree also provides the ability to fire events when the node handles are clicked.

Dynamically Adding and Removing Tree Nodes

The webuijsf:tree and webuijsf:treeNode tags can be used to dynamically populate tree structures, by using the binding attribute to create Tree and TreeNode component instances programmatically through a backing bean. This approach is useful when tree data is not static, but must be calculated when the page is rendered. Another reason to dynamically populate a tree is to decrease the time needed to initially render a tree by waiting until a user opens a folder before adding the folder's child nodes. See the Examples section for sample code that implements dynamic nodes.

Facets

The Tree component supports the following facets:

content Replaces the default title bar with a custom component. When the content facet is used, the action, target, text, url, and toolTip attributes are ignored.
image Specifies the image area. When the image facet is used, the imageURL, action, target, url, and toolTip attributes are ignored.

Theme Identifiers

The following image keys might be useful for including theme images in tree nodes. To use these keys, use the image facet with a child component that supports the icon attribute, such as webuijsf:image and webuijsf:imageHyperlink.

TREE_BLANK
TREE_DOCUMENT
TREE_FOLDER
TREE_FOLDER_ALARM_MINOR
TREE_FOLDER_ALARM_MAJOR
TREE_FOLDER_ALARM_DOWN
TREE_FOLDER_ALARM_CRITICAL
TREE_SERVER
TREE_SERVER_CRITICAL
TREE_SERVER_DOWN
TREE_SERVER_MAJOR
TREE_SERVER_MINOR
TREE_STORAGE
TREE_STORAGE_MAJOR

Client Side Javascript Functions

The JavaScript functions listed in the following table are defined in a file that is referenced automatically by the Tree component. The functions are called automatically in the rendered HTML. You can also call these functions independently; you may choose to do this to select or expand/collapse a TreeNode on the client.

clearHighlight(treeNode) This function clears the highlighting for a particular TreeNode. The treeNode passed in is the id of the <div> element that surrounds the HTML code for the TreeNode. This id can be obtained by calling getElementById("<TreeNode.getClidentId()>").
expandCollapse(treeNode, event) This function expands or collapses the given tree node. The function expects the source of the given event object to be a tree handle image. The function swaps images that depict the node as expanded or collapsed. The handle image points right when the node is collapsed, and points down when the node is expanded.  This implementation requires the file names of the images to include the strings "tree_handleright" and "tree_handledown" to enable the images to be accurately displayed by swapping "right" and "down" in the name of the image file that is rendered.
getParentTreeNode(treeNode) This function returns the parent TreeNode of the given TreeNode.
getSelectedTreeNode(treeId) This function returns the selected TreeNode given the treeId of the Tree.
getTree(treeNode) This function provides access to the Tree object containing the given TreeNode.
highlight(treeNode) This function highlights the given TreeNode.The treeNode passed in is the id of the <div> element that surrounds the HTML code for the TreeNode. This id can be obtained by calling getElementById("<TreeNode.getClidentId()>").
highlightParent(treeNode) This function highlights the parent TreeNode of the given TreeNode, only if the given TreeNode is not visible. The parent is considered the first visible parent of this TreeNode. The treeNode passed in is the id of the <div> element that surrounds the HTML code for the child TreeNode. This id can be obtained by calling getElementById("<TreeNode.getClidentId()>").
isAnHref(event) This function checks to see if the event target is an href, or if any of the parent nodes which contain it is an href. To be considered an href, the target or parent node must be an <a> element with an href="..."  attribute that contains at least four characters. (Note: Browsers will add on the protocol if you supply a relative URL such as one starting with a '#', '/', or filename).
isTreeHandle(event) This function determines if the event source is a tree handle image. This implementation depends on the tree handle image file name containing "tree_handle". No other images can contain this string.
onTreeNodeClick(treeNode, event) This function handles TreeNode onClick events. The treeNode passed in is the id of the <div> element that surrounds the TreeNode that was clicked, in order to process the highlighting changes that are necessary. This id can be obtained by calling getElementById("<TreeNode.getClidentId()>"). If this function is invoked from the TreeNode <div> object itself (as is the case when this method is implicitly called), the TreeNode object is simply the this variable.
selectTreeNode(treeNode) This function may be used to select the given TreeNode. The function clears the previous TreeNode and selects the given one.
treeNodeIsExpanded(treeNode) This function determines if the given TreeNode is expanded. The function returns true if the node is expanded, or false if collapsed.
unhighlightParent(treeNode) This function removes parent highlighting from the parent TreeNode of the given TreeNode, only if the given TreeNode is not visible. The parent is considered the first visible parent of this TreeNode. The treeNode passed in is the id of the <div> element that surrounds the HTML code for the child TreeNode. This id can be obtained by calling getElementById("<TreeNode.getClidentId()>").
updateHightlight(id) This function updates the highlighting for the given Tree client id. This function provides a way to restore the highlighting when a Tree is reloaded in a window (necessary for each page load).

Examples

The following examples are included:

Example 1: Multi-Root Tree

This example shows a simple multiple root tree.

<webuijsf:tree id="TreeExample1" >
        <webuijsf:treeNode id="node0" expanded="false" text="Accessibility" url="#">
            <webuijsf:treeNode id="node0_1" text="Access Key" url="#">
            </webuijsf:treeNode>
        </webuijsf:treeNode>
        <webuijsf:treeNode id="node1" expanded="false" text="Getting Started with Solaris" url="#">
            <webuijsf:treeNode id="node1_1" text="Registering with Sun Microsystems, Inc." url="#">
            </webuijsf:treeNode>
        </webuijsf:treeNode>
        <webuijsf:treeNode id="node2" expanded="true" text="Storage Management" url="#">
            <webuijsf:treeNode id="node2_1" text="Getting Started with Storage" url="#">
            <webuijsf:treeNode id="node2_1_1" text="Checking Volume Status" url="#">
            </webuijsf:treeNode>
            </webuijsf:treeNode>
            <webuijsf:treeNode id="node2_2" text="Storage Hardware" url="#">
            </webuijsf:treeNode>
            <webuijsf:treeNode id="node2_3" text="RAID Levels" url="#">
            </webuijsf:treeNode>
            <webuijsf:treeNode id="node2_4" text="Choosing Storage" url="#">
            </webuijsf:treeNode>
            <webuijsf:treeNode id="node2_5" text="Random I/O" url="#">
            </webuijsf:treeNode>
        </webuijsf:treeNode>

</webuijsf:tree>

Example 2: Client-side Tree

This example shows a client-side tree with nodes that use actions, urls, or static text. The example also uses the image facet to use a theme icon in the tree title bar.

 <webuijsf:tree id="TreeExample1" text="Client-side Tree" url="#" clientSide="true">
        <f:facet name="image">
            <webuijsf:image id="image" icon="TREE_FOLDER_ALARM_CRITICAL" />
        </f:facet>
        <webuijsf:treeNode id="node0" expanded="true"
                      text="Node with action set to navigation rule" action="hyperlinkPage">
            <f:facet name="image">
            <webuijsf:image id="image" icon="TREE_FOLDER_ALARM_CRITICAL" />
            </f:facet>
            <webuijsf:treeNode id="node1" expanded="true"
                          text="Node with action set to managed bean method"
                action="#{HyperlinkBean.success}">
            <f:facet name="image">
                <webuijsf:image id="image" icon="TREE_FOLDER_ALARM_CRITICAL" />
            </f:facet>
            <webuijsf:treeNode id="node1_1" text="Node with static text">
                <f:facet name="image">
                <webuijsf:image id="image" icon="TREE_SERVER" />
                </f:facet>
            </webuijsf:treeNode>
            <webuijsf:treeNode id="node1_2" text="Node with a URL" url="http://www.google.com/">
                <f:facet name="image">
                <webuijsf:image id="image" icon="TREE_SERVER_CRITICAL" />
                </f:facet>
            </webuijsf:treeNode>
            </webuijsf:treeNode>
            <webuijsf:treeNode id="node2" text="Building 10" url="#">
            <f:facet name="image">
                <webuijsf:image id="image" icon="TREE_FOLDER" />
            </f:facet>
            <webuijsf:treeNode id="node1_2" text="Skippy" url="#">
                <f:facet name="image">
                <webuijsf:image id="image" icon="TREE_SERVER" />
                </f:facet>
            </webuijsf:treeNode>
            </webuijsf:treeNode>
        </webuijsf:treeNode>
        <webuijsf:treeNode id="node3" expanded="true" text="Building 2" url="#">
            <f:facet name="image">
            <webuijsf:image id="image" icon="TREE_FOLDER" />
            </f:facet>
            <webuijsf:treeNode id="node3_1" text="Arizona" url="#">
            <f:facet name="image">
                <webuijsf:image id="image" icon="TREE_SERVER" />
            </f:facet>
            </webuijsf:treeNode>
        </webuijsf:treeNode>
        </webuijsf:tree>

Example 3: Server-Side Tree with content Facet

This example shows a server-side tree that uses a webuijsf:dropDown tag to create the content area in the title bar of the tree.

 <webuijsf:tree id="TreeExample3" url="#">
        <f:facet name="content">
            <webuijsf:dropDown id="airport" submitForm="true" items="#{BackingFileChoice.airports}" />
        </f:facet>
        <webuijsf:treeNode id="node0" expanded="true" text="Paducah" url="#">
            <f:facet name="image">
               <webuijsf:image id="image" icon="TREE_FOLDER_ALARM_MINOR" />
            </f:facet>
            <webuijsf:treeNode id="node1" expanded="true" text="Building 1" url="#">
              <f:facet name="image">
                <webuijsf:image id="image" icon="TREE_FOLDER_ALARM_MINOR" />
              </f:facet>
            <webuijsf:treeNode id="node1_1" text="Kenga">
              <f:facet name="image">
                <webuijsf:image id="image" icon="TREE_SERVER" />
              </f:facet>
            </webuijsf:treeNode>
            <webuijsf:treeNode id="node1_2" text="Crocker" url="#">
              <f:facet name="image">
                <webuijsf:image id="image" icon="TREE_SERVER_MINOR" />
              </f:facet>
            </webuijsf:treeNode>
        </webuijsf:treeNode>
       
        <webuijsf:treeNode id="node5" expanded="true" text="Building 4" url="#">
            <f:facet name="image">
              <webuijsf:image id="image" icon="TREE_FOLDER_ALARM_MAJOR" />
            </f:facet>
            <webuijsf:treeNode id="node5_1" text="Neptune" url="#">
              <f:facet name="image">
                <webuijsf:image id="image" icon="TREE_STORAGE_MAJOR" />
              </f:facet>
            </webuijsf:treeNode>
            <webuijsf:treeNode id="node5_2" text="Zeus" url="#">
            <f:facet name="image">
                <webuijsf:image id="image" icon="TREE_STORAGE" />
            </f:facet>
            </webuijsf:treeNode>
           </webuijsf:treeNode>
        </webuijsf:treeNode>   
 </webuijsf:tree>

Example 4: Dynamic Tree

This example shows how to dynamically add or remove nodes from the tree. It also shows one way to dynamically add nodes to a folder when that folder is expanded. Each time a user expands Folder 3, three new nodes are added to it. The backing bean used in this example is included after the example.

Note that you cannot delete nodes that are declared in the JSP. In this example, you cannot delete the root node (defined by webuijsf:tree) and the first three child nodes, folder1, folder2, and folder3 (defined by webuijsf:treeNode tags).

<webuijsf:tree id="dynamicTree" binding="#{TestTreeBean.dynamicTree}">
  <webuijsf:treeNode id="folder1" binding="#{TestTreeBean.folder1}" />   
  <webuijsf:treeNode id="folder2" binding="#{TestTreeBean.folder2}" />       
  <webuijsf:treeNode id="folder3" text="Folder3" url="#" actionListener="#{TestTreeBean.nodeExpanded}" >
    <webuijsf:treeNode id="folder3Child1" text="Folder 3 Child 1" url="#" />
  </webuijsf:treeNode>
</webuijsf:tree>

<webuijsf:button id="addButton" text="Add Child to Selected Node" action="#{TestTreeBean.addNode}" />
<webuijsf:button id="deleteButton" text="Delete Selected Node" action="#{TestTreeBean.deleteNode}" />

TestTreeBean.java Backing Bean

The following backing bean is used by the Dynamic Tree example.

public class TestTreeBean {

    ... other code removed for readability ....

    private Tree dynamicTree = null;

    public Tree getDynamicTree() {
        if (dynamicTree == null) {
            dynamicTree = new Tree();
            dynamicTree.setText("Dynamic Tree Behavior Test");
        }

        return dynamicTree;
    }

    public void setDynamicTree(Tree t) {
        dynamicTree = t;
    }

    private TreeNode folder1 = null;

    public TreeNode getFolder1() {
        if (folder1 == null) {
            folder1 = new TreeNode();
            folder1.setUrl("#");
            folder1.setText("Folder 1");
            folder1.setExpanded(true);
        }

        return folder1;
    }

    public void setFolder1(TreeNode n) {
        folder1 = n;
    }

    private TreeNode folder2 = null;

    public TreeNode getFolder2() {
        if (folder2 == null) {
            folder2 = new TreeNode();
            folder2.setUrl("#");
            folder2.setText("Folder 2");
            folder2.setExpanded(true);
        }

        return folder2;
    }

    public void setFolder2(TreeNode n) {
        folder2 = n;
    }

    // int counter to name new nodes with
    int i = 0;

    ⁄**
     * This action listener method will be called when Folder 3's
     * turner IconHyperlink is clicked.
     *⁄
    public void nodeExpanded(ActionEvent event) {
        TreeNode node = (TreeNode) event.getComponent();

        if (!node.isExpanded()) {
            for (int j = 0; j < 3; j++) {
                TreeNode newNode = createNode(i++);
                node.getChildren().add(newNode);
            }
        }
    }

    private TreeNode createNode(int id) {
        TreeNode node = new TreeNode();
        node.setId("node" + i);
        node.setText("Node " + i);
        node.setUrl("#");

        return node;
    }

    ⁄**
     * This action method is called when the "Add Child to Selected
     * Node" button is pressed.
     *⁄
    public String addNode() {

        String nodeId = getDynamicTree().getSelected();

        if (nodeId == null) {
            return "";
        }

        UIComponent node = getDynamicTree().findComponent(":" + nodeId);

        if (node != null) {
            TreeNode newNode = createNode(i++);
            node.getChildren().add(newNode);
        }

        return "";
    }

    ⁄**
     * This action method is called when the "Delete Selected Node"
     * button is pressed.
     *⁄
    public String deleteNode() {
        String nodeId = (String) getDynamicTree().getSelected();

        if (nodeId == null) {
            return "";
        }

        UIComponent node = getDynamicTree().findComponent(":" + nodeId);

        if (node != null) {
            UIComponent parent = node.getParent();

            List kids = parent.getChildren();
            kids.remove((Object) node);
        }

        return "";
    }



Tag Information
Tag Classcom.sun.webui.jsf.component.TreeTag
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone

Attributes
NameRequiredRequest-timeTypeDescription
bindingfalsefalsejava.lang.String A ValueExpression that resolves to the UIComponent that corresponds to this tag. This binding allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children.
imageURLfalsefalsejava.lang.String Absolute or relative URL to the image to be rendered for the tree node. Note that you cannot use the imageURL to display a theme image in the tree. You should use an image facet that contains a ui:image or ui:imageHyperlink tag to use a theme image. The imageURL attribute is overridden by the image facet.

When the imageURL attribute is used with the url attribute, the image is hyperlinked.

requiredfalsefalsejava.lang.String

Flag indicating that the user must select a value for this tree. Default value is false.

@deprecated: This attribute is deprecated from 4.1 and should not be used as it does not make much sense in the context of the tree.
actionExpressionfalsefalsejava.lang.String The action attribute is used to specify the action to take when this component is activated by the user. The value of the action attribute must be one of the following:
  • an outcome string, used to indicate which page to display next, as defined by a navigation rule in the application configuration resource file (faces-config.xml).
  • a JavaServer Faces EL expression that resolves to a backing bean method. The method must take no parameters and return an outcome string. The class that defines the method must implement the java.io.Serializable interface or javax.faces.component.StateHolder interface.

In the Tree and TreeNode components, the action applies only when attributes are used to define the tree and tree nodes. When facets are used, the action attribute does not apply to the facets.

clientSidefalsefalsejava.lang.String

Set the clientSide attribute to true to specify that the Tree component should run on the client. By default, this attribute is false, so the Tree component interacts with the server. In a client-side tree, expanding and collapsing of the tree nodes happens only in the browser. In a server-side tree, a request is made to the server each time the tree nodes are expanded or collapsed. If you use the actionListener attribute to fire events, you must use a server side tree so that the event can be processed.

targetfalsefalsejava.lang.String The resource at the specified URL is displayed in the frame that is specified with the target attribute. Values such as "_blank" that are valid for the target attribute of the HTML element are also valid for this attribute in the tree components. The target attribute is useful only with the url attribute, and does not apply when a facet is used.
renderedfalsefalsejava.lang.String Use the rendered attribute to indicate whether the HTML code for the component should be included in the rendered HTML page. If set to false, the rendered HTML page does not include the HTML for the component. If the component is not rendered, it is also not processed on any subsequent form submission.
idfalsetruejava.lang.StringNo Description
styleClassfalsefalsejava.lang.String

CSS style class(es) to be applied to the outermost HTML element when this component is rendered.

selectedfalsefalsejava.lang.String

Returns the id of the selected tree node. Should be cast to a String and nothing else.

immediatefalsefalsejava.lang.String

Flag indicating that event handling for this component should be handled immediately (in Apply Request Values phase) rather than waiting until Invoke Application phase. May be desired for this component when required is true (although most likely not).

actionListenerExpressionfalsefalsejava.lang.String The actionListener attribute is used to specify a method to handle an action event that is triggered when a component is activated by the user. The actionListener attribute value must be a JavaServer Faces EL expression that resolves to a method in a backing bean. The method must take a single parameter that is an ActionEvent, and its return type must be void. The class that defines the method must implement the java.io.Serializable interface or javax.faces.component.StateHolder interface.

In the TreeNode component, the method specified with the actionListener atttribute is invoked when the node's handle icon is clicked.

expandOnSelectfalsefalsejava.lang.String

Flag indicating that folder / container nodes will automatically expand when they are selected. This attribute is true by default. If you want a tree's container nodes to expand only when the handle icons are clicked, set expandOnSelect to false.

stylefalsefalsejava.lang.String

CSS style(s) to be applied to the outermost HTML element when this component is rendered.

visiblefalsefalsejava.lang.String

Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page. If set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, visible is set to true, so HTML for the component HTML is included and visible to the user. If the component is not visible, it can still be processed on subsequent form submissions because the HTML is present.

urlfalsefalsejava.lang.String Indicates that the text that is specified with the text attribute should be rendered as a hyperlink that resolves to the specified URL. If the imageURL attribute is used with the url attribute, the image is hyperlinked. The url attribute does not apply to facets.
toolTipfalsefalsejava.lang.String

Sets the value of the title attribute for the HTML element. The specified text will display as a tooltip if the mouse cursor hovers over the HTML element.

textfalsefalsejava.lang.String

Specifies the text for this component. If the url or action attributes are also specified, the text is rendered as a hyperlink. If neither the url or action attributes are specified, the specified text is rendered as static text. The text attribute does not apply when the content facet is used.


Variables
No Variables Defined.


Output Generated by Tag Library Documentation Generator. Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-4 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.