Generator: Tree Merge

The purpose of the tree merge generator is to take multiple input data tree items and combine them into a single tree item. It produces a single output tree every time it is passed a list of input data items. If there are no tree data items in the input list, no output tree is generated. The tree merging operation works by matching the tree row "names" and concatenating the values from each tree. The resulting tree will have at least one column of values added for each input tree. The merging process can be customized to select specific rows to merge.

Configuration options

The configuration options for this generator are relatively simple and are presented in the template editor main window. An example might be:

The generator starts by copying the first tree item in the list. It then builds a table from the tree with one row for each leaf in the tree. Each row consists of a name and the value columns from the tree leaves. For example, the tree:

is represented by the generator as the table:

Row name	name	key	value[0]	value[1]
top 1/top	top 1	top	Numbers	strings
top 1/top|leaf 1 1/leaf	leaf 1 1	leaf	1.0	N/A
top 1/top|leaf 1 2/leaf	leaf 1 2	leaf	2.0	N/A
top 2/top|	top 2	top	Numbers	strings
top 2/top|leaf 2 1/leaf	leaf 2 1	leaf		Hello
top 2/top|leaf 2 2/leaf	leaf 2 2	leaf		Bye
top 3/top|	top 3	top	100	200

The generator compares values in the "Row name" column. If there is a match, the value columns from the additional tables are added to the working table.

If the value in a table cell is unspecified, the 'Fill value' specified in the configuration options is used as the value of the cell. In the example, two rows had no values specified for value[1] and the fill value: 'N/A' is supplied by the generator.

The "Match rows by" option controls how the "Row name" column is computed. The row name is formed using the form {parentname}|{rowitemname}. The {rowitemname} can be one of three forms based on the "Match rows by" option. "Name and key" forms the names as shown here: {name}/{key}. It can also be just the {name} or just the {key}. This allows the tree merge generator to decide to merge rows using the hidden tree item 'key' values independently of the item name.

The "Row merge" option controls what happens when a row name match or non-match happens. There are three options:

'All rows' - if two trees have the same row, the value columns are appended.

'Common rows' - only those row names that are present in all of the input trees will be included in the output tree.

'Rows from first tree' - in this mode, the first input tree defines all of the rows that will be included in the output. If a row name is not present in another tree, the fill value will be output for the value columns for that tree.

The generated tree will have the tags copied from the generator itself and will have the item name specified by the 'Output tree name' option (so the item can be filtered in child templates).

The 'Header tag name' can be used to generate a new 'header' tree item at the top of the output tree. If the value is not empty, the values for the tree item will be taken from the tag named in that field.

Note: tree row hints will be copied from the first tree where a given "Row name" is encountered. There is no requirement that each tree will have the number of values.

Example

A more complex, but common example is illustrated next. First, consider the two input trees:

Note the 'header' tag value and the fact that the 'Design Point 20' tree lacks the 'Order' row. Using the options noted above, the resulting tree looks like this:

Notice the introduction of a header row at the top of the tree with values pulled from the 'header' tags. Also, the introduction of the 'N/A' value for the missing row in the "Design Point 20" tree.