| Use the ui:tree tag to display a tree structure in the
rendered HTML page. 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 tree is rendered with <div> XHTML elements which
define rows as well as nesting within the tree.
The ui:tree tag is the root of the tree, and acts as a
container for the ui:treeNode tags. The
ui:treeNode tags add branches, or nodes, to the tree. In
the rendered web page, nodes can be expanded and collapsed when you
click on small icons next to the nodes. In addition, the node is
highlighted when you click on the node's hyperlink to indicate the node
has focus.
The ui: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 visually
distinctive. You must specify attributes or facets in the
ui:tree tag to allow the title bar to be rendered.
- As a single root, without a title bar. The root looks like any
other container node in the tree. You must omit attributes and
facets in the
ui:tree tag, and specify a single
ui:treeNode as the root node, with other
ui:treeNode tags contained within the first
ui: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
ui:tree tag and include multiple
ui:treeNode tags.
Defining a Title Bar for the Single Root Tree
The title bar consists of the following elements:
- A shaded background color determined by the theme.
- An optional graphic to the left of the title bar's text.
- Text or a hyperlink for the content of the title bar.
The title bar can be defined with either ui: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 graphic and title text areas can be overridden with the following
facets:
-
content
--
Specifies the text or hyperlink for the title bar. When the
content facet is used, the text and hyperlink
properties have no effect.
-
image
--
Specifies the image area. When the image facet is
used, image properties have no effect.
Defining a Tree with Multiple Roots
To define a tree that has multiple roots rather than a single top root,
you must use the ui:tree tag only as a container. You
should not specify attributes for the graphic or title text, or use
facets in the ui:tree tag.
You can use ui:treeNode tags as containers for other
ui:treeNode tags, but should not use one to contain all
the others to avoid the appearance of a single root.
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.
-
clearHightlight(treeNode)
--
This function clears the highlighting for a particular
TreeNode. The treeNode passed in should be the
<div> around the html for the TreeNode. This
may be obtained by calling
getElementById("<TreeNode.getClidentId()>").
-
expandCollapse(treeNode, event)
--
This function expands or collapses the given tree node. It
expects the source of the given event object (if supplied) to
be a tree handle image. It will change this image to point in
the correct direction (right or down). This implementation
depends on the tree handle image names including
"tree_handleright" and "tree_handledown" in them. Swapping
"right" and "down" in these names must change the handle
direction to right and down respectively.
-
getParentTreeNode(treeId)
--
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 <div> around
the html for the TreeNode and may be obtained by calling
getElementById("<TreeNode.getClidentId()>").
-
highlightParent(treeNode)
--
This function highlights the parent TreeNode of the given
TreeNode. It only does so if the given TreeNode is not
visible. The parent is considered the first visible parent of
this TreeNode. The treeNode passed in is the
<div> around the html for the child TreeNode
and may be obtained by calling
getElementById("<TreeNode.getClidentId()>").
-
isAnHref(event)
--
This method checks to see if the event.target is an href, or if
any of the parent nodes which contain it is an href. To
considered an href, it must be an "A" tag with an "href"
attribute containing atleast 4 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 was a tree handle
image. This implementation depends on the tree handle image
file name containing "tree_handle" and no other images
containing this string.
-
onTreeNodeClick(treeNode)
--
This function Takes in the TreeNode <div> object that was
clicked in order to process the highlighting changes that are
necessary. This object may 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. It will
clear the previous TreeNode and select the given one.
-
treeNodeIsExpanded(treeNode)
--
This function determines if the given TreeNode is expanded. It
returns true if it is, false
otherwise.
-
unhighlightParent(treeNode)
--
This function un-applies parent highlighting to the parent
TreeNode of the given TreeNode. It only does so if the given
TreeNode is not visible. The parent is considered the
first visible parent of this TreeNode. The
treeNode passed in is the <div> element
around the html for the TreeNode and may 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 each page load).
Example:
Below is an example showing how a tree may be defined in a JSP
page:
<ui:tree id="MyTree" text="hi">
<f:facet name="image">
<ui:image id="image" icon="TREE_SERVER" />
</f:facet>
<ui:treeNode id="Node0" text="About..." />
<ui:treeNode id="Node1" expanded="true" text="External URLs">
<f:facet name="image">
<ui:image id="image" icon="TREE_SERVER" />
</f:facet>
<ui:treeNode id="Node1_1" text="Sun Microsystems, Inc." url="http://www.sun.com" target="external">
<f:facet name="image">
<ui:image id="image" icon="TREE_STORAGE_MAJOR" />
</f:facet>
</ui:treeNode>
<ui:treeNode id="Node1_2" text="Search Engines">
<ui:treeNode id="Node1_2_1" text="Google" url="http://www.google.com" imageURL="../images/google.jpg" target="external" />
<ui:treeNode id="Node1_2_2" text="Yahoo!" url="http://www.yahoo.com" imageURL="../images/yahoo.jpg" target="external" />
<ui:treeNode id="Node1_2_3" text="Lycos" url="http://www.lycos.com" target="external">
<f:facet name="image">
<ui:image id="image" url="http://ly.lygo.com/ly/srch/hp/dog_web_34x35.gif" height="16" width="16" />
</f:facet>
</ui:treeNode>
</ui:treeNode>
</ui:treeNode>
</ui:tree>
Auto-generated component class.
Do NOT modify; all changes
will be lost!
| 