| |||||||
FRAMES NO FRAMES |
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.
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.
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:
As a single root, with a title bar to make the root visible.
You must specify attributes or facets in the
webuijsf:tree
tag to allow the title bar to be rendered.
See Defining a Title Bar
for more information.
As a single root, without a title bar. The root is invisible,
and a treeNode component is used as a single "root".
This treeNode is like any other container node in the tree, and
includes handle icons for expanding and collapsing.
You must omit attributes and
facets in the webuijsf:tree
tag, and specify a single
webuijsf:treeNode
as the root node, with other
webuijsf:treeNode
tags contained within the first
webuijsf:treeNode
.
As a multi-root tree, without a title bar. There is no single top
node, but two or more at the same level. You must omit attributes
and facets in the webuijsf:tree
tag and include multiple
webuijsf:treeNode
tags. See
Defining a Tree with Multiple Roots
for more information.
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.
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.
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.
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.
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. |
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
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). |
The following examples are included:
image
Facetcontent
FacetThis 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>
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>
content
FacetThis 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>
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}" />
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 Class | com.sun.webui.jsf.component.TreeTag |
TagExtraInfo Class | None |
Body Content | JSP |
Display Name | None |
Attributes | ||||
Name | Required | Request-time | Type | Description |
binding | false | false | java.lang.String | A ValueExpression that resolves to the UIComponent that corresponds to this tag. This attribute allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children. |
imageURL | false | false | java.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. |
required | false | false | java.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. |
actionExpression | false | false | java.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:
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. |
clientSide | false | false | java.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. |
target | false | false | java.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. |
rendered | false | false | java.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. |
id | false | true | java.lang.String | No Description |
styleClass | false | false | java.lang.String | CSS style class(es) to be applied to the outermost HTML element when this component is rendered. |
selected | false | false | java.lang.String | Returns the id of the selected tree node. Should be cast to a String and nothing else. |
immediate | false | false | java.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). |
actionListenerExpression | false | false | java.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. |
expandOnSelect | false | false | java.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. |
style | false | false | java.lang.String | CSS style(s) to be applied to the outermost HTML element when this component is rendered. |
visible | false | false | java.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. |
url | false | false | java.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. |
toolTip | false | false | java.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. |
text | false | false | java.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. |
| |||||||
FRAMES NO FRAMES |