Tree definition

From Dreamtsoft Wiki
Jump to: navigation, search
  Note: This document is for features available in v0.6+.  Documentation for v0.5 is available here

The Bucket Tree component is used to display related records in a tree hierarchy. To do this, the structure of the tree must be specified in the Bucket Tree Component's Tree Definition.

The Bucket Tree component requires a Bucket to be specified as the starting point for the tree. After that, the Tree Definition is used to specify how the tree is to be built.

Tree Definition

The Tree Definition is an array of JSON objects used to indicate what goes into the tree.

Here is an example of a Tree Definition with the resulting display. It assumes that the Bucket for this tree is Bundle and shows the Browser Actions and Script Mappers for each installed Bundle:

  {
     "tree": [{
        "type": "bucket",
        "label": "%{$record.title} (%{$record.id})",
        "open": true,
        "condition": "",
        "sort_by": "id",
        "children": [{ 
           "type": "related",
           "bucket_node": true,
           "async": true,
           "child": "action_browser.bundle",
           "condition": "",
           "children": []
        }, {
        "type": "related",
        "bucket_node": true,
        "async": true,
        "child": "script_mapper.bundle",
        "condition": "",
        "children": []
        }]
     }],
     "tags": {
        "folder": {
           "bucket": "bundle_content",
           "condition": ["type","eq","folder"],
           "icon": "fontawesome:folder-o",
           "drag": true,
           "drop": ["folder","system"]
        },
        "file": {
           "bucket": "bundle_content",
           "condition": ["type","eq","file"],
           "icon": "fontawesome:file-o",
           "drag": true,
           "drop": ["folder","system"]
        },
        "locked": {
           "bucket": "bundle_content",
           "condition": ["type","eq","locked"],
           "icon": "fontawesome:lock"
        },
        "system": {
           "bucket": "bundle_content",
           "condition": ["type","eq","system"],
           "icon": "fontawesome:folder"
        }
     }
  }   

This results in something like this:

Tree.png

JSON Object Properties

Tree nodes are defined using a JSON object. The Tree Definition contains an array of JSON objects that are displayed in the tree as siblings. In addition, each JSON object contains a children array of objects that are used to define the child tree nodes for the JSON object.

type

The type property identifies the type of tree node being specified. It contains one of the following values:

label
Display a static label for the tree node
bucket
Display the tree nodes for each of the matching records for the Bucket specified for the Bucket Tree Component. This is really the starting point for generating the dynamic tree nodes.
related
Display records that are related to the parent of this node

Common properties

These properties are available for all nodes, regardless of the type.


label

The label for the node with replacements. This property is required for label type nodes. If it is not specified for bucket | related nodes, the display value for the record is used as the Tree node label.

For replacements, use %{$record.SLOT_NAME} in the label.

For HTML usage in the label, see the html attribute in the tags section

page

If specified, this property will control what page is navigated to when the node is clicked. The value may be:

blank string (ie, '')
The node is not clickable
string
The page URL to navigate to when the node is clicked. The string may contain the following replacements:
$parent
The parent record for this node. The values for the parent record may be referenced using $parent.SLOT_NAME
$bucket
Name of the bucket associated with this node
$slot
The slot used to get this node's data using the #child
$record
The record for this node. The values for the record may be referenced using $record.SLOT_NAME
$view
The current view being displayed, if there is one
If the page property is not specified, then a default page is used:
For bucket nodes
list.default.BUCKET_NAME
For nodes representing records
details.default.BUCKET_NAME?q=["id", "eq", "ID_OF_RECORD"]


children

This is an array of child nodes to be generated as children of the current node.


open

Indicates if the node should be initially displayed opened (ie, expanded). The default is false. The value of this property may be:

true
display node initially open
false
display node initially closed
condition_string|condition_array
the condition is used to match against the node's record. If the record matches the condition, the node is initially displayed as open (the condition may be specified as a json array or a json array specified as a string)


async

Indicates if the children for the node are loaded asynchronously when the user expands the node. At that point, an ajax call is made to the server to get the child nodes. The default is false.

true
load the child nodes when the user expands the node
false
load the child nodes when initially building the tree
condition_string|condition_array
the condition is used to match against the node's record. If the record matches the condition, the node is loaded when the user expands the node. (the condition may be specified as a json array or a json array specified as a string)

no_children

Indicates if there are no children for this node so that the +/- icons can be hidden for this node. This is not required, but is used as a hint indicating there are no children for this node. If a node has no children when an attempt to load child nodes (when this property is false) the +/- icons will be hidden at that time. This property is used to optimize the loading of the tree when it is know beforehandl that there will be no children for a node.

true
there are no children for this node
false
it is not known if there are children for this node
condition_string|condition_array
the condition is used to match against the node's record. If the record matches the condition, there are no children for this node. (the condition may be specified as a json array or a json array specified as a string)

tag

Indicates the tag for the node and is used to override the tags definitions. See #Tags for more information on using tags.


type="bucket"

Type of "bucket" is used to display the records for the Bucket Tree component Bucket. The following JSON object properties are used to control how the records are displayed.

bucket_node

If true, a tree node is created that contains the Label for the Bucket and all of the bucket records are displayed as tree nodes below it. If false (which is the default), a Label node is not created.

bucket_node_icon

Used to override the icon to use for the bucket node when the bucket_node property is true.

condition

If specified, this condition is used to limit the Bucket records that are displayed.

sort_by

By default, the Bucket record tree nodes are sorted alphabetically by the Display Value of each record. This property may be used to specify a different slot to use for sorting of the nodes.

sort_desc

