treehouze
v0.0.1
Published
Graph utilities for handling and housing markdown wikis -- and (semantic) trees!
Downloads
3
Maintainers
manunamzReadme
treehouze
Treehouze is a single graph instance that may be translated between 2D, 3D, VR, and AR representations without any changes to its shape or structure.
It's designed to be as general-purpose as possible, but was built with [[wikirefs]] and semantic trees structures in mind with the aim of facilitating tangible digital memory palaces.
🏡 Build and maintain a treehouze to play in in your WikiBonsai digital garden.
Install
Install with npm:
npm install treehouzeOr use a script tag:
<script type="module" src="treehouze.min.js"></script>Use
Add 2 div elements to your html -- one for the graph itself and another for the element that wraps it (this is for selecting multiple nodes to work)
<!DOCTYPE html>
<head>
<!-- ... -->
</head>
<body>
<div id="graph-view">
<div id="graph"></div>
</div>
</body>
</html>import { TreeHouze } from 'treehouze';
// get graph's html elements
let elementWrap = document.getElementById('graph-view');
let elementGraph = document.getElementById('graph');
// create graph instance
let graph = new TreeHouze(elementWrap, elementGraph, opts);
// set options
let opts = {
nodestate: (node) => return node.state,
// some defaults listed below
ctrls: { enabled: true },
nodekinds: {
'doc': '#3e5c50',
'template': '#F8F0E3',
'zombie': '#00000000',
},
nodetypes: {
'default': "#31AF31",
}
};
// create data payload
let data = {
'nodes': [
{
id: '12345', // used for linking nodes
label: 'label-txt', // used to label nodes
kind: 'nodekind', // used to colorize nodes and for filtering
type: 'nodetype', // used to colorize nodes
state: 0, // used to calculate glow strength ('ctx.shadowBlur')
},
// ...
],
'links': [
{
kind: 'linkkind', // used for filtering
source: '12345', // should be a node id
target: '67890', // should be a node id
},
// ...
],
};
// draw graph
graph.draw(data, opts);API
data
Graph data -- should contain nodes and links:
nodes
{
"id": "12345", // used for linking nodes
"label": "label-txt", // used to label nodes
"kind": "nodekind", // used to colorize nodes and for filtering
"type": "nodetype", // used to colorize nodes
"state": 0, // used to calculate glow strength ('ctx.shadowBlur')
// (web-only)
"neighbors": { // used to highlight neighboring nodes
"nodes": [], // array of neighbor node ids
"links": [], // array of neighbor links
},
// (tree-only)
"lineage": { // used to highlight lineage nodes
"nodes": [], // array of lineage node ids
"links": [], // array of lineage links
},
},links
{
"kind": "linkkind", // used for filtering
"source": "12345", // should be a node id
"target": "6789", // should be a node id
},draw([data][, opts])
Draw the graph from the given data. If redrawing the graph, data may be empty. opts may be used to reset any graph options.
Options
centerSpeed: number
Speed at which to center nodes (3D-only).
Default is 1000.
colors: { string: string }
Hash of graph object names to color hexes.
Defaults:
{
// graph
"background": "#000011",
// node
"text" : "#e6e1e8", // node labels
"band" : "#44434d", // node band
"current" : "#F0C61F", // 'current node'
// link
"link" : "#44434d",
"particle" : "#959396", // link particles
}current(node): boolean
A function that should return if a given node is the 'current' node. The current node will glow a specific color, to distinguish it from its type.
Default is:
(node) => { return false; }dagHeight: number
A number value to set the height of each level in the tree graph.
Default is 100.
nodekinds: { string: string }
A record that maps nodekind name strings to hex color strings; value can be a string or a function that returns a string.
Defaults are:
{
"doc" : "#3e5c50",
"template": "#F8F0E3",
"zombie" : "#959DA5",
}nodetypes: { string: string }
A record that maps nodetype name strings to hex color strings; value can be a string or a function that returns a string.
Default is:
{
"default": "#3e5c50"
}ctrls
Options for graph controls.
All boolean ctrls default to true.
ctrls.autosync: boolean
Set auto-sync to on/off.
ctrls.click: boolean
Set default node clickability to on/off.
ctrls.dim: '2d' | '3d' | 'vr' | 'ar'
What dimension to render the graph in. Can be: 2d, 3d, vr, or ar (See DimEnum for details).
Default is 2d.
ctrls.drag: boolean
Set default node draggability to on/off.
ctrls.enabled: boolean
Enable or disable graph controls.
ctrls.exclude: string[]
Which controls to exclude. Can be: kind, dim, filter, fix, flip, follow, glow, autosync, click, drag, hover, save, sync, data. (See CtrlEnum for details).
Default is an empty array.
ctrls.filter: { nodes: }
An object with nodes and links keys that point to arrays of string values from doc, template, and zombie (see NodeKindEnum) and fam for the tree graph and attr, link, embed for the web graph (see LinkKindEnum).
ctrls.fix: boolean
Set default of fixed (sticky) nodes (as opposed to force (free-floating)) to on/off.
ctrls.follow: boolean
Set default of active node following to on/off.
ctrls.hover: boolean
Set default node hoverability to on/off.
ctrls.glow: boolean
Set default glow to on/off.
ctrls.kind: 'tree' | 'web'
Which kind of graph to draw. Can be: 'tree' or 'web' (can access via GraphKindEnum for details).
Default is web.
Overridable Methods
The following methods provide default behavior for interacting with the graph. They may be overriden by subclassing the graph and provding your own implementation and/or calling super.<method>().
Graph Actions
onClickNode(node, event)
Centers the node in the graph. If shift is also pressed, then the node is added to selectedNodes.
onDragNode(node, translate)
Drags node along cursor path.
onDragEndNode(node)
Ends dragging a node. The node will stay in place if fix is set to `true.
onHoverNode(node, prevNode)
Highlights the hovered node and either its neighbors in the web graph or its lineage in the tree graph. All links connecting these nodes will highlight.
onHoverLink(link)
Highlights the hovered link and the two nodes it connects to.
onSelectStart(evt)
Begin box selection of multiple nodes.
onSelect(evt)
Selecting multiple nodes via box selection.
onSelectEnd(evt)
End selecting multiple nodes via box selection.
Graph Properties
autosync(data)
Redraws the graph from the given data. This method is unused internally and is meant for auto-syncing with whatever system is managing this graph instance.
save()
Returns the internal dataCache.
This method is recommended to be overriden: It is useful for saving the graph data. It is called when the user clicks the save data button.
sync()
Redraws the graph from the internal dataCache.
This method is recommended to be overriden: It is useful for syncing the graph data between some other source and itself. It is called when the user clicks the sync button and is meant for auto-sync-ing if implemented downstream.
force-graph
As a sidenote, this project showcases a unified instance of @vasturiano's force-graph libraries (2D, 3D, VR, AR).