4.82. tree

4.82.1. Summary

Parameters: table master subordinate start

The attribute hash reference is passed after the parameters but before the container text argument. This may mean that there are parameters not shown here.

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [tree] FOO [/tree]. Nesting: NO

Invalidates cache: no

Called Routine:

ASP-like Perl call:

    $Tag->tree(
        {
         table => VALUE,
         master => VALUE,
         subordinate => VALUE,
         start => VALUE,
        },
        BODY
    )

 OR

    $Tag->tree($table, $master, $subordinate, $start, $ATTRHASH, $BODY);

Attribute aliases

            sub ==> subordinate
    [tree table master subordinate start other_named_attributes]
Parameters Description Default
master   DEFAULT_VALUE
start   DEFAULT_VALUE
sub Alias for subordinate DEFAULT_VALUE
subordinate   DEFAULT_VALUE
table   DEFAULT_VALUE
Attributes Default
interpolate No
reparse Yes
Other_Characteristics  
Invalidates cache no
Container tag Yes
Has Subtags No
Nests No

Tag expansion example:

    [tree table master subordinate start]
---
    TODO: (tag result)

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.82.2. Description

Provides iterative list capability for binary trees. It produces hash-based rows use the same tags as [item-list]; sets some additional hash key entries to describe the tree and provide display control.

Works on a data set with the structure:

    parent  child
    99      a
    a       b
    a       c
    a       d
    a       x
    x       y
    x       z
    99      m
    99      n
    99      o
    o       e
    o       f
    o       g

Sets several keys which assist in walking and displaying the tree.

4.82.2.1. mv_level

Level of the item. If it is in the first level, it is 0. Sublevels are infinite (except for performance).

4.82.2.2. mv_increment

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

4.82.2.3. mv_children

If in autodetect mode, set to the number of children this branch has. If a leaf, set to 0.

4.82.2.4. mv_spacing

A multiple of level times the spacing option. Useful for setting width of spacer images.

The above sample data placed in a table named "tree" would produce:

    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

from the 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 '&nbsp' 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>

Accepts the following parameters:

4.82.2.5. table

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

4.82.2.6. master

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

4.82.2.7. subordinate

The child column, which determines which items are sub-items of the current one. Used to re-query for items with its value in master.

4.82.2.8. start_item

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

4.82.2.9. autodetect

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

4.82.2.10. full

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

4.82.2.11. stop

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

4.82.2.12. continue

An optional continue field which, when the value is true, can force the branch to be followed.

4.82.2.13. sort

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

4.82.2.14. outline

Sets outline mode, where mv_increment will be displayed with letter values or numeral values. If set to specifically 1, will produced outline increments like:

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

4.82.2.15. memo

Indicates that the collapse/explode/toggle features are to be used, and names a Scratch variable where the values should be stored.

4.82.2.16. collapse

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

Requires memo to be set if values are to be retained.

4.82.2.17. toggle

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

Requires memo to be set if values are to be retained.

4.82.2.18. explode

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

Requires memo to be set if values are to be retained.

4.82.2.19. pedantic

When set to a true value, and an endless tree is detected (i.e. the child branch contains a parent) then the error will be logged to the catalog error log and the tree call will return with an error.

If pedantic is not set (the default), the current leaf will be shown but never followed. This allows partial display of the tree.

4.82.2.20. log_error

When set to a true value, and an endless tree is detected (i.e. the child branch contains a parent) then the error will be logged to the catalog error log. No logging done by default.

4.82.2.21. show_error

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

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, set the tag prefix with prefix, etc.

4.82.2.22. master

4.82.2.23. start

4.82.2.24. subordinate

4.82.2.25. table