tree guide v2.4

7/27/2019 Tree Guide v2.4

1/60

EECCrruuiisseerr

TTrreeee

AApppplliiccaattiioonn DDeevveellooppeerrss GGuuiiddee

Second Edition

Simplica Corporation

1701 Shallcross Ave.

Suite B-2Wilmington, DE 19806

Published December, 2007 by Simplica Corporation. All rights reserved


2/60

SimplicaSimplified Computing

ECruiser Tree ii Application Developers Guide

EECCrruuiisseerr

TTrreeee

AApppplliiccaattiioonn DDeevveellooppeerrss GGuuiiddee

Second Edition

Published December, 2007.

Copyright 2007 by Simplica Corporation. All rights reserved.

ECruiser and Simplica are registered trademarks of Simplica Corporation.

This publication may not be reproduced, stored in a retrieval system, or transmitted in any form without the

written permission of Simplica Corporation.

Sun, Sun Microsystems, and Java, and JavaServer are trademarks or registered trademarks of Sun

Microsystems, Inc. in the United States and in other countries.

Microsoft Windows Explorer is a registered trademark of Microsoft Corporation.

All other trademarks mentioned herein are the property of their respective owners.

Authors: Roger R. Cote (Boomer Communications Consulting), Kito D. Mann (Virtua, Inc.)Technical Contributors: Marcus E. Rabil (Simplica Corporation), Gabriel Pascariu (Simplica

Corporation) Kito D. Mann (Virtua, Inc.)

Simplica Corporation

1701 Shallcross Ave.Suite B-2Wilmington, DE 19806


3/60


ECruiser Tree iii Application Developers Guide

Table of Contents

1 Introducing ECruiser Tree............................................................................................................ 1

Who Should Read this Guide......................................................................................................... 1

ECruiser Tree Features Overview............................................................................................... 1

2 A Simple Example .......................................................................................................................... 3

Chapter Summary .......................................................................................................................... 6

3 Introducing Tree Fundamentals....................................................................................................... 7

Understanding the Basic Structural Elements of Tree ................................................................... 7

Lines...................................................................................................................................... 7

Tree .......................................................................................................................................8

Tree Cells .............................................................................................................................. 8

Tree Cell Elements................................................................................................................ 9

Understanding the Key Java Components and Classes.................................................................. 10Chapter Summary .......................................................................................................................... 11

4 Defining the Tree Look and Feel .................................................................................................... 12

Introducing the Appearance Properties.......................................................................................... 12

Using the Default Tree Appearance............................................................................................... 14

Using Default Style Classes.................................................................................................. 14

Specifying Expander Icons ............................................................................................................ 15

Specifying Tree Cell Icons............................................................................................................. 17

Adding Selection Controls............................................................................................................. 20

Specifying Text Display and Format ............................................................................................. 22

Adding JSF Components ............................................................................................................... 24

Defining Line, Root and Expansion Properties.............................................................................. 25

Defining Tree and Tree Element Size............................................................................................ 26

Chapter Summary .......................................................................................................................... 27

5 Working with Data .......................................................................................................................... 28

Defining Tree Data ............................................................................................................... 28

Considering Your Model Options......................................................................................... 28

Using Tree Cell Templates ............................................................................................................ 30Using the Shortcuts ........................................................................................................................ 31

Defining a Static Tree in the JSP with Tags ......................................................................... 31

Defining a Tree with JSF SelectItem Objects....................................................................... 33

Understanding TreeModel and TreeNode...................................................................................... 35

Using the Tree Model and Tree Node Techniques ........................................................................ 36

Implementing the TreeModel Interface ................................................................................ 36


4/60


ECruiser Tree iv Application Developers Guide

Implementing the TreeNode Interface .................................................................................. 39

Wrapping Business Objects in DefaultMutableTreeNode.................................................... 41

Chapter Summary .......................................................................................................................... 43

6 Interacting with the User ................................................................................................................. 44

Enabling AJAX Support ................................................................................................................ 44

Setting Preloading and Reloading Features ................................................................................... 45

Defining Scrolling Behavior .......................................................................................................... 46

Supporting Drag and Drop............................................................................................................. 47

Handling Events............................................................................................................................. 51

Handling Selection Events.................................................................................................... 51

Handling Standard JSF Action and ActionEvents ................................................................ 53

Handling TreeModel Events................................................................................................. 55

Chapter Summary .......................................................................................................................... 56


5/60


ECruiser Tree 1 Application Developers Guide

1 Introducing ECruiser TreeWelcome to theECruiser Tree Application Developers Guide. This guide introduces you to Tree

features; defines key components and classes; describes how to customize the look-and-feel; explains data-

handling options; and discusses user interaction features. Each topic is addressed within concise, focusedchapters designed to get you up and running as quickly as possible.

We want to help you become familiar with the information you need to build a better application without

bogging you down in too much detail, so feel free to jump to a chapter or section of particular interest at

any time. Just remember that the early chapters include important information that can improve your

overall understanding of Tree.

NOTE: NOTE: If you need installation and setup information, refer to the

ECruiser Getting Started Guide, which is a separate document.

Who Shoul d Read t hi s Guid e

This guide is written for developers and architects who are working with Tree, or who want to learn more

about Trees advanced features. We assume that you have working knowledge of Java programming; a

good understanding of Java Server Pages (JSP) and Java Server Faces (JSF) application development; and a

good understanding of HTML and Cascading Style Sheet (CSS) concepts.

Because ECruiser components hide the complexity of client-side browser development, specific

knowledge of JavaScript and Asynchronous JavaScript and XML (AJAX) development is not required, but

it could enhance your understanding of how the component works.

ECr uiser Tr ee Feat ur es Over vi ew

ECruiser Tree is an AJAX-enabled JSF component specifically designed to optimally represent datastructures that are hierarchical by nature. ECruiser Tree is extremely flexiblefeaturing multiple options

for linking to hierarchical data, setting the component look and feel, and controlling how the user interacts

with it. Key features include:

In terac t ive

;;; Drag and Drop with AJAX.;;; Load tree nodes with AJAX.;;; Configure for single or multiple selection.;;; Fire selection events.;;; Show scrolling region automatically as necessary.;;; Use keyboard keys to navigate, expand, and collapse Tree.


6/60



Cust omizab le

;;; Set the depth of nodes that are preloaded in the client.;;; Configure all color, fonts, and styles with simple style sheet classes.;;; Put any JSF component in nodes.;;; Choose from default expand/collapse icons, and tree cell icons, or set your own.

Brow ser Compat ibi l i t y Feat ures

;;; Works on Internet Explorer, Mozilla (including Firefox), Netscape, Opera, and Safari.;;; Provides support for Facelets.;;; Works with Suns Reference Implementation 1.1_02 and 1.2.;;; Works with MyFaces 1.1, 1.3, and 1.1.4.

Tr ee Dat a

;;; Define static tree data in tags.;;; Use simple JSF SelectItem objects to programmatically set the tree structure.;;; Implement POJO-driven tree models.;;; Use powerful tree cell templates to easily construct complex trees.

So now that you have had a brief introduction to Tree, we can take a look at a simple example.


7/60


2 A Simple ExampleWe provide a Simple Tree Example application, as shown in the figure below, to give you a quick look at

the basic elements applied when creating an application using ECruiser Tree. This tree is an example of

defining a static tree in the JSP with tagsonly tree and tree cell tags define the structure. We talk moreabout this (and other) techniques used to define a tree structure later in the guide.

We modeled the example after a common email application, so the features might be familiar. Notice the

use of text formatting for hovering, selection, and function. The blue background indicates a selected tree

cell and the blue text indicates a user hovering over (cursor above) a tree cell. We use bold to indicate that

emails need to be read, and italics to indicate that a folder search needs to be executed. (We use them here

only to illustrate the formatting possibilities.)

Take a look at the icons in the example. You do not have to specify icon images for tree cells because

ECruiser Tree provides default images. The "Family" tree cell shown in the graphic above uses default

images, except for the file open icon, which was added to illustrate the open/closed file feature. (Refer to

the JSP below to review each setting). Tree gives you the option to specify icons as desired, including your

own custom icons.

