The JWL Tree component

The hierarchical organisation of data stored on the client

JWL (The JSF Widget Library) consists of a large number of complex components. These enable you to speedily build rich and reliable Web applications. The Tree Control is a prime example of such a component. The JWL components are currently shipping with IBM Websphere Studio Application Developer 5.1.2 (WSAD), IBM Rational Application Developer 6.0 (IRAD) and beyond. The tooling provided by IRAD allows you to simply and quickly develop complex Web applications using these components. This article will explain how to bind data to the JWL Tree component and easily configure the component to organise, manage, and display the data with minimal coding required.

Share:

Breffni Coffey (breffni.coffey@ie.ibm.com), Software Engineer, IBM, Software Group

Breffni CoffeyBreffni Coffey has been a member of the IBM Dublin Software Lab, Ireland since September 2002. She graduated with a BSc in Computer Applications from Dublin City University, Ireland and is a Sun-certified Java Developer. She joined the JWL team in September 2004 as lead developer for the JWL Tree Control.



20 December 2005

Also available in

JWL downloads

Downloads of the JWL are available from the JWL Community Source Site. The files section contains both daily and release builds. An IBM intranet id and password are required to access this site

Introduction to the JWL Tree component

The JavaServer Faces™ (JSF™) Widget Library (JWL) Tree component provides a hierarchical structure to store data on the browser. So how does it differ from a regular tree component on the browser? Well the Tree implements a feature unique to certain components in the JWL library. It supports client-side data storage. This means faster access to data, quicker page refreshes and less roundtrips to the server. The Tree component supports many other features that make it superior as both a user-friendly and extremely powerful Web component. From a user interface (UI) configuration point of view, you can fully configure the Tree either within IRAD or, if you're a more expert JWL user, in any text editor. All icons can be changed using the properties pane within IRAD. There is also the option to specify a Tree's maximum height and width, and there is a tree.css style sheet that enables you to configure the more intricate details of the Tree's appearance on the browser. The JWL component also has a number of custom event handlers at both a tree and node level. These can be used to trigger any user-defined event. It can also be used to interact with other JWL components on a page to provide a purely client-side relationship between components. All these features are explained in detail in the following sections.


Creating a basic Tree control in IRAD

In IRAD, complete the following steps to create a JavaServer Page™ (JSP™) containing a basic JWL Tree control and run it on the server:

  1. In the Web perspective in IRAD, create a new Dynamic Web Project.
  2. Import the SampleModel bean at the bottom of this page into your project by right-clicking the Java Source folder and selecting the Import option.
  3. Create a new bean in the Page Data view using the root object from the newly-imported SampleModel.
  4. Create client data in the client data view from the page data. Change from the Design view to the Source view on the display (shown in Figure 1) and you will see the following tag appear on your JSP.
    Figure 1. Switch to source view
    Switch to source view
    <odc:clientData modelName="" value="#{pc_TreeSample.myBean}"
    id="clientData1" >
    <f:actionListener type="com.ibm.faces.bf.listeners.DiffListener">
    </odc:clientData">
  5. Drag the Tree component onto the page from the Faces Client Drawer on the right of the screen.
  6. Drag the bean from the Client Data view and drop it onto the Tree.
  7. Review the source code at this point. Note the client binder tag. This identifies the data bound to the Tree control.
    <odc:tree styleClass="tree" rootVisibleFlag="true" 
    enableSelect="false" id="tree1" >
    <odc:clientBinder alue="#{pc_TreeSample.myBean} >
    </odc:clientBinder >
    <odc:treeNodeAttr attributeName="name" 
    className="com.ibm.odcb.tutorial.businessobjects.Root" 
    id="treenodeattr1" >
    </odc:treeNodeAttr >
    </odc:tree >
  8. Select the tree in the design view. Note that the Tree's properties are now on display and available for configuration in the Property panel at the bottom of the screen.
  9. Clean and rebuild your project.
  10. Run it on the server.

Tree Attributes & Events

The following are a list of attributes and events associated with the Tree tag in JWL V2.0. The new attributes are in blue.

