Skip to content

deitch/jstree-model-back

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

28 Commits
 
 
 
 
 
 
 
 

Repository files navigation

Plugin for the jstree www.jstree.com tree component that uses a model backing, rather than fixed data.

Provides greater flexibility, in allowing all, none or some of the data to be loaded at once,
and can even dynamically change the data as needed.

Note: Significant API changes in what a model looks like in v0.9 onwards, moving to v1.0. Please read documentation carefully.

Usage:
1) Include jquery and jstree in your page, as usual
2) Include jstreemodel.js
<script src="/path/to/jstreemodel.js"></script>

3) Include tree_model as a plugin
$("div#id").jstree({
..
	plugins: ["core","ui",...,"tree_model"],
..
})

4) Include relevant parameters. 
$("div#id").jstree({
..
	plugins: ["core","ui",...,"tree_model"],
	tree_model: {
		data: function(){return(rootObject);},
		progressive_render: true/false,
		progressive_unload: true/false,
		id_prefix: string,
		type_attr: string
	} 
..
});

The options are as follows:
- progressive_render: true or false, default false. If true, will not load children of the current node until the parent node is opened in the tree.
- progressive_unload: true or false, default false. If true, when a node is closed, will unload all of the children from DOM and data
- data: the root object of the tree. Must match the required interface for a treeNode (see below). The root will never be rendered, only its children.
- id_prefix: a prefix to prepend to the id parameter of the object, if relevant.
- type_attr: the name to give to the type attribute, if getType() is available and returns non-null. Used primarily for the types plugin.


Node Interface:
Every node must have the following functions available on it:
- getName(): returns either a string to use as the name for the node, or an object, per the jstree spec
- getAttr(): returns an object of attributes to add to the LI object
- getProps(): returns an object with attributes that are relevant to jstree, e.g. metadata, state, etc.
- openNode(cb,user): allows the tree to tell the model when the node has been opened. When openNode is complete, it should execute cb() to indicate completion, which is usually used to change class to show loading complete. The parameter "user" will tell the node if this openNode() was called because a user actually executed something (usually a click), or an API (true for both of those cases), or if it is because jsTreeModel opened a node that was loaded via addChildren.jstree, which itself was open (false).
- closeNode(): allows the tree to tell the model when the node has been closed.
- hasChildren(): returns true/false if the node has children.

The root node should also be an implementation of jQuery, primarily to inherit event binding and triggering. Generally, you do that as follows:
var obj = $({});
$.extend(obj,{
	getName: function() {},
	// etc.
});

Note that the argument to "data" in "model_data" is not the root node itself, but a function to retrieve the root node. Because jstree uses jQuery's deep copy, this would copy the node, rather than give us the node itself, which would lead to errors. Thus, we need a function - which is left as is - to retrieve the root node.

Event Structure:
In order to notify jsTree about changes in the node itself and/or its children, jsTreeModel will bind to the root object for three events:
- addChildren.jstree: The node model should trigger this event when it has added children. The event signature is:
	function(event,node,children,index)
		event is the event itself
		node is the one adding children
		children is one or an array of children object models that have been added.
		index is where in the list of children they should be added. If index is greater than the current number of children, or NaN, 
			then the children will be added at the end.
- removeChildren.jstree: The node model should trigger this event when it has removed children. The event signature is:
	function(event,node,children,index)
- nodeChange.jstree: The node model should trigger this event when the node itself has changed, specifically, one of its name or attributes. Signature:
	function(event,node)
		jsTreeModel will do model.getName() and model.getAttrs() to retrieve the latest information.

We considered making every node a jquery - in practice that is what we usually do, quite inexpensive since javascript is prototypal - but the issue was creating an event handler on each node. There is negligible impact on a small tree of 50 nodes, or even a medium one of 500 nodes, but there is significant impact for a large tree of thousands of nodes.

Additionally, every node may have one more functions available on it:
- getType(): returns a string representing some arbitrary type for this node. If available and returns non-null or blank string, will be given an attribute on the <li> element of type_attr or, if no type_attr, "rel"


About

Plugin for jstree that allows for model backing

Resources

Stars

Watchers

Forks

Packages

No packages published