Tree uses styles to control its look and feel. Tree supports three default styles: t r eeCel l ,t r eeCel l Hi ghl i ght , andt r eeCel l Sel ected. We created two custom styles for this demo:t r eeCel l Bol d andt r eeCel l I t al i c.

NOTE: Tree will automatically use default style class names unless you

explicitly specify different names.

You can specify styles for each tree cell. For example, we specify a style for the Deleted Items tree cell

by using the st yl eCl ass property as shown below:

Figure 1. Simple Tree Example using Static implementation.



8/60



Simpl e T r ee Exampl e JSP

As noted above, this is a static tree, so all of the tree cells are defined in the JSP and a backing bean is not

required. The JSP shown below contains all the information needed to configure the component.

ECr ui ser&r eg; Tree Si mpl e Exampl e

. t reeCel l t d {f ont - si ze: 10pt ; paddi ng- r i ght : 2px; t ext - al i gn: cent er; }

. t r eeCel l Hi ghl i ght {t ext - decor at i on: under l i ne; col or : #316ac5; cur sor : def aul t ; }

. t r eeCel l Sel ect ed {backgr ound- col or : #316ac5; col or : whi t e; cur sor : poi nt er ; }

. t r eeCel l Bol d t d {f ont - si ze: 10pt ; f ont - wei ght : bol d; paddi ng- r i ght : 2px;t ext - al i gn: cent er; }

. t reeCel l I t al i c td {f ont- s i ze: 10pt ; f ont - styl e: i t al i c ; paddi ng- r i ght : 2px;t ext - al i gn: cent er; }

Each tag defines a visible node in the tree. Properties can be set at the tree level toeffectively define default look and feel for the entire tree, or at the tree cell level to create special

formatting, visual display, or cell functions. We discuss this topic in more detail in the following chapters.

In the JSP, we use the i con properties to assign images to several tree cells. We also use the openI conproperty to assign an open image to a particular tree cell. In other cases, tree cells have no icon

specifically assigned, so those tree cells use the default images.


9/60


Tree includes more granular icons that you probably would not use in a static tree (typically used only use

templates). We discuss icons and the various properties that can be used to assign images in more detail in

chapter 4.

Because the example is simple, we do not use a separate style sheet file. A more complex application could

use an external style sheet, but here the CSS classes are defined within the tag. We did not needto specify the style class names because the style class definitions use the default values that ECruiser

Tree uses when no others are specified.

Keyboar d Accessibi l i t y

Tree also supports using keyboard arrow keys as an option for navigation and control. When a Tree is

selected (clicked on) and the focus is on the Tree, users have the option of navigating through the Tree with

the mouse or keyboard keys.

They can use the Up andDown Arrow keys to move through the Tree. They can expand folders using the

Shift + Right Arrow keys, or collapse folders using the Shift + Left Arrow keys. Of course, they can stilluse the mouse for navigation and control if they prefer.

This feature requires no extra programming or property setting; the mechanism is built-in and ready to go.

Figure 2. Keyboard accessibility option for navigation and control.



10/60



Chapt er Summar y

The chapter provided a simple example to show you the elements needed to begin using Tree. The

example addressed several key elements including:

;;; specifying icons for tree cells;;; specifying styles for selected tree cells;;; placing JSF components in a tree cell;;; using default styles

You should note that the Simple Tree Example is used only to introduce you to the basic features and

elements of ECruiser Tree. The example is a static tree, which is perfect for simpler scenarios such as

menus.

More advanced use cases can be achieved using other tree features and functions. Later chapters in this

guide show you just how flexible and adaptable ECruiser Tree can be.

The chapter also described the keyboard accessibility navigation options built into Tree. Users can move

through the Tree using the Up andDown Arrow keys, and they can expand and collapse folders by usingShift + Right orLeft Arrow keys.

The next chapter familiarizes you with the main components and classes used by Tree. It provides the

foundation needed to build your understanding of how the component can be customized to meet yourneeds.


11/60


3 Introducing Tree FundamentalsSeveral key elements form the foundation of the Tree component. Two sections in this chapter introduce

you to the essential structural elements, and the principal Java components and classes that make Tree a

versatile component.

Understa nding t he Basic St r uct ural Element s of Tr ee

The figure below breaks Tree into three basic elements: Tree, Tree Cells, and Lines. We refer to these

elements throughout this guide when discussing Tree properties, features, and implementations. The

following sections provide closer examination of each element.

Lines

The Lines that connect tree elements are optional. ECruiser Tree renders lines by default. If you prefer,

you can hide the lines by setting the l i nes property to false at the tree level.

Figure 3. Expanded view of Tree showing basic structural elements.



12/60



Tree

The overall structure is, of course, the Tree. It includes the other two basic elementstree cells, and lines.

A Tree contains one or more tree cells, which are JSF components that render the individual tree nodes. In

most cases, tree cells are re-used to render the data provided by the tree model, which defines the trees

physical structure. We discuss tree models in more detail in chapter 5.

Tree Cells

Tree Cells begin at the root of the tree. Typically, the root (as the primary parent) includes one or more

child tree cells. Each of these tree cells can be a parent itself, or a leaf. A leafis defined as any tree cell

that cannot have children.

Tree cells are the visual elements of Tree. You use tags to define the appearance of thevarious tree cells in a tree. The properties used to define tree cells perform several functions, including:

;;; Assigning various icons to specific tree cells.;;; Assigning specific styles for tree cell text.;;; Connecting the tree cell to an underlying data node.

NOTE: Where cells are the visual element of Tree, nodes are the data. Nodesare relative to tree cells and represent the actual data for specific treecell elements.

* A node's tree is the set of all nodes that can be reached by starting

at the node and following all the possible links to parents and children.

* A node with no parent is the root of its tree and a node that cannot

have children is a leaf.

* A tree node can have no more than one parent, and zero or more

children.

We discuss nodes in more detail in chapters 5.


13/60


Tree Cell Elements

The figure below shows the structure of a single tree cell. From left to right the elements that can be used

in a tree cell include: expander icons, tree cell icons, selection controls, text, and JSF components.

Most elements are optional and all elements are configurableyou can choose to hide or display most of

them, and you can choose from various display options for all of them. The following definitions introduce

these elements.

Figure 4. Individual Tree Cell elements.

;;; Expander IconsThese icons appear to the left of tree cell to indicate that a tree cell contains oneor more child tree cells. The element comprises two types of icons: Expanders and Collapsers.

As their names imply, expanders spread out the tree to display available tree cells when clicked

on and collapsers fold up (compact) tree cells.

;;; Tree Cell IconsTree uses tree cell icons to illustrate the hierarchy and state of elements withinthe tree.

;;; Selection ControlsWhen you include selection controls in your tree, you can assign a checkbox or a radio button depending on whether you allow multiple or single selection. You can also

use CSS styles to indicate selection.

;;; TextBy default, tree cells render output text unless you specify otherwise. Styles can also beapplied to format text as needed.

;;; JSF Component You can embed child JSF components in addition to, or in place of text if yourtree cells requires additional components.

Chapter 4 provides more information about each element.



14/60


Under st andi ng t he Key Java Component s and Classes

Now that we have discussed Tree on a conceptual level, we can look a little more closely at the

components object model. Here are the key players:

;;; Treeprimary ECruiser Tree class.;;; TreeCellrepresents either static nodes (as shown in the Simple Tree Example in chapter 2), or atemplate for each node (when nodes are retrieved dynamically).;;; TreeModelprovides dynamic access to data for each node.;;; TreeNoderepresents the data for a single node in the tree.

All of these classes are represented in the simplified UML diagram below.

As the diagram shows, a Tree can have zero or more child TreeCell components. In turn, each TreeCell

can have zero or more child TreeCell components.

The other classes in the diagram represent Trees model. The primary interface is TreeModel, which can

have zero or one TreeNode for its root. (Technically, a TreeModel can reference any object type as its root,

and some of these features are implemented by TreeModel implementations; see chapter 5 for details).

Each TreeCell defines the look and feel for one or more TreeNode instances (or any other object types).

Trees architecture makes it easy to get started, but provides enough flexibility for complex use-cases.

Defining a static tree in your view (JSP or Facelet) requires only declaring the Tree and zero or more

TreeCell components. As shown in chapter 2, the component does not even require a backing bean.

However, if necessary, you can manipulate Tree directly by writing event listeners, configuring a

TreeModel implementation, or even writing your own TreeModel.

NOTE: Refer to the JavaDocs for more detail about these classes.

Figure 5. Simplified UML diagram with key Tree classes and interfaces interaction.



15/60



Chapt er Summar y

This chapter introduced the basic elements that make Tree a powerful and flexible component. Tree

comprises three basic structural elements: Tree, Tree Cells, and Lines.

Tree cells can contain severalsub-elements, including: expander icons, tree cell icons, selection controls,

text, and JSF components.

Several tree and tree cell elements include default settings to allow you to easily integrate a standard tree

configuration into your application if you choose.

This chapter also introduced you to the key Java components and classes that make up Trees object model

by providing a brief description of the key players while graphically illustrating their relationship. These

players include: Tree, TreeCell, TreeModel, TreeNode, TreeModelEvent, and TreeModelListener.

So now that you have had an overview of the component, you can turn your attention to what you can do to

make Tree look like a part of your application.


16/60



4 Defining the Tree Look and FeelECruiser Tree offers you ample opportunity to enhance the user experience by customizing the

appearance of your tree. Presentation options can improve the appeal and usability of your implementation,

which can benefit your overall application and impress your users.The properties discussed in this chapter help you define how your tree will appear to the user. These

properties control the styles, colors, dimensions, and other physical features of Tree, allowing you to create

practically any look and feel you need.

Int r oducing t he Appear ance Pr opert ies

The following table provides an overview of the look-and-feel properties associated with Tree and indicates

which can be set on the tree itself or individually on the tree cells. The table separates the properties into

relative categories.

Table 1. An overview of the Tree appearance properties.

Properties Tree Tree Cell

Expander Icons

expanderType X X

expanderIcon X X

collapserIcon X X

Tree Cell Icons

closedIcon X X

icon X X

leafIcon X X

openedIcon X X

rootIcon X X

Sizing

width X X

height X X

cellHeight X

scrolling X X


17/60



Properties Tree Tree Cell

Styles

closedStyle X X

hoverStyle X X

leafStyle X X

cellStyle X

openedStyle X X

rootStyle X X

selectedStyle X X

styleClass X X

Selection Control

selectionType X

selectionMode X

Line, Root and Expansion

expanded X

lines X

rootExpanded X

rootRendered X

Tree allows you to set many properties at the tree or tree cell levels. Properties are typically specified at the

tree level to establish default appearances for the tree. You can override the default assignments as needed

by specifying properties for individual tree cells. Specifying properties at the tree cell level provides you

with the flexibility to customize specific elements within the tree.

Selection type and style are handled at the tree level. The cel l St yl e, cel l Hei ght , l i nes ,r oot Expanded, andr oot Rendered properties also can be set only at the tree level, as shown in thetable above.

TIP: The st yl eCl ass propertyalong with properties that end in Style refer to aCSS style class, and are usually defined in a pages head section, or in aseparate style sheet file.

The sections that follow provide more details for the properties and how they are used to define the

appearance of tree elements.


18/60



Using t he Defaul t Tr ee Appear ance

You can use Tree out of the box if you choose. It includes basic elements with default assignments as

shown in the figure below.

Figure 6. Tree showing default elements.

You should first notice that the tree displays a set of default icons for each icon element.

;;; Expander Icondefault is plus-minus image pair.;;; Tree Cell Icondefault is closed folder image. (No opened/closed pair used.);;; Leaf Icondefault is page image.

Lines also display by default, and text is uniformly rendered as defined by the default style.

Using Default Style Classes

Tree uses default style class names unless you specify another value via a tag attribute, or

programmatically. This means that all you have to do is create the style classes in your JSP or style sheet

with the default namethere is no need to also set the corresponding property on the tree.

NOTE: Every tree uses the same default class names. If you put multiple trees

on the same page, and you would like them to look different from one

another, only one can use the default style class names.

Defaul t Tr ee St yles

ECruiser Tree uses the following three default styles:

;;; treeCell tddefault style for cells.;;; treeCellHighlightdefault style for highlighted cell.;;; treeCellSelecteddefault style for selected cells.


19/60


Specif yi ng Expander Icons

Expander Icons appear first (from left to right) in a tree cell to indicate that the cell contains one or more

child tree cells. The element comprises two types of icons: Expanders and Collapsers. As their names

imply, expanders spread out the tree to display available tree cells when clicked on; collapsers fold up

(compact) tree cells.

The table below describes the properties used to assign the expander and collapser icon options.

Table 2. Properties used to specify expander icons.

Property Description Default Value

e x p a n d e r T y p e Specifies the image pair to use for all tree cells

when the related nodes are expanded. Possible

values include:

;;; black-twisty;;; white-twisty;;; plus-minus (default)You can also use your own images if you choose.

plus-minus

e x p a n d e r I c o n Specifies a custom image to assign to anexpander icon. You must define the image path.

c o l la p s e r I c o n Specifies a custom image to assign to a collapsericon. You must define the image path.

The figure below shows examples of the plus-minus, and black-twisty expander icon sets.

Figure 7. Expander icons using standard Tree sets.

The expander icon sets shown above were specified for these examples using the expanderTypeproperty. This assignment specifies that the icon sets be used for the entire tree. The values plus-minus



20/60


and black-twisty were used to create each example. You can also set this property at the tree cell level if

desired.

The JSF snippet for the plus-minus example looks like this:

. . .

The next figure provides an example of a custom icon set specified using the expander I con andcol l apser I con properties.

Figure 8. Tree using custom expander/collapser icons.

The custom_plus and custom_minus icons are used in this example to show how you can use your own

expander and collapser icons. Select the tree cell for which you want to use custom icons. Then specify

the image path for each property.

The JSF snippet for the custom icon set looks like this:

. . .

. . .

You could also set these properties at the tree level if you want to use custom icons for the entire tree.



21/60



Specif yi ng Tr ee Cell Icons

Tree uses other icons to illustrate the hierarchy and/or state of elements within the tree. The table below

defines the properties used to assign icons to tree cells.

NOTE: Expander and collapser icons are also a type of tree cell icon, but they

were addressed in the previous section to stay in context withexpander types.

Table 3. Properties used to specify tree cell icons.


c lo s e d I c o n Specifies the image path to usefor tree cells in a closed state.

c l o s e d S t y l e Specifies how the node willappear when the tree cell is in a

closed state. *

i c o n Specifies the default image pathto use for any unspecified tree

cell icon assignment. Set this

property to none to turn officons. This property does notaffect leaf nodes.

l e a f I c o n Specifies the image path to usefor tree cells identified as leaf

nodes. Typically not used instatic models.

l e a f S t y l e * Specifies how the node will

appear for a tree cell identified asa leaf node.

o p e n e d I c o n Specifies the image path to use

for tree cells in an openedstate.

o p e n e d S t y l e * Specifies how the node willappear for a tree cell in an

opened state.

r o o t I c o n Specifies the image path to usefor the root icon.

r o o t S t y l e * Specifies the appearance of theroot tree cell.

* These styles affect the appearance of the node only, not the text within the tree cell.


22/60


The following figure provides examples of how tree cell icons were assigned to the Simple Tree Example.

Figure 9. Tree showing standard tree cell icons.

(1) The Personal Folders tree cell sets the default image for the tree cell and its children by using the

i con property. All subordinate tree cells will also use this image (except leaf nodes) unless another isspecified within individual tree cells. The JSP declarations are shown below:

(2) The second example specifies an image for a leaf node. In this example, the l eaf I con propertyspecifies the draft image.

(3) The next example shows the openedI con property used to specify the open_folder image for theFamily folder when it is in an opened state. Note that the leaf nodes were not assigned specific images,

so they use the default.

(4) The last example illustrates how the default images are overridden by re-using the i con property. In

this case, the tree cell replaces the icon with a search image, which is also used by the associated leafnodes in this folder.



23/60


TIP: You would likely use the l eaf I con property in a tree cell template. Staticstructures typically include known elements, and therefore have easilyidentifiable leaves to which you can directly assign icons as needed using the

i con property.

Tree cell styles are used to improve the look and usability of Tree. The figure below provides an exampleof using a tree cell style.

Figure 10. Tree showing an example of openedStyle formatting.

In this example, we use the openedSt yl e property to set the background color for the Family tree cellto light blue. When the user opens this node, the openedSt yl e formatting appears.

The JSP elements for this formatting is shown below:


24/60



Addi ng Select ion Cont r ols

You can add selection controls (check boxes or radio buttons) to your tree if you want to allow your users

to select nodes within the tree via a separate input control (versus just clicking on the text). Users then

click on the tree cell text, or the control to select the cell; they click on it again to unselect it. The table

below describes the properties used to add selection controls and functionality.

Table 4. Properties used to specify selection controls and functionality.


s e l e c t e d S t y l e Specifies the text and node formattingstyle for a tree cell selected by the user.

Displays when sel ect i onMode is set to

text. Set this property at the treelevel to assign a new default. Set this

property at the tree cell level if you want

special formatting for specific tree cells.

.treeCellSelected

s e l e c t i o n M o d e Specifies the selection mode to use.

Values can be:;;; textselects the tree cell using

formatting provided by assigned style

classes.

;;; inputdisplays a standard HTML selectioncomponent. If type value is single a

radio box is rendered.If type value is multiple a check box is

rendered.

;;; bothrenders the "input" and "text"selections at the same time.

This property is set at tree level only.

(If you are working with code in abacking bean, these values are

represented by the constantsTr ee. TEXT_SELECTI ON_MODE,

Tr ee. I NPUT_SELECTI ON_MODE, and

Tr ee. BOTH_SELECTI ON_MODE,

respectively.)

text

s e l e c t i o n T y p e Specifies the selection type to use.

Value can be none single ormultiple. This property is set at tree

level only.

(If you are writing Java code in abacking bean, these values are

represented by the constants

Tr ee. SI NGLE_SELECTI ON_TYPE andTr ee. MULTI PLE_SELECTI ON_TYPE. )

single


25/60


The following example shows the resulting tree when the sel ect i onType property is set to multipleand the sel ect i onMode property is set to input. We assign these properties at the tree level.

Figure 11. Tree illustrating selection control box example.

Check boxes appear between the icons and text as shown in the example above. Users can select as many

checkboxes (cells) as needed for the related application.

The next example shows you how to use the sel ect edSt yl e property along with the radio buttonselection control option.

In this example, we set the sel ect i onType property to single and the sel ect i onMode property toboth to show how the component renders the tree cell when selected. These properties are set at the tree

level as shown below in the JSP snippet below.

Figure 12. Tree showing selection control and style.

In the tag at the top of the JSP, we defined a custom style, mySel ect edSt yl e, with theformatting attributes.

.mySelectedStyle { background-color: violet; color: white;

font-weight: bold; font-style: italic; }



26/60


Speci f yi ng Tex t Display and Format

By default, tree cells render output text unless you specify otherwise. Tree cells render the text assigned to

the cells val ue property by default. If you specify a t ext property, the tree cell renders that assignmentinstead. Take a look at the following example.

The rendered tree would display spreadsheet if no t ext property were assigned. If a t ext property isassigned, as shown above, the specified value (calculate in this example) is displayed.

You can also assign formatting properties to the entire tree, or to specified tree cells. The table below

defines the properties that you can use to define these styles.

Table 5. Properties used to assign function and format to text.


h o v e r S t y l e Specifies the text formatting stylefor all tree cells when the user

moves the cursor over a cell.

.treeCellHighlight

c e l l S t y l e Specifies the style to use for all

cells in the tree. The assigned style

will be used unless another style isset at the tree cell level. Set this

property at the tree level only.

.treeCell td

s t y l eC l a s s Specifies the style class to use for

the entire tree or for a specific treecell.

.treeCell td

The figure below illustrates how text style properties can be set at the tree cell level.

These examples illustrate the visual impact your modifications can have on the tree, which can improve

both the aesthetic appeal and usability of your application.

Figure 13. Tree illustrating text using styles.



27/60


(1) First, we assigned a custom style class to the Delete Items folder to format the text in bold.

(2) For the Grandma & Grandpa tree cell, we not only assigned a custom style class to format the text in

bold, but we also used the t ext property to assign a text label different from the cell identifier.

(3) For the Large Mail tree cell, we specified a custom style class to format the text in italics.

In the tag at the top of the JSP, we defined custom styles, t r eeCel l Bol d andt r eeCel l I t al i c, with the formatting attributes.

.treeCellBold td { font-size:10pt; font-weight: bold; padding-right:2;

text-align: center; }

.treeCellItalic td { font-size:10pt; font-style: italic; padding-right:2;

text-align: center; }

The figure below provides an example of Tree using a modifiedhover St yl e property.

Here, we set the hover St yl e property to create a light blue background and convert the text to bold italicwhen the user passes the cursor over a tree cell:

Figure 14. Tree showing modified hoverStyle property.

In this example, the JSP declarations are set at the tree level as shown below, but you can create custom

highlighting effects at the tree cell level if you choose. In this JSP we defined a custom style,

myHoverSt yl e, with the formatting attributes:

.myHoverStyle { background-color: light blue; color: white;

font-weight: bold; font-style: italic; }



28/60


Addi ng JSF Component s

ECruiser Tree allows you to embed JSF components in line with, or in place of, text when your

application requires such a component.

The figure below provides three examples of embedded JSF components.

Figure 15. Tree illustrating the use of JSF components.

(1) The first example adds an out putText component that could be used to indicate the number of files(emails) in the Deleted Items folder. (For this example, we provide a static value of 400, but in a

practical application, this would likely come from a backing bean.) The component is added to the

Deleted Items text, which is assigned to the cell by default.

The JSP declarations look like this:

(2 and 3) The second example adds an image to the Grannie leaf node, while the third adds a JSF input

control component to the Family folder. The modified tree cells render the Grannie leaf with the

image shown, and an input text box for the JSF component rather than the text assigned to the cell.

The JSP declarations are shown below:



29/60


Defi ning Line, Root and Expansion Propert ies

Tree also has several properties that determine whether the lines and/or the root are displayed in the tree,

and whether the root will be expanded upon display. You can also define whether specific tree cells should

expand upon display. The table below provides definitions for these properties.

Table 6. Properties used to specify line and root display, and expansion.


e x p a n d e d Specifies whether the associated

tree cell will be expanded whenthe tree is first displayed. Thevalue can be true or false.

true

l i n e s Specifies whether lines will bedisplayed in the tree structure.

The value can be true (the

default) or false. This propertyis set only at tree level.

true

r o o t E x p a n d e d Specifies whether the root should

be expanded when the tree isfirst displayed. The value can be

true or false. This property isset only at tree level.

true

r o o t R e n d e r e d Specifies whether the root treecell will be displayed. To hide

the root, set the property tofalse at the tree level only.

true

The figure below illustrates the appearance of Tree when the lines and root display are turned off.

Figure 16. Tree with hidden lines and root.

To hide the root tree cell, and the lines for the entire tree, we included the following properties in the JSP:

These properties can be set only at the tree level.



30/60


The figure below illustrates Tree when it opens with the root expanded.

Figure 17. Tree showing expanded root upon display.

To expand the root when it first displays, we included the following element in the JSP.

Only the root expands; any children that include other children do not expand. This property is set only at

the tree level.

Def ini ng Tr ee and T r ee Element Size

ECruiser Tree provides several properties that allow you to define the size of the tree and/or tree

elements.

Table 7. Properties used to define sizing features.


h e i g h t Defines the height of the associatedelement. This is a pass-throughproperty.

c e l l H e i g h t Specifies the height for all cells inthe tree. Set this property at the

tree level only.

s c r o l l i n g Specifies whether scroll bars should

be used with the tree display.Values can be:

;;; autoscrollbars appear automaticallydepending on the content size.

;;; nonescrollbars never appear and allcontent will be visible.

Set this property at the tree level

only.

auto

w i d t h Defines the width of the associatedelement. This is a pass-through

property.

The Lines feature works with the default cel l Hei ght property setting only. If you want to use a largersize forcel l Hei ght , you should set the l i nes property to false for the best visual appearance.



31/60



Chapt er Summar y

This chapter discussed how to change Trees appearance to create a compelling user experience. Tree can

be configured to integrate into your applications appearance, or customized to suit your personal

preferences.

Tree can also be usedas is with default styles to provide a simple component addition that meets your basic

needs.

This chapter divided the appearance topics into categories based on tree cell elements (Expander Icons,

Tree Cell Icons, Selection Controls, Text, and JSF Components), then discussed the properties related to

each element. The chapter also addressed Line, Root, and Expansion properties, and Tree and Tree

Element sizing properties. Descriptions and examples for each property were provided. We also discussed

the JSP elements as they related to specific examples, and provided code snippets.

While the chapter discussed many essential features and functions of the appearance properties, a crucial

point to remember is that many properties can be set at either the tree level, or the tree cell level. Properties

set at the tree level typically define the default values for the entire tree. Exceptions or customizations are

set at the tree cell level.

In the next chapter, we take a look at your options for defining tree data.


32/60



5 Working with DataTo this point, you have been introduced to the features and properties needed to make Tree lookthe way

you want. Now we need to take a closer look at features and properties you can use to make Tree workthe

way you want.The data for a tree is typically provided by implementations of TreeModel, although in some cases

the tree will automatically create a model based on some other data construct you provide.

Defining Tree Data

ECruiser provides you with five techniques for defining tree data.

;;; Defining a Static Tree in the JSP with Tags;;; Defining a Tree with JSF SelectItem Objects;;; Implementing the TreeModel Interface;;; Implementing the TreeNode Interface;;; Wrapping Business Objects in DefaultMutableTreeNode

The first two techniques are essentially shortcuts, which allow you to easily initialize your trees data

without investing a lot of time. The last three techniques provide you with more power and flexibility, but

require a bit more effort.

It is conceivable that you could use several of these techniques in the same application. Each time you use

Tree, you pick a method based on the particular data needs for that part of your application. So, a shortcut

makes sense whenever you use a tree to represent static data, or a simple data structure.

Considering Your Model Options

The technique you choose to define your tree model will also affect the amount of work you have to do.Consider the following general guidelines to help you select the best technique for your situation.

Defi ning a St at ic Tr ee in t he JSP wi t h Tags

This technique is best suited for static trees (trees with a structure that does not change) where the entire

tree configuration is encapsulated in the JSP tags. For example, this option is a good choice when Tree is

used as a navigation control or as a static menu.

Because you define every tree cell within a corresponding tag, this technique also provides fine-grained

control over icons and other look-and-feel properties of the individual tree cells.

Defi ning a Tr ee wit h JSF Select Item Obj ects

This technique is the simplest way to define a tree programmatically. It is well suited for static or dynamictrees where the look and feel is based on default values for icons, styles, and so on. Use Sel ect I t ems (andSel ect I t emGr oups) to build a tree structure when you already have them for another purpose, orwhen you need to quickly map another data structure into a tree structure.

Implement ing t he TreeModel Int er f ace

By implementing the TreeModel interface (or its mutable sub-interface, MutableTreeModel), you directly

create the class that will drive your tree. All other techniques either directly or indirectly result in the


33/60



creation of a TreeModel instance. This technique allows you to drive your tree with simple, plain old Java

objects (POJOs) and is a good choice if you want to bind your objects properties to TreeCell templates.

Mutability (whether the tree nodes can be inserted, removed, or moved) is an important consideration when

implementing a TreeModel because the base TreeModel has only four methods to implement and

MutableTreeModel adds another nine.

Implement ing t he Tr eeNode Int er f aceImplementing the TreeNode interface (or its mutable sub-interface, MutableTreeNode) is similar to

implementing a TreeModel. The key difference is that the TreeNode interface gives your more control

over the tree structure, and the look and feel on a per-node basis. In this case, a special TreeModel

implementation (NodeTreeModel) delegates its methods to the nodes.

Use this technique when you have a heterogeneous tree. We can look at Microsoft Windows Explorer as

an example. In this case, each of the main nodes (My Computer, My Network Places, Recycle Bin, and so

on) could be implemented with its own TreeNode (MyComputerNode, MyNetworkPlacesNode, and

MyRecycleBinNode). You could do the same thing by just implementing TreeModel, but this would

require a lot of conditional code in each model method.

Wrappi ng Business Obj ects in Defa ult Mut abl eTr eeNodeDefaultMutableTreeNode is a specialized subclass of TreeNode that allows you to wrap any POJO. This

technique is useful because the wrapped POJO properties can be linked to look-and-feel properties via the

TreeCell template mechanism. Using this technique is similar to building an array of SelectItems, but

instead you build the tree structure with instances of DefaultMutableTreeNode. Although similar to the

light-weight SelectItem technique, DefaultMutableTreeNode allows significantly more flexibility for your

trees appearance.


34/60



Using Tr ee Cel l Templ at es

Throughout this guide, we have been using tree cells to define static Tree nodes. However, when working

with a large, model-driven tree, you will encounter situations for which you want to define the appearance

for specific node sets. For these cases, you can define a template tree cell that is repeatedly rendered for

each node provided by the tree model. You can define any number of template tree cells and use a

condition to determine which one is applied to each node..For example, if you wanted most nodes to look the same, but wanted to set one specific node type in bold,

and another in italics, you could define your tree like this:

NOTE: The l eaf I con property is used in these examples (and in others in this

chapter) as you would typically use itwithin templates.

In this example, the data is defined by a TreeModel, which could be very large. We have defined three tree

cell templates. The first tree cell is the default tree cell template because no matchExpr essi onproperty was specified. A match expression is a special, JSF value-binding expression that Tree uses to

determine when to select a particular template. When the expression returns true, the tree cell will be

used to display the node as defined by the assigned attributes. If no match expressions return true, the

default tree cell will be displayed.

The second and third tree cells are special cases with different styles for bold and italic formattingthe

matchExpr essi on property determines when the special cases are used (NODE is an implicit variablethat represents the current node).

Tree cell templates are ideal for more complicated data sets; they make it easy to dynamically control the

appearance of different nodes. You will see more examples of tree cell templates throughout this chapter.


35/60



Using t he Shor t cut s

When you only need to create a tree to represent static data or a simple data structure you can choosebetween two techniques that simplify your task.

Using the Static Tree approach, you need only define tree and tree cell tags to create a tree (for example, a

static menu). The tree component mechanism works behind the scenes with theTr eeCel l Model class

to create the model. Of course, you could work directly with the model if you prefer, but the shortcutmakes it easy to create simple, static trees.

Using JSF SelectItem objects to create a tree has similar advantages. You need only specify the SelectItem

objects, and the tree component mechanism works behind the scenes with the Sel ect I t emTreeModel class to create the modelthe task is made simple. Remember, you do have the option to work directly

with the model if you prefer. (For more information on SelectItemTreeModel refer to the Understanding

TreeModel and TreeNode section found below.)

Now we can take a look at each technique to see how they actually work.

Defining a Static Tree in the JSP with TagsWith the Static Tree approach, tree cells, nested within each other as necessary, can be used to define

an entire tree structure. You should recognize this implementation because we have used it to this pointto illustrate earlier topics.

A quick review of the JSP is shown below.


36/60


The resulting tree is, of course, our Simple Tree Example.

Remember that this technique is commonly used to display static data structures and that the tree

component mechanism works behind the scenes with theTr eeCel l Model class to create the model.

Figure 18. Static Tree Example.



37/60


Defining a Tree with JSF SelectItem Objects

SelectItem objects are commonly used to create items for drop-down lists and lists of checkboxes. But

because they are really just lists of items, and because item groups can also have child items, you can use

SelectItem objects to create nested structureslike the items in a tree. So in this scenario, we use them to

define a list of items that the tree can display.

Using this technique, we define a tree with no tree cells, which also means that you can specify icons only

at the tree level. The default tree cell is created automatically.

The key element for this example is the sel ect I t emBean, which is bound to the tree as shown in theJSP snippet below.

The resulting tree is shown below.

In this example, we did not apply tree cell templates, so all cells are displayed in the default manner. You

should note that you can use tree cell tags to define templates if necessary.

The bean for this tree example shows how the tree data is set using only standard JSF SelectItem and

SelectItemGroup objects.

publ i c cl ass Sel ect I t emBean {

pr i vat e Sel ect I t em[ ] sel ect I t ems = creat eI t ems( ) ;

publ i c Sel ect I t em[ ] get I t ems( ) {r et ur n sel ect I t ems;

}

Figure 19. Select-Item Tree Example.



38/60



The following method contains all the logic that defines the tree.

pr i vat e Sel ect I t em[ ] cr eat eI t ems( ) {Sel ect I t emGr oup r oot I t em= new Sel ect I t emGr oup( "Per sonal Fol ders ") ;

Sel ect I t emGr oup[ ] chi l dI t ems = new Sel ect I t emGr oup[ 5] ;r oot I t em. set Sel ect I t ems( chi l dI t ems) ;

chi l dI t ems[ 0] = new Sel ect I t emGr oup( "Del eted I t ems ( 400) " ) ;chi l dI t ems[ 1] = new Sel ect I t emGr oup( "Dr af t s" ) ;chi l dI t ems[ 2] = new Sel ect I t emGr oup( "I nbox") ;

chi l dI t ems[ 3] = new Sel ect I t emGr oup( "Fami l y") ;chi l dI t ems[ 3] . setSel ect I t ems( new Sel ect I t em[ ] {new Sel ect I t em( "Momand Dad") ,

new Sel ect I t em( "Gr anni e") }) ;

chi l dI t ems[ 4] = new Sel ect I t emGr oup( "Sear ch Fol ders" ) ;chi l dI t ems[ 4] . setSel ect I t ems( new Sel ect I t em[ ] {new Sel ect I t em( "For Fol l ow Up") ,

new Sel ect I t em( "Large Mai l ") }) ;

r etur n new Sel ect I t em[ ] {r oot I t em};}

}

The root is a SelectItemGroup instance, whose children (SelectItem instances) represent individual nodes.

Note that every node that has children is also a SelectItemGroup instance.

The last statement in the method returns the root as a single value in an array.


39/60


Understa nding Tr eeModel and Tr eeNode

Before we examine the next three data definition techniques, we need to take a closer look at two interfaces

that ECruiser Tree uses internally to work with data: TreeModel and TreeNode.

TreeModel is the interface that defines a suitable data model for a tree. It is not a standard JSF Model; it

stands alone. TreeModel can work with either TreeNodes or plain old Java objects (POJOs).

TreeModel defines a simple, read-only interface for working with data. ECruiser also provides a

MutableTreeNode interface for trees with nodes that can be inserted or removed.

Now we need to examine a few additional classes and interfaces that implement or extend TreeModel and

TreeNode. These classes will help you quickly provide data for Tree, as well as accommodate more

complex scenarios.

The figure below illustrates how all of these classes are related.

The TreeModel interface provides basic methods for working with POJOs (including TreeNode

implementations). TreeModel features two convenience implementations: SelectItemTreeModel and

TreeCellModel. SelectItemTreeModel is used internally when you initialize a tree using JSF SelectItem

objects, and TreeCellModel is used internally when you statically initialize a tree in your page.

TreeModels with node structures that can be changed are represented by the MutableTreeModel interface.

A convenience base class, AbstractMutableTreeModel, provides basic implementations of some methods

and support for TreeModelEvents, which are fired to TreeModelListeners whenever an operation that

modifies the trees structure occurs.

ECruiser also provides NodeTreeModel (an AbstractMutableTreeModel subclass), which can be used

when the underlying data structure is modeled with TreeNode instances. MutableTreeNode extends the

TreeNode interface with methods for adding and removing child TreeNodes. DefaultMutableTreeNode is a

Figure 20. UML diagram representing TreeModel, TreeNode and related objects.



40/60



concrete implementation of MutableTreeNode which can be used in conjunction with NodeTreeModel to

dynamically build a tree using POJOs.

Earlier, we showed you how to use TreeCellModel and SelectItemModel implicitly. Next, we examine

how flexible Tree can be when you work directly with TreeModel and TreeNode, and their

implementations.

Using t he Tr ee Model and T r ee Node Techniques

This section provides more information about the three techniques based on TreeModel and TreeNode:

;;; Implementing the TreeModel Interface;;; Implementing the TreeNode Interface;;; Wrapping Business Objects in DefaultMutableTreeNode

Essentially these three techniques provide you with the means to return data via a customized tree model,

customized node objects, or with your own business objects, respectively.

Implementing the TreeModel Interface

The TreeModel interface accepts any kind of object as a tree node. It does not require that nodes

implement the TreeNode interface. For example, if you have a pre-existing hierarchical data structure, you

do not need to duplicate it, or force it to fit the TreeNode mold. You just need to implement your tree

model so that it uses the information in the existing data structure.

The TreeModel interface specifies methods for:

;;; getting a particular tree node.;;; getting the number of children of a particular node.;;; determining whether a node is a leaf.

The interface is designed to work with JavaBean-style objects (for example, POJOs that define read-onlydata sets). These objects can be linked to specific tree cells in the tree via tree cell templates. For example,

a tree based on File Objects could have two tree cellsone for directories, and one for files. The tree

template mechanism could select the proper tree cell using each File Object's i sDi r ector y( ) method.

In the example below, we assign a value binding expression, which binds the backing bean

t r eeModel Bean to the tree.


41/60


The resulting tree looks like this in a browser.

By now you might be saying: This tree looks familiar. It should; it is the same tree we have been

showing all along. The point is that you can create the same tree using a variety of techniques. When you

choose one of these methods, the tree could be easily changed dynamically, whereas with the static method

it is a little more difficult. Of course, the more sophisticated trees would also use more of the features

provided by the techniques described in this section.

The bean used to create the example driven byTr eeModel is shown below.

publ i c class TreeModelBean {

pri vate Tr eeModel t r eeModel = new Emai l Fol der Model ( ) ;

publ i c TreeModel getTreeModel ( ) {r etur n t r eeModel ;

}

publ i c voi d set TreeModel ( TreeModel t r eeModel ) {t hi s. t r eeModel = t r eeModel ;

}}

ThisTr eeModel implementation example uses a simple Emai l Fol der POJO with just two properties(name and iconPath). In the various methods, we hard-coded the tree relationship with conditionals, but a

real-world example could have SQL here instead.

publ i c cl ass Emai l Fol der Model i mpl ement s TreeModel {

public Object getChild(Object parent, int index) {

St r i ng parentName = ( ( Emai l Fol der) parent) . getName( ) ;i f ( par ent Name. equal s( "Per sonal Fol der s") ) {

i f ( i ndex == 0) {r eturn new Emai l Fol der( "Del et ed I t ems ( 400) ", "i mages/ personal . j pg") ;

}el se i f ( i ndex == 1) {

r et ur n new Emai l Fol der ( "Dr af t s", "i mages/ dr af t . j pg") ;

Figure 21. Tree example for all three techniques.



42/60



}el se i f ( i ndex == 2) {

r eturn new Emai l Fol der( "I nbox", "i mages/ i nbox. j pg") ;}el se i f ( i ndex == 3) {

r eturn new Emai l Fol der( "Fami l y", "i mages/ per sonal . j pg") ;}el se {

r eturn new Emai l Fol der( "Search Fol ders" , "i mages/ sear ch. j pg") ;}}el se i f ( par ent Name. equal s( "Fami l y") ) {

i f ( i ndex == 0) {r et urn new Emai l Fol der ( "Mom & Dad") ;

}el se {

r eturn new Emai l Fol der( "Gr anni e") ;}

}el se i f ( parent Name. equal s( "Search Fol ders" ) ) {

i f ( i ndex == 0) {r eturn new Emai l Fol der( "For Fol l ow Up") ;

}

el se {r eturn new Emai l Fol der( "Large Mai l ") ;

}}return nul l ;

}

public int getChildCount(Object parent) {

St r i ng parentName = ( ( Emai l Fol der) parent) . getName( ) ;i f ( par ent Name. equal s( "Per sonal Fol der s") ) {

r et ur n 5;}i f ( parent Name. equal s( "Fami l y") | | parent Name. equal s( "Sear ch Fol der s" ) ) {

r et ur n 2;}

el se {r et ur n 0;

}}

public Object getRoot() {

r eturn new Emai l Fol der( "Personal Fol ders" , "i mages/ personal . j pg") ;}

public boolean isLeaf(Object node) {

Str i ng name = ( ( Emai l Fol der ) node) . get Name( ) ;i f ( name. equal s( "Personal Fol ders" ) | | name. equal s( "Fami l y") | | name. equal s( "Search

Fol ders") ) {r et ur n f al se;

}

el se {return true;

}}

}

You should note here that the four methods highlighted above are the only methods that you must

implement when using the TreeModel interface, which helps simplify your tasks while still providing a

flexible option for retrieving data.


43/60



Implementing the TreeNode Interface

TheTr eeNode interfacedefines the requirements for an object that can be used as a node in a tree. Youcan implement one or more tree nodes and use them to construct a special, node-driven tree model called

NodeTr eeModel . In this case, the tree structure is wrapped and delivered on aper node basis.

To illustrate this technique, we created a custom, node-driven tree. Here we use just a single tree cell

template; all properties come from the custom node bean and its supporting Java code.

The bean used for this example is shown below.

publ i c cl ass CustomNodeBean {

private TreeModel treeModel = new NodeTreeModel(new RootFolderNode());


}


}}

The Java code that defines the RootFolderNode class is shown below. The tree is constructed here. We

specify nul l when we want to use the default tree style or icon.

publ i c cl ass RootFolderNode extends EmailFolderNode {

publ i c Root Fol der Node() {super ( "Per sonal Fol der s", "i mages/ personal . j pg", nul l ) ;

chi l dr en. add( new Emai l Fol derNode( "Del eted I t ems ( 400) ", "i mages/ personal . j pg","t reeCel l Bol d") ) ;

chi l dr en. add( new Emai l Fol der Node( "Dr af t s", "i mages/ dr af t . j pg", nul l ) ) ;chi l dr en. add( new Emai l Fol der Node( "I nbox", "i mages/ i nbox. j pg", nul l ) ) ;

Emai l Fol derNode f ami l yNode = new Emai l Fol derNode( "Fami l y", " i mages/ per sonal . j pg",nul l ) ;

f ami l yNode. i nsert ( new Emai l Fol der Node( "Mom& Dad", nul l , nul l ) ) ;f ami l yNode. i nser t ( new Emai l Fol der Node( "Gr anni e", nul l , nul l ) ) ;chi l dr en. add( f ami l yNode) ;

Emai l Fol derNode searchFol der sNode = new Emai l Fol der Node( "Search Fol der s" ,"i mages/ search. j pg", nul l ) ;

sear chFol dersNode. i nser t ( new Emai l Fol derNode( "For Fol l ow Up" , " i mages/ sear ch. j pg" ,nul l ) ) ;

sear chFol dersNode. i nsert ( new Emai l Fol derNode(" Lar ge Mai l ", "i mages/ sear ch. j pg"," t r eeCel l I tal i c" ) ) ;

chi l dr en. add( sear chFol dersNode);}

}


44/60



Because RootFolderNode extends EmailFolderNode, we show the following Java code, which represents

the base functionality of an email folder node in the example tree.

publ i c cl ass EmailFolderNode implements TreeNode {

pr i vat e St r i ng name;pr i vat e St r i ng i conPat h;pri vat e St ri ng st yl eCl ass;

pr i vat e Emai l Fol derNode parent ;pr ot ect ed Li st chi l dr en = new Ar r ayLi st ( ) ;

publ i c Emai l Fol der Node( St r i ng name, St r i ng i conPat h, St r i ng styl eCl ass) {t hi s. name = name;t hi s. i conPat h = i conPat h;t hi s. st yl eCl ass = st yl eCl ass;

}

public TreeNode getChildAt(int childIndex) {

r et ur n ( Tr eeNode) chi l dr en. get ( chi l dI ndex);}

publ i c i nt get Chi l dCount ( ) {

return chi l dren. si ze( ) ;}

public int getIndex(TreeNode node) {

r et ur n chi l dr en. i ndexOf ( node) ;}

public boolean isLeaf() {

r et ur n chi l dr en. si ze( ) == 0;}

publ i c Tr eeNode getPar ent ( ) {r eturn par ent ;

}

publ i c St r i ng get I conPat h( ) {r eturn i conPat h;

}

publ i c St r i ng getName( ) {r et urn name;

}

publ i c St r i ng get St yl eCl ass( ) {r et ur n styl eCl ass;

}

pr ot ect ed voi d i nser t ( Emai l Fol der Node chi l d) {chi l dren. add( chi l d) ;chi l d. parent = t hi s;

}

}

Note that the highlighted segments above are methods of the TreeNode interface, which this class must

implement.

This example illustrates how you can implement TreeNode for a non-mutable data structure. Now we take

a look at how to implement a concrete class for mutable structures.


45/60



Wrapping Business Objects in DefaultMutableTreeNode

DefaultMutableTreeNode is a general-purpose TreeNode implementation that can be used to build a tree

data structure. Because DefaultMutableTreeNode is a MutableTreeNode, it also allows users to

dynamically move, add, or delete nodes within the tree. The class also provides operations that examine

and modify a node's parent and children.

When building up the tree structure, you can use a Def aul t Mut abl eTr eeNode instance as an objectwrapper. This technique works with POJOs; you do not need to subclass anything.

In the example below, we use tree cell templates to define formatting based on the node values set by the

matchExpr essi on properties.

For this approach, we created the following bean, which uses POJOs wrapped in tree nodes. The first part

of the bean builds the tree structure by wrapping Emai l Fol der objects (the POJOs) inDef aul t Mutabl eTr eeNodes. Our backing bean returns a NodeTreeModel instance with aDefaultMutableTreeNode set as the root (NodeTreeModel is a special implementation of the

MutableTreeModel interface designed to work with MutableTreeNodes as the underlying objects).

publ i c class DefaultNodeBean {

pr i vat e TreeModel t r eeModel ;

publ i c Def aul t NodeBean() {t r eeModel = cr eat eTr eeModel ( ) ;

}


}


}