Table of possible attributes for the <odc:tree> tag
AttributeDescription
systemIconStyle A style string to configure the icons for the Tree.
rootVisibleFlagBoolean value to identify whether or not the Tree root is visible.
dynamicFlagBoolean value to identify if the Tree is to be constructed dynamically
workPlaceFlagBoolean value to enable Notes>Workplace inbox-style nodes for the Tree control.
enableSelectBoolean attribute to enable selection boxes or not
widthTree width in pixels or percentage
heightTree height in pixels or percentage
styleClassPrefix specifying CSS for multiple data grids on page
Table of possible events for the <odc:tree> tag
EventDescription
onnodehighlightThe handler to be called when the onhighlight event is fired on any node in the Tree.
onnodeexpandThe handler to be called when the onexpand event is fired on any node in the Tree.
onnodecollapseThe handler to be called when the oncollapse event is fired on any node in the Tree.
onnodedropThe handler to be called when the ondrop event is fired on any node in the Tree.
onnodeselectThe handler to be called when the onselect event is fired on any node in the Tree.
onnodeunselectThe handler to be called when the onunselect event is fired on any node in the Tree.

Tree Node Attributes & Events

The following are a list of attributes and events associated with the treeNodeAttr tag in JWL V2.0.

Table of possible attributes for the <odc:treeNodeAttr> tag
AttributeDescription
idThe ID for the Tree node
classNameThe fully-qualified class name of the kind of objects to be shown in this node
attributeNameAttribute name of the Java™ class that will be displayed as the label of the node.
nodeLabelA string will be displayed as the label of the node when there is no attribute on an object.
referenceNameComma-delimited reference name string of the Java class that will be displayed as child nodes of this node.
closeIconThe icon to be displayed when this tree node is collapsed.
openIconThe icon to be displayed when this tree node is expanded.
showSystemIconFlag to decide whether +/- should be shown with icon. False means if should not. Default value is True
Table of possible events for the <odc:treeNodeAttr> tag
EventDescription
onhighlightThe handler to be called when the onhighlight event is fired on this particular node.
onexpandThe handler to be called when the onexpand event is fired on this particular node.
oncollapseThe handler to be called when the oncollapse event is fired on this particular node.
onselectThe handler to be called when the onselect event is fired on this particular node.
onunselectThe handler to be called when the onunselect event is fired on this particular node.

Using Attributes & Events to customise the JWL Tree control

The odc:tree properties panel

This section will return to the basic Tree you created at the start of the article. First, take a look at the odc:tree section of the properties panel, as shown in Figure 2.

Figure 2. The odc:tree properties panel
The odc:tree properties panel

