 |
jMaki Tree Model Specification
Main data model page
(1) Introduction
The tree data model represtens all the common acctions that can occur with tree widgets.
(1.2) Examples
The model for a tree widget like this:
{
tree: {
label : 'Yahoo Tree Root Node',
expanded : true,
children : [
{ label : 'Node 1.1'},
{ label : 'Node 1.2',
'children : [
{ label : 'Node 3.1',
action : { message : { targetId : 'bar'}}
}
]
}
]
}
}
(2) Data Model
The value property of a tree widget, no matter how it is created, must be a well formed JSON value that conforms to the following BNF description:
tree ::= "{" <label> [ <expanded> ] [ ( <action> | <children> ) ] "}"
label ::= "'label'" ":" <string>
expanded ::= "'expanded'" ":" ( true | false )
action ::= "action:" "{" [<topic>] [<message> ] "},"
topic ::= "topic:" <string>,
message ::= "message:" <obj>
obj ::= <string> | <JavaScript object literal>
children ::= "'children'" ":" "[" <tree> ... "]"
JSON schema format is:
{
"description" : "jMaki Tree",
"type":"object",
"properties": {
"tree" : {
"type" : "object",
"properties" : {
"id" : {"type": "string", "optional":true},
"label" : {"type": "string"},
"expanded" : {"type": "boolean","optional":true, "default":true},
"action" : {"type" : "object","optional":true,
"properties": {
"topic": {"type" : "string", "optional" : true},
"message": {"type" : "string", "optional" : true}
}
}
},
"children" : {"type" : "object",
"properties": {
"id" : {"type": "string", "optional":true},
"label" : {"type": "string"},
"expanded" : {"type": "boolean","optional":true, "default":true},
"action" : {"type" : "object","optional":true,
"properties": {
"topic": {"type" : "string", "optional" : true},
"message": {"type" : ["string","object"],, "optional" : true}
}
}
}
} // children
}
}
}
(2.1) Property Descriptions
The tree element represents an individual node in the underlying tree data structure. The outermost tree element identifies the single root node of the tree.
As you will see below, the children element allows nodes to be nested to an arbitrary level. Note that there are no restrictions on the order of subordinate elements.
The label element defines the text that will be displayed for this particular node. This element is required.
The expanded element declares whether the children underneath this node will be initially visible or not. If not included, this element defaults to true for the top
level node in the tree, and defaults to false for subordinate nodes.
The action element defines the required behavior if the user clicks on this node at runtime. If this element is present, a click on this node will cause an event to be published to the topic specified using the publish property of the widget or to the topic specified as a property of the publish object. If not present, and if this node has children, the expanded state of this node will be toggled (dynamic change on the client side only). If not present,
and this node does not have children, only the event behavior described below will occur.
The children element contains an array of tree subelements that represent the child nodes underneath this node. If not present, this node will have no children.
It is not legal to have both an action element and a children element on the same node.
(3) Events
(2.1) Subscribe Events
The tree widgets supporting the event model all have the following handlers accessible through the action property. Below is the list of handlers and the expected payload described in this model. You will also find examples on usage. Coomands occur on the widget so they are a way to manipulate the widget itself.
| Commands | Payload (object literal) |
| addNodes | {targetId: <string> , value: tree} |
| collapseNode | {targetId , <string>} |
| expandNode | {targetId , <string>} |
| removeNode | { targetId , <string>} |
| removeChildren | {targetId , <string>} |
| collapseAll | |
| expandAll | |
Events are based on the following value:
{
root : {
title : 'Default Tree Root Node',
expanded : true,
id : 'root',
children : [
{
label : 'Node 1.0',
id : 'bar',
},
{
label : 'Node 1.1',
id : 'node 1.1',
children : [
{ label : 'Node 1.1.1'}
],
action : {
message : ''
}
},
{
label : 'Node 1.2',
id : 'node_1_2',
children : [
{
label : 'Node 3.1',
id : 'foo',
children : [
{label : 'Last Leaf'}
]
}
]
}
]
}
}
Here is some glue code for that uses Yahoo buttons to fire the events.
Remove Node:
jmaki.publish("/dojo/tree/removeNode", {tartgetId : 'bar'});
All nodes including the node with nodeId will be removed.
jmaki.publish("/dojo/tree/removeChildren", {targetId : 'bar'});
Removes all children under a given node with targetId.
jmaki.publish("/dojo/tree/expandNode", {tartgetId : 'root'});
Expands the node with nodeId and all parent nodes so it will become visible.
jmaki.publish("/dojo/tree/collapseNode", {targetId : 'root'});
Add Nodes:
var node = {
label : 'Graft',
expanded : true,
children : [
{label : 'Graft .1'},
{label : 'Graft .2'}
]
};
jmaki.publish("/dojo/tree/addNodes", {targetId : 'foo', value : node});
Adds a graft or sub-tree of nodes under the node with targetId.
(2.1) Publish Events
Following are the events published by a tree.
| Event type | Payload (object literal) | Event |
| onClick | { widgetId : widget id, type : 'onClick', targetId: <tree>}] | When the user clicks on a leaf node that does not have an action assoicated to it. |
| onCollapse | { widgetId : widget id, type : 'onCollapse', targetId : <targetId>} | When a user collapses a node. |
| onExpand | { widgetId : widget id, type : 'onExpand', targetId : <targetId>} | When a user expands a node |
In each case the the Event type is appended to topic when the event is published.
In the case of a widget with "publish" set to "/dojo/tree" a "onClick" event will be published to "/dojo/tree/onClick".
Last modified by :
-- Main.gmurray71 - 22 July 2007
|