pr otected TreeModel cr eat eTr eeModel ( ) {Def aul t Mutabl eTreeNode root = new Def aul t Mut abl eTreeNode

( new Emai l Fol der ( "Per sonal Fol der s", "i mages/ per sonal . j pg") ) ;r oot . i nser t ( new Def aul t Mutabl eTr eeNode

( new Emai l Fol der ( "Del eted I t ems (400) ", "i mages/ personal . j pg") ) ) ;r oot . i nser t ( new Def aul t Mutabl eTr eeNode

( new Emai l Fol der ( "Dr af t s", "i mages/ dr af t . j pg") ) ) ;r oot . i nser t ( new Def aul t Mutabl eTr eeNode

( new Emai l Fol der ( "I nbox", "i mages/ i nbox. j pg") ) ) ;Def aul t Mutabl eTreeNode per sonal = new Def aul t Mutabl eTreeNode

( new Emai l Fol der ( "Fami l y", "i mages/ per sonal . j pg") ) ;root . i nsert ( personal ) ;personal . i nser t ( new Def aul t Mutabl eTr eeNode(new Emai l Fol der( "Mom & Dad") , t r ue) ) ;


46/60



personal . i nsert ( new Defaul t Mut abl eTr eeNode( new Emai l Fol der( "Gr anni e") , t r ue) ) ;Def aul t Mutabl eTreeNode search = new Def aul t Mut abl eTreeNode

( new Emai l Fol der( "Search Fol ders" , "i mages/ sear ch. j pg") ) ;root . i nsert ( search) ;sear ch. i nser t ( new Def aul t Mutabl eTr eeNode

( new Emai l Fol der( "For Fol l ow Up", "i mages/ sear ch. j pg") ) ) ;sear ch. i nser t ( new Def aul t Mutabl eTr eeNode

( new Emai l Fol der ( "Large Mai l ", "i mages/ sear ch. j pg") ) ) ;

r et urn new NodeTr eeModel ( r oot ) ;}

}

