com.sun.rave.web.ui.component
Class TreeBase

java.lang.Object
  javax.faces.component.UIComponent
      javax.faces.component.UIComponentBase
          com.sun.rave.web.ui.component.TemplateComponentBase
              com.sun.rave.web.ui.component.TreeNodeBase
                  com.sun.rave.web.ui.component.TreeNode
                      com.sun.rave.web.ui.component.TreeBase

All Implemented Interfaces:

ChildManager, javax.faces.component.NamingContainer, javax.faces.component.StateHolder, TemplateComponent

Direct Known Subclasses:

Tree

public abstract class TreeBase

extends TreeNode

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!

Field Summary

Fields inherited from class com.sun.rave.web.ui.component.TreeNode

CONTENT_FACET_KEY, IMAGE_FACET_KEY, LAYOUT_KEY

Fields inherited from interface javax.faces.component.NamingContainer

SEPARATOR_CHAR

Constructor Summary

TreeBase()
Construct a new TreeBase.

Method Summary

java.lang.String	getFamily() Return the family for this component.
java.lang.String	getSelected() Specifies the client id of the selected tree node.
java.lang.String	getStyle() CSS style(s) to be applied when this component is rendered.
java.lang.String	getStyleClass() CSS style class(es) to be applied when this component is rendered.
java.lang.String	getText() The text displayed at root of the tree
boolean	isClientSide() Specifies if this Tree should run on the client, or if it should interact with the server.
boolean	isExpandOnSelect() Flag indicating that folder / container nodes will automatically expand when they are selected.
boolean	isImmediate() Indicate that event handling for this component should be handled immediately (in Apply Request Values phase) rather than waiting until Invoke Application phase.
boolean	isRequired() Indicates that the user must select a value for this tree.
boolean	isVisible() Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page.
void	restoreState(javax.faces.context.FacesContext _context, java.lang.Object _state) Restore the state of this component.
java.lang.Object	saveState(javax.faces.context.FacesContext _context) Save the state of this component.
void	setClientSide(boolean clientSide) Specifies if this Tree should run on the client, or if it should interact with the server.
void	setExpandOnSelect(boolean expandOnSelect) Flag indicating that folder / container nodes will automatically expand when they are selected.
void	setImmediate(boolean immediate) Indicate that event handling for this component should be handled immediately (in Apply Request Values phase) rather than waiting until Invoke Application phase.
void	setRequired(boolean required) Indicates that the user must select a value for this tree.
void	setSelected(java.lang.String selected) Specifies the client id of the selected tree node.
void	setStyle(java.lang.String style) CSS style(s) to be applied when this component is rendered.
void	setStyleClass(java.lang.String styleClass) CSS style class(es) to be applied when this component is rendered.
void	setText(java.lang.String text) The text displayed at root of the tree
void	setVisible(boolean visible) Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page.

Methods inherited from class com.sun.rave.web.ui.component.TreeNode

addActionListener, fireTurnerEvent, getActionListeners, getHandleIcon, getImageKeys, getParentTreeNode, removeActionListener, toggleNode

Methods inherited from class com.sun.rave.web.ui.component.TreeNodeBase

getAction, getActionListener, getImageURL, getTarget, getToolTip, getUrl, isExpanded, setAction, setActionListener, setExpanded, setImageURL, setTarget, setToolTip, setUrl

Methods inherited from class com.sun.rave.web.ui.component.TemplateComponentBase

getChild, getChild, getLayoutDefinition, getLayoutDefinitionKey, setLayoutDefinitionKey

Methods inherited from class javax.faces.component.UIComponentBase

addFacesListener, broadcast, decode, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientId, getFacesContext, getFacesListeners, getFacet, getFacets, getFacetsAndChildren, getId, getParent, getRenderer, getRendererType, getRendersChildren, getValueBinding, isRendered, isTransient, processDecodes, processRestoreState, processSaveState, processUpdates, processValidators, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient, setValueBinding

Methods inherited from class java.lang.Object

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

Constructor Detail

TreeBase

public TreeBase()

Construct a new TreeBase.

Method Detail

getFamily

public java.lang.String getFamily()

Return the family for this component.

Overrides:

getFamily in class TreeNodeBase

isClientSide

public boolean isClientSide()

Specifies if this Tree should run on the client, or if it should interact with the server. If it runs on the client, then clicking on the tree icon to expand or collapse portions of the tree will happen only on the client (browser). Otherwise, it will make a request to the server each time the tree is expanded or collapsed.

setClientSide

public void setClientSide(boolean clientSide)

Specifies if this Tree should run on the client, or if it should interact with the server. If it runs on the client, then clicking on the tree icon to expand or collapse portions of the tree will happen only on the client (browser). Otherwise, it will make a request to the server each time the tree is expanded or collapsed.

See Also:

isClientSide()

isExpandOnSelect

public boolean isExpandOnSelect()

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.

setExpandOnSelect

public void setExpandOnSelect(boolean expandOnSelect)

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.

See Also:

isExpandOnSelect()

isImmediate

public boolean isImmediate()

Indicate that event handling for this component should be handled immediately (in Apply Request Values phase) rather than waiting until Invoke Application phase.

setImmediate

public void setImmediate(boolean immediate)

Indicate that event handling for this component should be handled immediately (in Apply Request Values phase) rather than waiting until Invoke Application phase.

See Also:

isImmediate()

isRequired

public boolean isRequired()

Indicates that the user must select a value for this tree.

setRequired

public void setRequired(boolean required)

Indicates that the user must select a value for this tree.

See Also:

isRequired()

getSelected

public java.lang.String getSelected()

Specifies the client id of the selected tree node.

setSelected

public void setSelected(java.lang.String selected)

Specifies the client id of the selected tree node.

See Also:

getSelected()

getStyle

public java.lang.String getStyle()

CSS style(s) to be applied when this component is rendered.

Overrides:

getStyle in class TreeNodeBase

setStyle

public void setStyle(java.lang.String style)

CSS style(s) to be applied when this component is rendered.

Overrides:

setStyle in class TreeNodeBase

See Also:

getStyle()

getStyleClass

public java.lang.String getStyleClass()

CSS style class(es) to be applied when this component is rendered.

Overrides:

getStyleClass in class TreeNodeBase

setStyleClass

public void setStyleClass(java.lang.String styleClass)

CSS style class(es) to be applied when this component is rendered.

Overrides:

setStyleClass in class TreeNodeBase

See Also:

getStyleClass()

getText

public java.lang.String getText()

The text displayed at root of the tree

Overrides:

getText in class TreeNodeBase

setText

public void setText(java.lang.String text)

The text displayed at root of the tree

Overrides:

setText in class TreeNodeBase

See Also:

getText()

isVisible

public boolean isVisible()

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.

Overrides:

isVisible in class TreeNodeBase

setVisible

public void setVisible(boolean visible)

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.

Overrides:

setVisible in class TreeNodeBase

See Also:

isVisible()

restoreState

public void restoreState(javax.faces.context.FacesContext _context,
                         java.lang.Object _state)

Restore the state of this component.

Specified by:

restoreState in interface javax.faces.component.StateHolder

Overrides:

restoreState in class TreeNodeBase

saveState

public java.lang.Object saveState(javax.faces.context.FacesContext _context)

Save the state of this component.

Specified by:

saveState in interface javax.faces.component.StateHolder

Overrides:

saveState in class TreeNodeBase