Using Phyloviewer GWT client library

Phyloviewer's GWT client library can be used to add a tree viewer to larger GWT based applications. This document shows the api of the viewer.

Adding viewer to another widget.

The class DetailView provides a pan and zoom viewer with auto-collapsing of interior nodes. To add the viewer to a panel:

Creating a DetailView

DetailView view = new DetailView(800,600);
panel.add(view);

Adding tree data to view

The DetailView class needs an IDocument object to hold the tree data. A document object can be constructed using a json string for the tree data and for the layout. The layout data can be generated using a service (documentation coming). To create a document:

Creating a document

ITree tree = (JsTree) JsonUtils.safeEval(jsonTreeString);
ILayoutData layout = (JsLayoutCladogram) JsonUtils.safeEval(jsonLayoutString);
Document document = new Document();
document.setTree(tree);
document.setLayoutData(layout);

view.setDocument(document);

JSON format

Tree object

Property	Description
id	unique id for the tree
root	node object for the root of the tree

Node object

Property	Optional	Description
id	No	Unique id for this node. Ids do not need to be sequential, but need to be an integer
name	Yes	The name of the node
children	No	An array of the nodes children. If there are no children, the viewer expects a non null empty array
branchLength	Yes	Distance to the parent node
metadata	Yes	Custom defined metadata object. The metadata object will be passed in the event json (see below)

For example, the json for the Newick tree '(a:1,(ab:1,ac:2):2);' is:

{
    "id": 0,
    "root": {
        "id": 0,
        "children": [
            {
                "id": 1,
                "name": "a",
                "children": [],
                "branchLength": 1
            },
            {
                "id": 2,
                "children": [
                    {
                        "id": 3,
                        "name": "ab",
                        "children": [],
                        "branchLength": 1
                    },
                    {
                        "id": 4,
                        "name": "ac",
                        "children": [],
                        "branchLength": 2
                    }
                ],
                "branchLength": 2
            }
        ]
    }
}

Adding styling markup to viewer

The viewer using an IStyleMap object to provide mappings between nodes and the visual elements to use when drawing.

Creating a StyleMap

IStyleMap styleMap = (JsStyleMap) JsonUtils.safeEval(jsonStyleMapString);
view.setStyleMap(styleMap);

JSON format

Style map

Property	Optional	Description
styles	yes	An object where the names are the id of the style and the value is a style object
nodeStyleMappings	yes	An object where the names are the node id and the value is the style name
nameStyleMappings	yes	An object where the names are the node name and the value is the style name. Note that nodeStyleMappings will override nameStyleMappings when both appear.
branchDecorations	yes	An object where the names are the node id and the value is what to decorate the branch with (only triangles are implemented as of now)

Style object

Property	Description
id	Id of this style
branchStyle	BranchStyle object
glyphStyle	GlyphStyle object
labelStyle	LabelStyle object
nodeStyle	NodeStyle object

BranchStyle object

Property	Description
strokeColor	HTML color string for line
lineWidth	Width in pixels for line

GlyphStyle object

Property	Description
strokeColor	HTML color string for outline
fillColor	HTML color string for shape fill
lineWidth	Width of outline

LabelStyle object

Property	Description
color	HTML color string

NodeStyle Object

Property	Description
color	HTML color string
pointSize	Size in pixels of shape
nodeShape	Shape of node. Values of circle and square are currently implemented

Example Style Map Object

{
    "styles": {
        "style-one" : {
            "id" : "style-one",
            "nodeStyle" : {
                "color" : "#ff0000",
                "pointSize" : 3,
                "nodeShape": "circle"
            },
            "labelStyle" : {
                "color" : "#000000"
            },
            "branchStyle" : {
                "strokeColor" : "#000000",
                "lineWidth" : 1
            },
            "glyphStyle" : {
                "fillColor" : "#000000",
                "strokeColor" : "#000000",
                "lineWidth" : 1
            }
        },
        "style-two" : {
            "id" : "style-two",
            "nodeStyle" : {
                "color" : "#0000ff",
                "pointSize" : 10,
                "nodeShape": "square"
            },
            "labelStyle" : {
                "color" : "#000000"
            },
            "branchStyle" : {
                "strokeColor" : "#000000",
                "lineWidth" : 1
            },
            "glyphStyle" : {
                "fillColor" : "#000000",
                "strokeColor" : "#000000",
                "lineWidth" : 1
            }
        }
    },
    "nodeStyleMappings": {
        "1": "style-one",
        "2": "style-two",
        "5": "style-one"
    },
    "nameStyleMappings": {
        "a": "style-two",
        "ab": "style-two"
    },
    "branchDecorations": {
        "1": "triangle",
        "3": "triangle"
    }
}

Listening for mouse events

The viewer provides mouse over, mouse out, and mouse clicked events for the line, node, and label items. The viewer sends the events as json strings. In order to receive the events, create an instance of BroadcastCommand (in package org.iplantc.core.broadcaster.shared) and give the object to the viewer.

Setting A BroadcastCommand Object

view.setBroadcastCommand(new BroadcastCommand()
{
	@Override
	public void broadcast(String jsonMsg)
	{
           // Use jsonMsg here
	}
});

The fields of the json string are:

Field	Description
event	Event name
id	Node id corresponding to the event
mouse	Object containing absolute x and y position of the mouse
metadata	The metadata object in the node (may be empty)

Example Event JSON

{
    "event": "node_clicked",
    "id": "42",
    "mouse": {
        "x": 156,
        "y": 324
    },
    "metadata": {

    }
}

Possible events are:

node_clicked
leaf_clicked
branch_clicked
label_clicked

node_mouse_over
leaf_mouse_over
branch_mouse_over
label_mouse_over

mode_mouse_out
leaf_mouse_out
branch_mouse_out
label_mouse_out