If you take a closer look at some of the code content, you see that the following statement creates a new

node calledroot:

Def aul t Mut abl eTreeNode root = new Def aul t Mut abl eTreeNode( new Emai l Fol der ( "Per sonal _Fol der s", "i mages/ per sonal . j pg") ) ;

Statements such as the following create a new node, in this case called Drafts, whose parent is root:

r oot . i nser t ( new Def aul t Mutabl eTr eeNode( new Emai l Fol der( "Dr af t s", "i mages/ dr af t . j pg") ) ) ;

Alternatively, the following statements create a new node called search whose parent is root:

Def aul t Mut abl eTreeNode search = new Def aul t Mutabl eTreeNode( new Emai l Fol der( "Search Fol ders" , "i mages/ sear ch. j pg") ) ;

root . i nsert ( search) ;

The MutableTreeNode interface has an insert method that takes an index, but here we use an insert method

from DefaultMutableTreeNode that does not require an index; it just adds the child to the end of the list.

The DefaultNodeBean references the following EmailFolder class, which represents the base functionality

of the email folders used in this example.

publ i c class EmailFolder {

pr i vat e St r i ng name;

pr i vat e St r i ng i conPat h;

publ i c Emai l Fol der( St r i ng name) {t hi s. name = name;

}

publ i c Emai l Fol der ( St r i ng name, St r i ng i conPat h) {t hi s. name = name;t hi s. i conPat h = i conPat h;

}

publ i c St r i ng getName( ) {r et urn name;

}

publ i c voi d set Name(Str i ng name) {t hi s. name = name;

}

publ i c St r i ng get I conPat h( ) {r eturn i conPat h;

}

publ i c voi d set I conPat h( St r i ng i conPat h) {


47/60



t hi s. i conPat h = i conPat h;}

}

