Tree Builder
In this topic ...
Getting the Input Value from the Tree
Related Topics ...
Use the Tree builder to display a tree of information and allow the user to select a single element from the tree. Think of a tree as being yet another select control. The advantage the Tree builder provides is that it displays data in a familiar tree format, with open and close icons.
When you create a Tree builder, you pass it an XML structure, such as you might create in a Variable, or that might be returned from a service call. The Tree builder provides a number of options for exactly how the tree should display, and the format in which it should return its value. When a page containing a Tree builder is rendered, a Tree Handler interprets your XML tree and constructs HTML to create the tree behavior.
This builder's output is rendered as a select list In browsers other than Microsoft's Internet Explorer. Consequently, various inputs to this builder (Look & Feel items, Advanced items, etc.) do not apply in non-Internet Explorer settings.
Quick Tips
- Opening the Tree at the last selected node -- If you show a page with a tree on it and save the value from the tree, then the next time you show that same page, if you pass in your saved value as the Selected Value, the same node will initially display as selected.
- Create your own node and leaf icons -- We can create your own icons for use in a Tree builder display. If you do, use an image size of 18 x 18 pixels.
Specifying Inputs
The Tree builder takes the inputs described in the table below. For help on inputs common to many or all builders such as those in the Properties and HTML Attributes input groups, see "Using the Builder Call Editor."
Input Name Description Name Enter a name for this builder call. The Designer displays this name in the Builder Call List. Page Location Use the Page Location input to specify the page or pages on which this builder call will act. See "Locating Control Builders on Pages" for detailed documentation about the Page Location input and page location syntax.
Tree Data Specify data returned from a Method, Service Call, or Variable. This data will be in XML. Visible Root Node Check this to force the tree to start by displaying the root node (in whatever display format you select). If not selected, then the tree will not show the root, but will start by displaying the first set of children. Allow Multi-Select Enable this check box if you want the user to be able to select more than one item listed in the tree. To use the multi-select capability, the user must select items in the tree use CTRL+ CLICK. Display Style There are several Display Style choices. Following each is a sample of what would be displayed for the node <SS2>Sub Section 2</SS2>.
- Show the text from the XML Node -- "Sub Section 2"
- Show just the XML tag -- "SS2"
- Show <tag> and text -- "<SS2> Sub Section 2"
Selection Rule Indicate the selection options available for this tree. Options are:
- All nodes can be selected -- Choose this to enable a user to select any element in the tree.
Select this if you want the tree to return a value.
Sometimes a tree is just for display purposes, so that the end user can browse through some hierarchical information. When this is the case, there is no concept of the user selecting one of the nodes. If you do not want a user to be able to select a node, uncheck this check box.
- Only leaf nodes can be selected -- Choose this to prevent a user from selecting Parent Nodes in the tree.
If this is checked, only leaf nodes (those that have no children) are selectable. Note that this setting is ignored if the previous setting is unchecked.
- No Selection - Tree does not return a value -- Choose this to present a user with a read-only tree. Such a tree is often used for display purpose to indicate hierarchical relationships among items.
(optional) Selected Value Specify the node in the Tree Data that you want to be initially selected when the tree displays. We can configure the tree to "open" at the last selected node by setting the value of a String variable to the selected value of the tree when you process the page's Submit event.
Note: In the TreeStyle structure set the <Data /> value for any selectable elements to: default^nodeNamePath.
See "Configuring the Tree to Open at the Last Selected Node" for more information.
Return Data Style We can determine the format of the data for the selected node by selecting one Return Data Style value. The descriptions for the Return Data Style options uses the following XML structure as an example and assumes the user clicked on "Joe": <customers>
<customer>Joe
<id>1111</id>
<region>North</region>
</customer>
<customer>Jane
<id>2222</id>
<region>South</region>
</customer>
</customers>
- Just the Text in the XML Node -- Returns "Joe."
- Using node text - build full path name -- Returns "Root:/Joe"
- Just the XML Tag -- Returns "customer"
- Using XML Tags -- Returns "customers/customer[0]"
- XML Tags - full pathname - skip top node -- returns "customer[0]"
- XML from node -- Returns "<customer>Joe
<id>1111</id>
<region>North</region>
</customer>"Look and Feel Node Indent This is the number of pixels each level is indented from the previous level. The default is 40. Note that on Netscape Navigator only the first level is indented using this setting. Closed Node Icon Name and path of graphic file to represent a closed "branch" node in the tree. Default value: factory/images/tree/closednode.gif
Open Node Icon Name and path of graphic file to represent an open "branch" node in the tree. Default value: factory/images/tree/opennode.gif
Leaf Node Icon Name and path of graphic file to represent a single "leaf" in the tree. Default value: factory/images/tree/leafnode.gif
Expand Node Icon Use an indirect reference to specify an image to be used for the icon representing an expanded node. If no value is specified, then the tree will resort to the default image.
Unexpand Node Icon Use an indirect reference to specify an image to be used for the icon representing an un-expand node. If no value is specified, then the tree will resort to the default image.
Selected Icon
Name and path of graphic file to designate an item as "selected." Default value: factory/images/tree/rightarrow.gif
Tree Width Enter the width, in pixels, of the tree control. Tree Height Enter the height, in pixels, of the tree control. Disable Border Enable to remove the dark grey border from around the tree. Advanced (optional) Custom Tree Style Specify the XML data that defines the display characteristics for each node in the tree data. For example, if a variable called "TreeStyle" contains the display information, the Custom Tree Style value would be: ${Variables/TreeStyle/Styles}, where "Styles" is the top node of the XML structure contained in the TreeStyle variable. For more information, see Customizing the Tree Display. Note: If you specify a value for this input, the Display Style and Data Style input values are ignored.
(optional) Return Value Prefix Enter a prefix that will be added to the selected items value. We can use this feature to send extra information or to further identify the selected value. For example, you could enter ${Variables/prefixVar} as a value for the prefix. The resulting value for the selected item would have the value of prefixVar prepended to its own value.
(optional) Return Value Suffix Enter a suffix that will be added to the selected items value. We can use this feature to send extra information or to further identify the selected value. For example, you could enter ${Variables/suffixVar} as a value for the prefix. The resulting value for the selected item would have the value of prefixVar appended to its own value.
Customizing the Tree Display
We can control the display of the nodes and leaves of the tree with an XML structure stored in a variable or returned by a method or service. The XML structure declares the Opened Node, Closed Node, and Leaf Node images, the caption, and data information for each element in the Tree Data structure. Elements whose image, caption, and data information is not explicitly defined in a specific NodeStyle element use the images and caption information defined by the DefaultNodeStyle element.
Notes
- Any NodeStyle elements not defined for a particular node in the tree will get their values from the DefaultNodeStyle element in the TreeStyle structure.
- Paths to image files are relative to the Factory's <servable_content_root>/factory/classes directory, which is where the code for the Tree applet resides.
The following XML structure controls the display of the Employees and Employee nodes for a tree structure.
<TreeStyle>
<DefaultNodeStyle>
<Images>
<OpenedNodeImage>../../factory/images/tree/opennode.gif</OpenedNodeImage>
<ClosedNodeImage>../../factory/images/tree/closednode.gif</ClosedNodeImage>
<LeafNodeImage>../../factory/images/tree/leafnode.gif</LeafNodeImage>
</Images>
<Caption>default^text</Caption>
<Data>default^nodeNamePath</Data>
</DefaultNodeStyle>
<NodeStyle>
<TagName>Employees</TagName>
<Images>
<OpenedNodeImage>../../factory/images/tree/opennode.gif</OpenedNodeImage>
<ClosedNodeImage>../../factory/images/tree/closednode.gif</ClosedNodeImage>
<LeafNodeImage>../../factory/images/tree/leafnode.gif</LeafNodeImage>
</Images>
<Caption>const^Employee List</Caption>
<Behaviors>
<Behavior>
<Event>onclick</Event>
<Trigger>LJOName.showClickInfo</Trigger>
<Target>_self</Target>
<ClientTrigger>alert('caught an employee click');</ClientTrigger>
</Behavior>
</Behaviors>
</NodeStyle>
<NodeStyle>
<TagName>Employee</TagName>
<Images>
<OpenedNodeImage>../../factory/images/tree/opennode.gif</OpenedNodeImage>
<ClosedNodeImage>../../factory/images/tree/closednode.gif</ClosedNodeImage>
<LeafNodeImage>../../factory/images/tree/leafnode.gif</LeafNodeImage>
</Images>
<Caption>path^Name</Caption>
<ItemList listtype="include">
<Item nodename="Address" />
<Item nodename="City" />
<Item nodename="State" />
</ItemList>
<Data>path^State</Data>
</NodeStyle>
</TreeStyle>
The following table describes each of elements used in a NodeStyle structure.
NodeStyle Element Used for ... <OpenedNodeImage /> Specifying the image to display for opened nodes. <ClosedNodeImage /> Specifying the image to display for closed nodes. <LeafNodeImage /> Specifying the image to display for leaf nodes. (Nodes without children.) <ItemList /> Specifying a list of child elements to display, or to keep from being displayed, under the node. See "<ItemList /> Options" for more information.
<Caption /> Specifying the text to display for the node. See "<Caption /> Options" for more information.
<Behaviors /> Specifying the method to run or the JavaScript to execute when the user clicks on the node. See "<Behaviors /> Options" for more information.
<Data /> Specifying the input value when the node is selected. See "<Data /> Options" for more information.
<Caption /> Options
Desired Display Value of <Caption /> Element Text value for the node default^text XML tag for the node default^tag XML tag and text value for the node default^tagtext The text value for a child of the node path^XPath/to/child -- Where XPath/to/child is an XPath notation that points to a text value in the XML structure of the tree. Note: XPaths are relative from the current node.
Constant Value const^Value -- Where "Value" will be displayed for any occurrences of this node in the tree.
<Behaviors /> Options
Desired OnClick Action Value for <Behaviors /> Element Execute an Action List, Method, or LJO method <Behaviors> <Behavior>
<Event>onclick</Event>
<Trigger>LJOName.methodName</Trigger>
<Target>_self</Target>
<ClientTrigger></ClientTrigger>
</Behavior>
</Behaviors>
Execute client-side JavaScript <Behaviors> <Behavior>
<Event>onclick</Event>
<Trigger></Trigger>
<Target>_self</Target>
<ClientTrigger>alert('caught an employee click');</ClientTrigger>
</Behavior>
</Behaviors>
<Data /> Options
Desired Return Value Value for <Data /> Element Text of selected node default^nodeText XML tag name of selected node default^nodeName XPath to the selected node default^nodeNamePath XML of the selected node default^nodeXML Text values for all the elements in the XPath down to the selected node default^nodeTextPath Text value of a child element of the selected node path^XPath/to/child Constant value const^ValueToReturn
<ItemList /> Options
Child Node Display Behavior Value for <ItemList /> Element Show all children Default behavior. You do not need to include an <ItemList /> element in the NodeStyle XML to display all the children for a node.
Do not show any children <ItemList listtype="include"></ItemList> Show most children <ItemList listtype="exclude"> <Item nodename="ChildOnetoHide" />
<Item nodename="ChildTwotoHide" />
</ItemList>
Show a few children <ItemList listtype="include"> <Item nodename="ChildOnetoDisplay" />
<Item nodename="ChildTwotoDisplay" />
</ItemList>
Getting the Input Value from the Tree
We can extract the selected value in the Tree from request with code similar to the following:
webAppAccess.getRequestInputs().getInputValue("inputname");
The value passed from the Tree to the inputs object is determined by the <Data> element in the selected item's <NodeStyle> element.
Configuring the Tree to Open at the Last Selected Node
We can configure the tree to open at the last selected node by performing the following steps:
- Create a String variable to hold the XPath value for the last selected node. For example, SelectedNode.
- Set the Tree builder calls Selected Value input to the variable you created in Step 1. For example, ${Variables/SelectedNode}.
- In the method that processes the Submit event for the page, assign the input value of the Tree builder call to the variable you created in Step 1. For example,
webAppAccess.getVariables().setString("SelectedNode",
webAppAccess.getRequestInputs().getInputValue("TreeName");
The tree will now open at the last selected node during the execution of the model .