Tree Fields =========== General Syntax -------------- Each tree field is a function with a list of input fields. These fields can be either tree fields or data fields. To avoid ambiguities it is good practice to name tree fields starting with a capital letter and data fields with a lower case letter. A tree field is always defined as part of a tree (see previous chapter). The definition states the name, the field type, and the input parameters:: field "Name" field-type "type" own-fields [...] child-fields [...] sibling-fields [...] parent-fields [...] The field is started by the line ``field "Name"`` where "Name" is the name of the field. This will appear as the column heading in the tree list. After this, indented with four spaces, is the field type: ``field-type "type"``, where "type" is the type (see next for an overview). After this, the lines ``own-fields [...]``, ``child-fields [...]``, ``sibling-fields [...]``, and ``parent-fields [...]`` each define a list of field names. These are the input parameters for the function. They are evaluated in the order they are mentioned. A real-world example:: field "Progress" field-type "ratio-percent" own-fields ["Spent Hours", "Planned Hours"] child-fields [] sibling-fields [] parent-fields [] The tree field "Progress" is a ratio, defined as parameter1 / (parameter2 + parameter3 + ...). In the tree view it will be displayed as a percentage. It shows the ratio of the tree fields "Spent Hours" / "Planned Hours". concatenation ------------- Concatenates strings. Syntax:: field "Name" field-type "concatenation" own-fields ["field1", "field2", ...] child-fields ["field3", ...] sibling-fields [...] parent-fields [...] were "field1", "field2", "field3", ..., are the names of data or tree fields. Result: The strings found in *field1, field2, field3, ...*, put together, in the order they are mentioned. difference ---------- Difference of numbers. Syntax:: field "Name" field-type "difference" own-fields ["field1", "field2", ...] child-fields ["field3", ...] sibling-fields [...] parent-fields [...] were "field1", "field2", "field3", ..., are the names of data or tree fields. Result: The value *field1 - (field2 + field3 + ...)*, in the order they are mentioned. difference-time --------------- Same as "difference", but will show the result as hour format, e.g. the value *1.5* will be displayed and exported as *1:30:00*. mean ---- The statistical mean of all input fields. Syntax:: field "Name" field-type "mean" own-fields ["field1", "field2", ...] child-fields ["field3", ...] sibling-fields [...] parent-fields [...] were "field1", "field2", "field3", ..., are the names of data or tree fields. Result: The value *(field1 + field2 + field3 + ...) / N*, where *N* is the number of fields. mean-percent ------------ Same as "mean", but will show the result as a percentage, e.g. the value *0.75* will show as *75 %*. node-name --------- The name of the node's parent in another tree. Syntax:: field "Name" field-type "node-name" own-fields [] child-fields [] sibling-fields [] parent-fields [N] were *N* is an integer number. Result: Displays the name of the node's parent in tree *N*. Trees are counted starting with 0. Example: This field is called "Project" and is defined in a tree "Time", which is the first tree (i.e. Tree 0). There is another tree called "Projects", which is the third tree (i.e. Tree 2):: tree "Time" field "Project" field-type "node-name" own-fields [] child-fields [] sibling-fields [] parent-fields [2] tree "Tasks" ... tree "Projects" ... This would create the column "Project" in the tree view of the "Time" tree. The line ``parent-fields[2]`` means each entry shows the respective node's parent in the "Project" tree (e.g. "TreeTime"). node-path --------- Same as "node-name", but instead of the paren't name, the entire path is shown, using "\|" as delimiter (e.g. "Coding \| Open Source \| TreeTime"). ratio ----- The ratio between the first and the sum of all following input fields. Syntax:: field "Name" field-type "ratio" own-fields ["field1", "field2", ...] child-fields ["field3", ...] sibling-fields [...] parent-fields [...] were "field1", "field2", "field3", ..., are the names of data or tree fields. Result: The value *field1 / (field2 + field3 + ...)*, where *N* is the number of fields. ratio-percent ------------- Same as "ratio", but displayed as percentage (e.g., 0.75 is displayed as 75 %). set --- A list of unique occurrences of values of all input fields. Syntax:: field "Name" field-type "set" own-fields ["field1", "field2", ...] child-fields ["field3", ...] sibling-fields [...] parent-fields [...] were "field1", "field2", "field3", ..., are the names of data or tree fields. Result: A list like *value1, value2, value3, value4*, where each value is the value of at least on input field and each value is listed only once. string ------ The simple display of the content of a data field or another tree field. Syntax:: field "Name" field-type "string" own-fields ["field1"] child-fields [] sibling-fields [] parent-fields [] were "field1" is the name of a current data or tree field. The "string" function only takes one parameter. Result: The value of *field1*. sum --- The sum of all input fields. Syntax:: field "Name" field-type "sum" own-fields ["field1", "field2", ...] child-fields ["field3", ...] sibling-fields [...] parent-fields [...] were "field1", "field2", "field3", ..., are the names of data or tree fields. Fields must be integer fields, the result for string fields is not defined. Result: The value *field1 + field2 + field3 + ...*. sum-time -------- Same as "sum", but will show the result as hour format, e.g. the value *1.5* will be displayed and exported as *1:30:00*. text ---- Same as "string", but the exported field has a larger width and can span several lines. url --- Same as "string", but in an html export the field is formated as url link (clickable).