You should take notice that the TreeModel assigned in this example is the NodeTreeModel class. In thiscase, it is expected to handle mutable operations, so the nodes are instances of MutableTreeNode.

The difference in this example besides adding mutability features to the tree is that it wraps objects tocreate the nodes needed by NodeTreeModel. This technique can be a convenient approach when you want

to work with existing POJOs.

Chapt er Summar y

This chapter discussed your options for defining tree data. Essentially, you have five techniques from

which to choose:

;;; Using Static Tree Data in Tags;;; Using JSF SelectItem Objects;;; Implementing the TreeModel Interface;;; Implementing the TreeNode Interface;;; Wrapping Business Objects in DefaultMutableTreeNode

Each technique has specific advantages depending on your applications needs. The first two techniques

are shortcuts that allow you to easily initialize a tree without working directly with tree models. Using

Static Tree Data, you need only define the andtags in a JSP. Tree works behindthe scenes to create the model using TreeCellModel. Likewise, you can use JSF SelectItem objects to

initialize your tree and the component will again work behind the scenes to create your model using

SelectItemsTreeModel. (You also have the option of working directly with these classes if you prefer, butthe shortcuts minimize the tasks needed to implement simpler trees.)

For more advanced scenarios, you can choose from three techniques that require more work on your part,

but deliver more power and flexibility. The software design also helps minimize the effort required by

