Data Item: Tree#
This data item contains a tree of name/value pairs. These pairs are organized in an ordered tree structure. Each entry includes a 'name' which is used for display purpose, a 'key' that can be used for classification/comparison and a value. The entry may optionally include hints on how the entry should be displayed and an optional list of children entries (each of which can also have children). Data values in the tree can be Boolean, Integer, Floats, Date/times, Strings, a Data Item GUID or empty.
Display options#
The tree item is displayed as a two column table, where child trees can be nested as an indented collection of entries. The left column includes controls that enable the children of an entry to be hidden or displayed. To the left of those controls are the 'name' values from the entries. In the right column is the entry value. The value supports various formatting options for the different types. The properties that control this are documented in the table at the end of this section.
The tree can be set up to display entries in collapsed or expanded form. In the latter, all of the children are visible.
Tree Item hinting#
Individual entries support hints that suggest the initial state of entries. Current hints include: 'state' and 'header'. The default visibility is controlled by the 'state' hint (if no hint is given the entry is displayed expanded). The 'tree_initial_state' property can be used to override the expansion hints, but it is applied to the entire tree. The 'header' hint specifies that a row in the tree table be displayed as a 'header' with bold text and enhanced bottom border.
In addition to hints, every tree row include a 'key' value which is not displayed (the 'name' and 'value' values are always displayed). The 'key' value is a mechanism to tag an item with additional, hidden information that can be used to filter items or aggregate them using generators.
Properties#
Property |
Value |
|---|---|
item_justification |
Controls the justification of trees in reports and detail pages. Overrides report-wide justification. Can be left, center or right. By default, there will be no justification. |
table_cond_format |
This property sets the conditional formatting for the tree entries. See conditional formatting ting for more details. |
tree_format_bool |
This string is used when the value is a boolean. It takes the form {XXX}#{YYY} where XXX is the string used for the true value and YYY is the string used for the false value. The default is: True#False |
tree_format_date |
When the value is a date/time, this string is used to pick the formatting. See Table Date formatting for specifics. The default is: date_44 |
tree_format_float |
For a float value, this string is used for formatting. See Table Float formatting. The default is: floatdot2. |
tree_format_guid |
When the value is a GUID that maps to another valid data item, this value is used to select how the item is displayed. The value 'link' will display the item via hyperlink to a new page. The value 'inline' will attempt to display the item directly in the tree view structure. The default is: link |
tree_initial_state |
This property allows the tree to be entirely expanded or collapsed initially. Legal values are: expanded, collapsed and the default is: expanded |
tree_bordered |
If this property is 0, the tree's border will be removed. The default is 1. |
tree_condensed |
If this property is 1, the tree's horizontal and vertical height will be minimized making it look compact. The default is 0. |
tree_global_toggle |
If this property is 1, the option to Expand All/Collapse All nodes of trees will be visible. The default is 0. |
Tree Conditional Formatting#
The property is a conditional formatting string. In the discussion of how conditional formatting is applied to tree objects, it is useful to understand the concept of node names and keys in tree objects (see the Python API for tree item details). Tree formatting begins by creating a table based the nodes in the tree. The table row names are computed from the tree node names. Consider the tree formed from this code snippet:
c0 = dict(name='Child' key='leaf0', value=500)
c1 = dict(name='Child' key='leaf1', value=[1000, 2000])
dict(name='Top', key='root', value=[100, 200], children=[c0, c1])
The table generated from this tree will look like this:
Row label |
Column 0 |
Column 1 |
|---|---|---|
Top/root |
100 |
200 |
Top/root|Child/leaf0 |
500 |
|
Top/root|Child/leaf1 |
1000 |
2000 |
Row labels are generated by concatenating the name and key for the tree node with the '/' character and the parent to the child using the '|' character. The naming convention makes it possible to write rule target expressions using the visible node names and the (hidden) node key value. Tree conditional formatting follows the rules for tables using the transformation from tree to table noted above.
Tree formatting has two additional formatting functions: openparent() and openparents(). These formatting functions allow the conditional formatting rule to set the initial state of the target nodes. openparent() ensures the parent node to the target node to be 'expanded'. openparents() ensures all of the parent nodes to the top of the tree would be 'expanded'. This can be useful in conjunction with the 'collapsed' tree_initial_state.