|
BEE Script: dbtree dbobj [root=string] [self=string] [parent=string]
[maxlevels=num] [maxnodes=num] [withroot=bool];
BEE Tag: <beedbtree dbobj [root=string] [self=string] [parent=string]
[maxlevels=num] [maxnodes=num] [withroot=bool]>
The "dbtree" command does not generate any output. It only generates an internal structure for the specified database object. This structure can only be accessed via a foreach loop of type "dbtree".
A dbtree is a non-circular tree structure converted from a database query result. The typical use of a dbtree is in a site-map style hierarchical menu. The minimum implementation is a VirtualBase table with two fields: Self and Parent. "Self" is a unique identifier of the menu item and "Parent" is the upper level menu the item belongs to, which must exist as a "Self" node in another item. It is like a file system directory structure.
In this context, we follow the common convention in describing "node", "parent", "child", "sibling", "leaf" and "root". (See Terminology for more details).
Each record in the record set corresponds to a node in the dbtree. The node record has at least one unique key field (of which the name is specified in the "self" parameter) and a parent pointer field (of which the name is specified in the "parent" parameter.) Circular relations will be detected and removed.
The root node does not necessarily exist as a record (virtual root), but the sibling relation for all children nodes having the same parent pointer still holds.
A record set may contains several roots (or virtual roots), each holds a disjoint dbtree in the same record set. In this case, you may specify root="..." to indicate a sub-dbtree formed by all siblings of that parent.
The root will not be included in the dbtree result unless withroot="1". If the root does not exist in the record set but withroot="1", a faked root node will be generated in the dbtree result (not in the record set). The faked root (if there's one) has only the "self" field containing the virtual root pointer and the "parent" field being null.
Example:
In the following example, "indent" is a variable containing spaces and the "lead" strings are the symbols you display before the node to indicate its type. e.g. ">" (or >) implies a non-opened parent etc.
Please note that the "lead" variable is indexed by a two digit number, the first one being the "activeness" and the second one "isparent". There're 4 possible values for "activeness" (0, 1, 2 and 3) and 2 possible values for "isparent". Zero "activeness" should not be shown. So you can specify 6 different symbols.
(For the sake of an example, the "self" node is the "Code" field in the table, and the "parent" node is the "Parent" field in the table, which is the default.)
var indent = ". ";
var "lead" = "(array)10=>o, 11=>>, 21=>v,
30=><font color=#ff0080>o</font>,
31=><font color=#ff0080>v</font>";
database "db" query="select * from Menu";
dbtree "db" self="Code" active="form%pagecode";
foreach ((dbtree)db as node)
{
if ({result%node:activeness} == 0) continue;
display "{indent|repeat:{result%node:level}}";
display
"{leadchar:{result%node:activeness}{result%node:isparent}}";
var href = "{sys%url:page}?pagecode={node:Code}";
display '<a href="{href}">{node:Name}';
display ' ({node:Description})</a><br>';
}
Terminology:
Every "node" in the tree can have zero or more "children" nodes, which in turn may have their own children nodes. Children nodes with the same parent node are called "sibling" nodes of each other. Nodes with no children nodes are called "leaf" nodes; nodes with children nodes are called "parent" nodes; the node with no "parent" node are called the "root" node (usually unique in a tree).
Parameters
root specifies the root node that the dbree is built under. The default is blank.
active indicates the active node in the dbtree. By specifying the "active" parameter, you assign an activeness value to each node "related" to the active one in the following scheme:
|
3 |
CURRENT: The active node itself |
|
2 |
OPEN: An active parent, i.e. a parent of the active node or a parent of another active parent. All the active parents form a path from the root to the active node. |
|
1 |
CLOSE: An active sibling, i.e. a sibling of the active node or an active parent. All the active siblings form an active tree that resumbles a function menu hierarchy. |
|
0 |
None of the above. (Nodes with zero activeness should not be shown.) If "active" is blank, the activeness of all nodes will be set to 0. |
self specifies the name of the field which contains the unique key of the node. The default is "Self".
parent specifies the name of the field which contains the parent pointer of the node. The default is "Parent".
maxlevels specifies the maximum number of levels the process will go down to. This restriction is introduced to avoid endless looping in ever deeper search for more levels due to a fault in the record set. The default is 10.
maxnodes specifies the maximum number of nodes the process will take from the database. This restriction is introduced to avoid resource draining problem with a huge record set. The default is 1000.
withroot indicates whether to include the root into the dbtree. To include the root, please enter "yes", "on", "true", or a positive number. If the root does not exist in the record set (virtual root), a faked dbtree node will be generated. To exclude the root (the default case), please enter "no", "off", "false", or 0.
After calling the function, the following BEE Variables are made available:
|
status%database |
Error code of the dbtree operation, or 0 if successful |
|
message%database |
Error message of the dbtree operation, or blank if successful |
The followings are available only in the "foreach ((dbtree)... as var) { ... }" loop:
|
result%var:activeness |
The "activeness" value of the current node. (Please see the "active" parameter.) |
|
result%var:isparent |
0 if the current node is a leaf node.
1 if the current node is a parent node. |
|
result%var:level |
The number of active parents inclusively between itself and the root. If "withroot" is 1, the root is at level 0 and all its children nodes are at level 1; if "withroot" is 0, there is no root, and all top level nodes are at level 0. In another word, you always have level 0 in a dbtree. |
|