completing many tasks at higher levels, thereby reducing the number of methods that require

implementation at the level you choose.

The TreeModel interface accepts any kind of object as a tree node. It does not require that nodes

implement the TreeNode interface. If you have a pre-existing hierarchical data structure, you just need to

implement your tree model so that it uses the information in the existing data structure.

The TreeNode interfacedefines the requirements for an object that can be used as a node in a tree. You can

implement one or more tree nodes and use them to construct a special, node-driven tree model called

NodeTr eeModel . In this case, the tree structure is wrapped and delivered on aper node basis.

The third technique, Wrapping Business Objects in DefaultMutableTreeNode, lets you define tree data

using the Def aul t Mutabl eTr eeNode class via the Mut abl eTr eeModel interface. This techniqueuses a Def aul t Mutabl eTr eeNode instance as an object wrapper. Objects can be almost anything,including POJOs.


48/60



6 Interacting with the UserECruiser Tree provides many options for customizing the user experience. In this chapter, we examine

the options for adding drag-and-drop functionality, and employing the AJAX (Asynchronous JavaScript

and XML) development technique to provide an extremely responsive user experience.AJAX uses JavaScript to talk to the web application in the background without re-loading the entire web

page. Because Tree encapsulates the AJAX functionality within the component, it provides full-fledged