By default, sorting is done ascending. Setting this property to true does the sorting descending by the "sort_by" slot.


type="related"

Type of "related" is used to display records related to the parent record. The following JSON object properties are used to control how the records are displayed.

bucket_node

If true, a tree node is created that contains the Label for the Bucket and all of the bucket records are displayed as tree nodes below it. If false (which is the default), a Label node is not created.

bucket_node_icon

Used to override the icon to use for the bucket node when the bucket_node property is true.

child

This required property is used to specify the related records to be displayed. The value is "bucket.slot" and is used to identify the bucket for the related records and the slot that contains the reference to the parent record. For example, if the parent is the "Bundle" bucket, the following child property would show the Script Mappers for the Bundle:

  "script_mapper.bundle"

condition

If specified, this condition is used to limit the related records that are displayed. For example, if only Active records are to be displayed:

  ['active', 'eq', 'true']

sort_by

By default, the related record tree nodes are sorted alphabetically by the Display Value of each record. This property may be used to specify a different slot to use for sorting of the nodes.

sort_desc

By default, sorting is done ascending. Setting this property to true does the sorting descending by the "sort_by" slot.

recurse

If true, child nodes are created for the current node using the same child definition. This allows trees to be built from records that are self-refering, such as a record that contains a parent slot that points back to itself.

true
child nodes are created by recursing
false
recursion is not performed
condition_string|condition_array
the condition is used to match against the node's record. If the record matches the condition, child nodes are created by recursing. (the condition may be specified as a json array or a json array specified as a string)


type="label"

Type of "label" is used to display arbitrary items in the tree that aren't part of the tree and/or don't have records associated with them. This is generally used to put "top nodes" on the tree like "All groups" or "User list" that act more like navigators than tree nodes. The following JSON object properties are used to control how the records are displayed.

Example
[{ "type": "label",
  "label": "All locations",
  "page": "list.default.location",
  "open": true,
  "children": []
}]

label

The text displayed in your tree node


Tags

Tags are used to classify a group of nodes so that they can be assigned certain properties, such as an icon. Tags are also used to indicate which nodes can be dropped on other nodes. When dragging a draggable node, it can only be dropped on nodes that have the same tag as one of the entries in the drop array.

To define tags, use the tags property. Each object in the tags property contains a bucket and condition value that is used to match a node and assign the node a tag. A tree definition may also specify a tag property to override the tags definition (see #tag above).

The tags object contains the following properties:

bucket

The bucket that this tag is associated with

condition

The condition used to match this tag against a node

icon

Indicates the icon to be displayed for the node. If not specified, the default folder icon is used.

drag

Indicates if the node can be dragged and then dropped on on other nodes. The default is false. The value of this property may be:

true
the node may be dragged
false
the node is not draggable
condition_string|condition_array
the condition is used to match against the node's record. If the record matches the condition, the node is draggable (the condition may be specified as a json array or a json array specified as a string)

drop

Indicates which nodes this node may be dropped onto. The default is []. The value of this property may be:

array_string|array
An array of tags that indicate the nodes that this node may be dropped onto.

Note: when a node is dropped, the Tree Action with a type of Drag and Drop and a matching bucket name is executed to handle any actions required for moving the dropped node. See Drag and Drop Actions for more details.

html

Available in 1.0+

Specifies the node title in HTML. May specify a template with substitutions including the variable $record.

Example
"tags": {
     "folder": {
        "html": "<strong>%{$record.name}</strong>",
        "bucket": "bundle_content",
        "condition": ["type","eq","folder"],
     }
}

Actions

Actions can be attached to nodes in the tree using Tree Actions. To create new tree actions, click the gears icon in the upper right of the screen and select Actions. When the + button is clicked, select Tree Action and a new Tree Action can be created.

Currently, Tree Actions are assigned to Buckets and any tree that displays a node from that bucket will have the action available. In the future, actions will be defined with the tree so that the actions are associated with the tree page, not with the bucket, however, this support is not currently available. All actions are accessed as right-click menu tree actions.

TreeAction.png

Drag and Drop Actions

Drag and drop actions are used to handle what happens when a node is dropped on another node. When the drop occurs, the first matching Tree Action with a type of Drag and Drop and a bucket name that matches the bucket of the dropped node is executed. When the action is executed, $record refers to the node that was dragged and dropped. In addition, $flow.dnd is used to provide information about the drop action and may be used in the Action Flow activities, such as Run Script, in order to update the node to reflect the drop location:

  $flow.dnd
     .oldParent           // old parent before the drag started
        ._bucketName      //    bucket name of the parent node we dragged from
        ._bucketId        //    id of the parent node we dragged from
        ._bucketLabel     //    bucket label of the parent node we dragged from
        ._bucketLabelP    //    bucket label (plural) of the parent node we dragged from
        ._tag             //    tag of the parent node we dragged from
  
     .oldPosition         // position (0-based index) of the node in the parent we dragged from
  
     .parent              // parent we dropped onto
        ._bucketName      //    bucket name of the parent node we dropped on
        ._bucketId        //    id of the parent node we dropped on
        ._bucketLabel     //    bucket label of the parent node we dropped on
        ._bucketLabelP    //    bucket label (plural) of the parent node we dropped on
        ._tag             //    tag of the parent node we dropped on
  
     .position            // position (0-based index) of the node in the parent where we dropped
  
     .after               // information about the node that we want to insert the node after (ie, where we dropped the node within the parent)
        ._bucketName      //    undefined if dropped as the first node of the parent (ie, we are not after any of the sibling nodes)
        ._bucketId        //    otherwise, contains ._bucketName and ._bucketId to indicate the node to be inserted after