tree

Provides an iterative list capability for parent/child hierarchies.

Summary

[tree table master subordinate start] ... [/tree]

Parameter	Description	Default
table	Database table which contains the tree.	None
master	The column which is used to determine the parent of the item.
subordinate	The child column, which determines which items are sub-items of the current one.	None
sub	Alias for subordinate.	None
start		None
autodetect	Specifies that the next level should be followed to detect the number of child items contained.	None
code_field		None
collapse	The name of a variable in the user's session which will determine that the tree should be "collapsed".	None
continue	The name of an optional continue field which, when set true, can force the branch to be followed.	None
delimiter		None
explode	The name of a variable in the user's session which will determine that the tree should be "exploded".	None
file
full	Specifies that all items should be followed.	None
toggle	The name of a variable in the user's session which determines if current item should be either followed or not.	None
level_field		None
log_error	If endless tree is detected, an error will be logged.	None
memo	Names a scratchpad variable for use with the collapse/explode/toggle feature.	None
multiple_start		None
object
outline	Sets outline mode, where mv_increment will be displayed with letter or numerical values.	None
pedantic	Guard against endless tree loops by not following endless branches. Also logs the error.	No
show_error	If and endless tree is detected, returns error to page.	None
sort	determines the order in which they will be displayed under the current parent.	None
spacer
spacing
start_item	The first item to be followed.	None
stop	An optional stop field which, when the value is true, can stop the following of the branch.	None
where
hide	Suppress any output text that would ordinarily be returned from this tag. (This universal parameter was introduced with Interchange version 5.5.2.)	No
interpolate	Parse Interchange tags, included in the body text, before this container tag executes.	No
reparse	Process any Interchange tags found in the text output from this tag.	Yes

Examples

Tag expansion example

The [tree] tag works with data sets with the following parent/child structure:

Key	Parent
a	99
b	a
c	a
d	a
x	a
y	x
z	x
m	99
n	99
o	99
e	o
f	o
g	o

The above sample data, placed in a table named "tree", could be used to as follows:

Tag call

<table>
[tree
start=99
table=tree
master=parent
subordinate=child
autodetect=1
spacing=4
full=1
]
<tr>
<td>
[if-item-param mv_level]
[item-calc]
return ' ' x [item-param mv_spacing];
[/item-calc]
[/if-item-param]
[item-param child]
</td>
<td>
mv_level=[item-param mv_level],
mv_increment=[item-param mv_increment],
mv_children=[item-param mv_children]
</td>
</tr>
[/tree]
</table>

Tag call pseudo-output

a    mv_level=0, mv_increment=1, mv_children=4
b    mv_level=1, mv_increment=1, mv_children=0
c    mv_level=1, mv_increment=2, mv_children=0
d    mv_level=1, mv_increment=3, mv_children=0
x    mv_level=1, mv_increment=4, mv_children=2
y   mv_level=2, mv_increment=1, mv_children=0
z   mv_level=2, mv_increment=2, mv_children=0
m    mv_level=0, mv_increment=1, mv_children=0
n    mv_level=0, mv_increment=2, mv_children=0
o    mv_level=0, mv_increment=3, mv_children=3
e    mv_level=1, mv_increment=1, mv_children=0
f    mv_level=1, mv_increment=2, mv_children=0
g    mv_level=1, mv_increment=3, mv_children=0

Perl example

$Tag->tree({
table => $table,
master => $master,
subordinate => $subordinate,
start => $start,
body => $body,
});

or similarly with positional parameters:

$Tag->tree($table, $master, $subordinate, $start, $attribute_hash_reference, $body);

Description

This tag provides an iterative list capability for binary trees It presents the tree data in a loop of hash-based rows, pretty much the same as as [item-list].

Some additional hash key entries are also provided, to describe the tree and provide display control.

Hash keys

Sets several keys which assist in walking and displaying the tree, to be used within the looping tags construct, such as [PREFIX-param]. See the Looping tags introduction.

mv_level

Level of the item. 0 is the first level. Sub-levels are infinite (except for performance).

mv_increment

Increment label for the item. This normally goes from 1...n, but can be changed to A...Z or a...z, in outline mode.

mv_children

If in autodetect mode then this is set to the number of children in this branch. If a leaf then it is set to 0.

mv_spacing

This is a multiple of the value of the spacing parameter, and is useful for determining the row indentation width.

Parameters

table

Database table which contains the tree. Must be a valid Interchange table name.

master

The column which is used to determine the parent of the item.

subordinate

The child column, which determines which items are sub-items of the current item. This is used to re-query for items with its value in master.

start

autodetect

Specifies that the next level should be followed to detect the number of child items contained. This is not recursive; It only follows far enough to determine the children of the current item.

code_field

collapse

The name of a variable, in the user's session, which will determine whether the tree should be "collapsed". When collapsed, the child items will not be followed unless they are set to be followed with toggle. This parameter zeros all toggles.

Collapse/explode/toggle status values will only be retained if the memo parameter is set true.

continue

The name of an optional continue field which, when set true, can force the branch to be followed.

delimiter

explode

The name of a variable, in the user's session, which will determine whether the tree should be "exploded". When exploded, all child items are followed and the full tree can be displayed.

Collapse/explode/toggle status values will only be retained if the memo parameter is set true.

file

full

Specifies that all items should be followed. This is essentially the same as specifying memo and passing the explode variable, but is not dependent upon them. Useful for building lists for inclusion in embedded Perl, among other things.

toggle

The name of a variable, in the user's session, which will determine whether the current item should be followed or not. The first time the toggle variable corresponding to its primary key is passed, the item will be "exploded". The next call will "collapse" the item.

collapse/explode/toggle status values will only be retained if the memo parameter is set true.

In addition to the above values, all valid options for a list tag are in force. For example, you can set a "selected" value on an option list with option=1, and the tag prefix with prefix etc.

level_field

log_error

When set to a true value, and an endless tree is detected (i.e. the child branch contains a parent), the error will be logged to the website's "error.log" file. No logging is performed by default.

memo

This parameter names a scratchpad variable where the persistent status values for the the collapse/explode/toggle feature should be stored.

multiple_start

object

outline

Sets outline mode, where mv_increment will be displayed with letter or numerical values. If set to specifically "1", it will produce outline increments like the following:

1
	A
	B
		1
		2
	C
		1
		2
			a
			b
				1
				2
					a
					b
2

pedantic

When set to a true value, and an endless tree is detected (i.e. the child branch contains a parent), the error will be logged to the website's "error.log" file, and the [tree] tag call will return with an error.

If pedantic is false (the default), the current leaf will be shown but never followed. This allows a partial display of the tree to be rendered.

show_error

When set to a true value, and an endless tree is detected (i.e. the child branch contains a parent), the error will be returned in the page. Errors are NOT shown by default.

sort

The column which should be used for ordering the items. This determines the order in which they will be displayed under the current parent.

spacer

spacing

start_item

The first item to be followed, i.e. the master value of all the top-level items.

stop

An optional stop field which which, when the value is true, can stop the following of the current branch.