AJAX functionality without any JavaScript coding. In other words, you can use the standard JSF

programming model and still have full AJAX support.

Each section provides information to help you modify Tree to enhance the user experience.

Enab li ng AJAX Suppor t

The single aj ax property enables basic AJAX support. By default, this property is true and AJAX isenabled for Tree. When this property is true, Tree executes selection events, drag-and-drop functionality,

or even preloading and automatic reloading of child nodes via AJAX. AJAX support increases the speed at

which these features operate and updates the tree without refreshing the entire page.

Table 8. Properties related to AJAX behavior.

Property Description Default

a j a x Flag that controls whether theevents of the component use the

AJAX request mechanism. Set this

property at the tree level only.

true

d i r t y The value of the dirty flag. Used todetermine if this component's

state has somehow been changed

so that it needs to be updatedbefore rendering. This is helpfulwhen AJAX support is enabled.

Generally, this property will beautomatically set and reset by the

ECruiser AJAX mechanism.Application developers should only

need to set this in specialcircumstances.

false

Communications with the server uses AJAX by default, but if you set the aj ax property to false you canswitch to the standard behavior, where each operation requires a full-page refresh.


49/60



Set t ing Pr eload ing and Reload ing Feat ures

Tree allows you to define how data from the server is loaded to the client. Two properties help you specify