You can use this panel for customising basic attributes and labels using the following editable text fields:

  1. Id: Default value is tree1. You can customise this as appropriate.
  2. Value: This field was populated when the bean was bound to the Tree contol in step 6 of Creating a basic Tree control in IRAD. The value currently reads @{pc_DocTree.myBean} as a result of this binding.

    Note: @ in a value field signifies that the JWL component is bound to client data. # indicates page data is being used. Currently the Tree control only binds to client data, so # should not appear in this field.

  3. Tree style: The default css file can be replaced to display the Tree using your personal style preferences (see Changing CSS styles for the tree.
  4. Size (Width & Height): Both width and height can be set in either pixels or percentages. The two attributes do not have to be specified using the same unit of measurement. Width can be set in pixels and height in percentages or vice versa.
  5. Enable Node Selection: Selecting this box causes checkboxes to appear beside tree nodes. These check boxes can be used to trigger events. This is detailed further in Other Tree & Node Events .
  6. Show Root Node: This checkbox is selected by default, meaning the root node is on display initially. Clearing this checkbox, as shown in Figure 3, causes the root to no longer be visible on the page. This is particularly useful in a situation where you need more than one node available on the top level of the tree. It is also appropriate to use this feature if you require your top -evel node to have expand and collapse capabilities. The root node of a tree can not be expanded and collapsed.
    Figure 3. Clearing "Show Root Node" hides the root from the user
    Clearing Show Root Node hides the root from the userFig 3: Root
  7. Click to create/edit event handlers for tree control: This button brings you to the QuickEdit view, where you can create handlers for custom tree events. This QuickEdit panel is described in detail in the section Other Tree & Node Events .

The Tree Node List properties panel

Now select the Tree Node List panel shown in Figure 4. This panel allows the user to configure each individual Tree node. Currently only the root node is displaying on the Tree. To display more nodes, select them in the Select Nodes to Display panel.

Figure 4. The Tree Node List properties panel with the Users and Portfolios nodes selected to be displayed
The Tree Node List properties panel with the Users and Portfolios nodes selected to be displayed

Notice when you click on any of the nodes in the Tree Node List pane the text fields on the right change value to match the node selected. For each node, the following information is displayed and configurable:

  1. Id: Default value is already given using the generic term treeNodeAttr followed by a unique number. You can customise this as appropriate.
  2. Label value: The label for the tree node. Populated by the drag & drop binding to the sample bean when the Tree was first created.
  3. Class name: The Java class within the bean that relates to this tree node. This field is also populated by the binding of the bean to the Tree control. This class can be seen in the Project Explorer view on the right of the IRAD workbench. They are located in the package com.ibm.odcb.tutorial.businessobjects found in the Java Resources\Java Source directory of your Dynamic Web Project.

The other fields on this panel will be discussed in detail in the sections that follow.

Customising Node Icons

The default images for JWL tree nodes are standard tree graphics, as shown in Figure 5.

Figure 5. Standard tree graphics
Standard tree graphicsFig 5

You can change these images in the Tree Node List panel (Figure 4). Each level of nodes on the tree can be set to have different open and closed folder icons, independent of the icons selected for nodes on other levels of the tree's hierarchy. To achieve this, select the node that requires customised images from the Select Nodes to Display panel. Using the browse buttons provided beside the Open Icon and Close Icon fields, select the appropriate images. When selected, these icons are automatically imported to your Web Project and can be found in the newly created WebContent\ibmjsfres directory .

Note: icon names should not contain blank spaces.

Customising what data is displayed on the Tree

Customising the subset of data you wish to display on your tree can be acheived at two different stages of development:

  1. Prune the data server side: This method means you select the subset of data prior to pushing the data onto the client. This is advantageous in that it reduces the presence of redundant and unused data stored on the client, improving performance and reducing memory usage. This can be carried out by selecting the bean in the Client Data view. Right-click the porfolio bean and select Configure. Here you can expand the Tree and select the nodes that you wish to travel client-side. Note that if you clear a node here you will not see it as a selectable option in the Select Nodes to Display panel.
  2. Prune the data client-side: Selecting a subset of data after the data has been pushed onto the client. This approach is useful if there are multiple JWL components on the page, requiring the use of the entire data content of the bean. In this case all the data is required to be stored and accesible on the client-side for other JWL components on the page, but not required by the Tree in particular. To prune data client-side, use the Select Nodes to Display panel (left of Figure 4). Nodes can be selected and cleared to be displayed as appropriate.

Making the tree scrollable

Setting the width and height to a specific size using the fields made available in the odc:tree panel sets the tree to a specific size. Scollbars appear on the page if the tree exceeds the specified size after being expanded. In the example shown in Figure 6, the height of the tree is set to 100 pixels and the width to 200 pixels. Initially when the tree is displayed on the server no scroll bars appear, but when both nodes are expanded the height of the tree exceeds the stated 100 pixels and the tree becomes scrollable. The width of the tree has remained within its 200 pixel boundary so no horizontal scroll bar is visible.

The JWL component catalog

To learn more about the JWL components connect to the JWL component catalog. You will be asked to log in to the Boundary Firewall Service using your IBM internal intranet ID and password. Wait for the small window to disappear, and you will be automatically forwarded to the JWL component catalog.

Figure 6. Scroll Bar activated once height exceeds 100 pixels
Scroll Bar activated once height exceeds 100 pixels

Using the drag & drop event handler

The Drag & Drop event handler was introduced in JWL 2.0. It allows you to create an event handler that will be triggered when you drop an item (for example, a file from your desktop) onto a tree node. Although all other event handlers for the tree contain corresponding IRAD tooling the Drag & Drop listener currently has to be added manually into the code. The tag used to set the listener for this event is the onnodedrop event and it is added to the <odc:tree> tag.

Steps to manually create a Drag & Drop event handler:

  1. Create a drop handler method containing a JavaScript™ alert and place it within a script tag at the top of your JSP.
    	<LINK rel="stylesheet" type="text/css" href="theme/tree.css" title="Style">
    	<script type="text/javascript">
    		function func_1(thisObj,thisEvent)
    		{
    			alert("we are dropping on a tree node!");
    		}
    	</script>
    </HEAD>

    The parameters for the method are the eObject relating to this node (thisObj) and the corresponding event object (thisEvent). The native JavaScript event is available within this method using the variable thisEvent.nativeEvent. This is crucial when using the dataTransfer object while dragging and dropping data.
  2. Add a new onnodedrop tag pointing to the handler function within the <odc:tree> tag on your jsp.
    <odc:tree 
    styleClass="tree" 
    rootVisibleFlag="true"
    enableSelect="false" 
    id="tree1" 
    onnodedrop="return func_1(this,event);">
  3. Save the page, refresh and clean your project,and run the page on the server.
  4. Drag a file from the desktop onto any tree node.
  5. The alert within your function is displayed as the file is dropped onto the node, as shown in Figure 7.
    Figure 7. Alert displayed by drop event
    Alert displayed by drop event

Other Tree & Node Events

The other tree and node events can also be implemented in this manual fashion. Simply replace the onnodedrop tag with the appropriate tag for the event. However, if you are more comfortable developing your application using the IRAD tooling, this is best implemented using the QuickEdit view. The QuickEdit view is visible when in the Web perspective. It is the tab immediately beside the Properties pane at the bottom of the IRAD workbench. With this panel open, select the Tree control from the Design view above it. Please note that there are two seperate sets of events for the Tree. There are those belonging to the entire tree (preceded by the string onnode, for instance onnodeselect and onnodehighlight) and those specific to the individual Tree nodes (prefix of on for example, onhighlight and onselect). Please ensure when you are creating events for the entire Tree that you have selected the entire Tree in the Design view and the elements on the list to the left of the QuickEdit page contain the prefix onnode. To see the node-specific events appear there simply select the node you wish to trigger the event in the design view and a list of node events will appear on the left.

Event handlers can be created for both the Tree and node-specific events by typing or pasting the method body into the panel on the right of the QuickEdit screen.

For specific tree nodes there is also an option to use prewritten JWL handler methods to interact with other JWL client components on the page. Detailed descriptions on how to use these custom handlers can be found in the Developers Guide Section 3.16: Wiring controls, event handler.

Changing CSS styles for the tree

The tree styles are set in the tree.css file located in the WebContent\themes folder of your project. This file contains a number of configurable styles for the tree control. An example of this is the labelMouseoverStyle. This governs the style of a tree node's text label when you move a mouse over it. The default value for this style is:

/*Use for node text label style when mouse over the label*/
tree.labelMouseoverStyle
{
FONT-SIZE: 11px;
COLOR: #000000; FONT-FAMILY:
Tahoma, Verdana, Geneva, Arial, Helvetica, sans-serif;
font-style: italic;
}

This displays as shown in Figure 8.

Figure 8. When the mouse is over the label
When the mouse is over the label

It is possible to use your own customised styles to change the appearance of a tree node label during mouse over. To acheive this, create your own personalised style sheet. Copy the contents of the existing tree.css and paste it into a newly created myStyles.css. Create a link to the new style sheet at the top of your JSP.

<LINK rel="stylesheet" type="text/css" href="theme/myStyle.css"
	title="Style">

Change the styleClass attribute in your jsp file to:

		<odc:tree styleClass="myStyle"

Change the values in your newly created style sheet to have a myStyle_ prefix instead of a tree_ prefix. Now you are ready to change the labelMouseoverStyle in your newly created style sheet. Here's how to set it to highlight the text in a grey colour by setting the background attribute accordingly.

/*Use for node text label style when mouse over the label*/
breff.labelMouseoverStyle
{
FONT-SIZE: 11px;
COLOR: #000000;
BACKGROUND: #CCCCCC;
FONT-FAMILY:Tahoma, Verdana, Geneva, Arial, Helvetica, sans-serif;
font-style: bold;
}

Clean and rebuild your project and rerun it on the server. Now when a mouse over occurs, a node label will appear as shown in Figure 9.

Figure 9. Mouse over changes
Mouse over changes

Download

DescriptionNameSize
Sample model beansamplemodel.zip5 KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=100677
ArticleTitle=The JWL Tree component
publish-date=12202005