how many levels of the tree to preload for the client and whether children nodes are reloaded from the

server each time the user expands a node. The following table describes these two properties.

Table 9. Properties used to define data loading for client.


p r e l o a d D e p t h Specifies the number of levels

(depth) of the tree that should bepreloaded for the client. Defaultvalue of 1 preloads the root tree

cell and its children. Specifying a

negative number preloads allchildren. Set this property at the

tree level only.

1

r e l o a d i n g Specifies whether the browser

should retrieve children from theserver each time the user expandsa node versus caching them after

the first retrieval. Set this property

at the tree level only.

false

By default, Tree loads child nodes after the roots children lazily when the user expands a node. Using the

prel oadDept h property allows the component to display quickly even if you have hundreds orthousands of child nodes. This property defines the number of levels that the client will load from the

server the first time Tree is displayed. To preload all the levels of the tree, specify a negative number.

Choosing the preload depth is a tradeoff between the initial load time and the responsiveness of Tree whenthe user expands a node. For small trees, preloading all nodes ensures that the component is very

responsive. For larger trees, you might want to stick with the default (one level), or try a slightly higher

number.

Reloading simply allows you to define whether the client loads child nodes from the server every time theparent node is expanded. Set reloading to true to have the client update the list of child nodes whenever

the user expands a node. Set reloading to false to have the user see what the client stored previously.


50/60


Def ini ng Scrol l i ng Behavi or

You can change Trees scrolling behavior using the scrolling property, which is described in the table

below.

Table 10. Property used to define scrolling behavior.

Property Description Defaults c r o l l i n g Define the scrolling type. This can

be set to the following values:

;;; autoscrollbars appearautomatically depending on the

content size.

;;; nonescrollbars never appear andall content will visible.

auto

In the example below, we customize the Simple Tree Example to allow easier viewing. We increase the

node height to accommodate larger text set in the styles, but restrict the trees vertical display area to 300

pixels.

We set the related properties at the tree level as shown below:

As a result, Tree displays in a browser as shown below:

Figure 22. Tree illustrating use of scrolling feature.

Because auto is the default setting for scrolling, Tree will automatically display scrollbars when the

content exceeds the allotted display area. Set the property to none to turn off scrollbars and display all of

the content.



51/60



Suppor t ing Dr ag and Dr op

ECruiser Tree supports dragging and dropping tree cells to reorder cells within a tree, or to transfer tree

cells between two Trees. This section introduces you to this feature, describes its related properties, and

provides examples of using drag and drop. The following table provides descriptions of the drag-and-drop

properties.

Table 11. Properties that define drag-and-drop support.


d r a g T y p e The string identifier that definesthe type of drag object

transferred by this component.

For example: item, trade, or *.

d r o p T y p e s The comma-separated list of drag

types that this component canaccept. For example: item,

trade, *.

a

tree guide v2.4

Documents