Site archive. SpicyNodes was active 2005-2018.

Home > Archive > Developers/reference > API Reference > Javascript

The API is still being finalized. This is a preview...

Using Spicynodes JS API developer can:

• create and manipulate Spicynodes tree
• embed flash object on page
• export and import Spicynodes tree to XML and JSON
• send data via Ajax to server endpoint for processing
• control flash object
• create callback to flash object events

Everything is contained in one file (packed version about 10k). After including it on page new Javascript object becomes available – Spicynodes, which most importantly is used as a container for nodes.

The following are methods and properties for creating and manipulating trees.

Method or property	Description
Spicynodes.nodes	property which represents whole nodes tree, and itself represents root node
Spicynodes.addNode()	x
Spicynodes.getNode(string|array)	For accessing existing nodes - Returns reference to node with given alias, or node at the end of path array
Spicynodes.findBy(string, string)	For accessing existing nodes - Returns reference to first node which property (first parameter) set to value (second parameter).
Spicynodes.each()	traverse all nodes in a tree. It takes one parameter – callback function, and calls it with each node

Nodes, addNode(), and each() are detailed below.

It is most important property which represents whole nodes tree, and itself represents root node – which means that it can (and should) contain some properties. Each element (so root also) is a simple Javascript object, which always contains at least two properties:

Property	Description
_parent	reference to parent object (null for root object) – it is always created automatically
node	an array which contain other objects (child nodes).

Object property names should be of course the same as attributes of node tag from nodemap file (ex. loc, label, name, htmlText etc.).

One thing to mention about _parent property – lower dash before its name is not without a reason – since its not a default node attribute it should be ignored in exporting data to xml or json, and that’s what lower dash is there for. Any property with name starting from “_” will be ignored when exporting data. Therefore developer can add its own properties in nodes (some counter property could be named for ex. _count, or _amount or anything else).

Sample structure (in Javascript Object Notation), could look like:

{
  “label”: “root”,
  “_parent”: null,
  “node”: [
	{
		“label”: “first_child”
	},
	{
		“label”: “second_child”
	}
  ]
}

Its the easiest way to create nodes tree – create Javascript object this way, and assign it to Spicynodes.nodes. Of course creating “bigger” trees this way could be somewhat painful. That’s where addNode method becomes handy.

This method can be used in few various ways, depending on number and type of parameters. It can take up to 3 parameters. The first parameter should always be node object; other parameters are optional. As mentioned before node object is a standard Javascript object with special properties.

There are two approaches to creating Javascript objects.

Approach	Code example
Creating new Object():	var n = new Object(); n.label = “this is node label”; n[“name”] = “node name”;
Using Javascript Object Notation (JSON)	var n = { label: “this is node label”, name: “node name” }

Calling addNode with first parameter (object) only will add this object as a child of root node. For example:

var n = {“label”: “my first child”};
Spicynodes.addNode(n);

Assuming that root properties are default, generated structure in xml would look like:

<node><node label=”my first child”></node></node>

Second parameter can be object, array, or string. Passing an object as a second parameter will add first one as a child to second one. It is all done by references, so doing something like:

var n = {“label”: “my first child”};
Spicynodes.addNode(n);
Spicynodes.addNode({“label”: “other child”},n);

Would create in xml something like (again with default root):

<node><node label=”my first child”><node label=”other child”></node></node></node>

An array parameter is called path, because it can point to one certain node in a tree. Each element of path array must be an integer, which is in fact number of child element in node property (which is also an array). First element points to child of root, second to child of child of root etc. For example:

[0] – points to first child of root.
[0,1] – points to second child of first child of root
[1,1,0] – points to first child of second child of second child of root

This might be helpful if tree structure is “static” and developer knows where what should be added.

Using string as a second parameter creates a named alias for newly added node. Using this alias you can always access node no matter where it is in a tree structure. By using object and string parameters only new node will be added to root, but its name will be stored. The third parameter must be a string – also an alias, but this time alias of a parent node to which object should be added to. So for example:

Spicynodes.addNode({“label”: “corridor”},”corridor”);	//it will add corridor node to root
Spicynodes.addNode({“label”: “lab”},”lab”,”corridor”);	//it will add lab node to corridor
Spicynodes.addNode({“label”: “medic”},”medic”,”lab”);	//it will add medic node to lab

It is definitely the best way of creating complicated tree structures, since developer doesn’t have to remember whole structure, but only hierarchical connections between elements (My Friends → Canada → Toronto → Gustav).

Advanced example:

Spicynodes.addNode({'name’:'friends’, ‘label’:'My Friends’},'friends’);
Spicynodes.addNode({'name’:'canada’, ‘label’:'From Canada’},'canada’,'friends’);
Spicynodes.addNode({'name’:'toronto’, ‘label’:'City Toronto’},'toronto’,'canada’);
Spicynodes.addNode({'name’:'thomas’, ‘label’:'Thomas’},'thom’,'toronto’);
Spicynodes.addNode({'name’:'voyteck’, ‘label’:'Voyteck’},'voj’,'toronto’);
Spicynodes.addNode({'name’:'poland’, ‘label’:'From Poland’},'poland’,'friends’);

Above code will result in this xml:

<node>
	<node label="My Friends" name="friends">
		<node label="From Canada" name="canada">
			<node label="City Toronto" name="toronto">
				<node label="Thomas" name="thomas"></node>
				<node label="Voyteck" name="voyteck"></node>
			</node>
		</node>
		<node label="From Poland" name="poland"></node>
	</node>
</node>

This method is designed to traverse all nodes in a tree. It takes one parameter – callback function, and calls it with each node. Traversing is done recursively, but current depth level is passed to callback function as a second parameter (first is of course current node). For example to get names of all nodes from third level execute:

var secnd = [];
Spicynodes.each(function(node,level) {
	if (level==2) secnd.push(node.name);
});

Spicynodes object also takes care of embedding flash movie on page. It uses object tag only – different for Internet Explorer, different for any other browser. This method works in all modern browsers, and is valid xhtml. There are few properties which influence way flash is embeded.

Object containing default flash parameters, which are:

Spicynodes.flash_options = {
	width: 720,
	height: 480,
	quality: ‘high’,
	bgcolor: ‘#FFFFFF’,
	wmode: ‘transparent’,
	allowScriptAccess: ‘always’,
	swliveconnect: ‘true’,
	allowFullScreen: ‘true’,
	name: "spicyflash"
};

Name option is used also as id, and is used to locate flash movie on page.

Object - additional variables to be sent to flash when embedding. It should be usually redefined. Default is empty.

Reference to flash object, after successfully embedded. It is used to communicate with movie (see Commands).

Embeding itself is done using only this method. First parameter should be DOM element, or id of DOM element where flash should be embedded. Movie object will be appended to the end of it, so no content will be removed. Second parameter is options Object – its properties will overwrite defaults. Example:

Spicynodes.flash(“my_spicy”,{ width: 600, height: 600 });
//above code will create spicyflash inside #my_spicy element, setting its width and height to 600px

There are two methods currently which allows to export to / import from specific format – XML or JSON (most popular those days).

When called without parameters it returns JSON formated text representing current Spicynodes tree. To create tree from JSON pass parameter to this method – either string, or JSON object. If string is detected it will be parsed to JSON object, when object detected it will be simply assigned to Spicynodes.nodes property.

This one is similar to json(). Called without params returns xml string (without header) representation of Spicynodes tree. It can also take two types of parameter – and also either string, or object. If its string – it will be parsed to DOM object, and loaded into Spicynodes.nodes. Second case is passing DOM object directly (with node tags), it also will be loaded.

Sometimes created tree must be stored or manipulated on server side in those cases this method will be helpful. It will prepare and send (via POST method) Spicynodes tree data to any script along with any other parameters. Server script location is defined in Spicynodes.server_url property (default is index.php). First method parameter can be either string or an object – representing additional variables, second is callback function on success, third callback function of error. Current XMLHttpRequest object will be passed as parameter to both callbacks.

Example:

Spicynodes.server_url = “http://www.example.com/ex_script.php”;
Spicynodes.send(“id=33311&action=update”,function(req) { alert(“spicytree successfully uploaded”) });

As mentioned above embedded flash can be accessed (for LiveConnect communication) using Spicynodes.flash_handle property. There are a number of methods which send specific commands to flash movie allowing to control it. Currently those methods are:

Command	Description
cGoto(id)	Centers flash on node with given id. Those id’s are recursively assigned by flash movie. Spicynodes object cannot assign them automatically because tree is not static (developer can add new node anytime to any node). There is a Spicynodes._ids() method which creates _id property to each node, but it should be called once tree is finished.
cHome()	Goes to root node (id=0);
cLoadXML(string)	Loads new xml string into tree, or (without parameters) loads current tree representation into tree.
cNext()	Goes to next node in history (if any).
cPrevious()	Goes to previous node from browse history (if any).
cZoomin()	Zooms in.
cZoomout()	Zooms out.
cZoom(int)	This is not default flash command. It does few zoom steps one by one in direction depending from number sign. This is controlled by javascript setTimeout function, and speed in fact depends on browser, so its not to reliable.

These methods are available after embedding and loading flash. Examples:

Spicynodes.cNext(); //calls next command, which moves flash to next node
Spicynodes.cZoomin(); //zooms flash once
Spicynodes.cGoto(3); //goes to node with id = 3
Spicynodes.cLoadXML(); //loads current nodes tree into flash movie

It is possible to assign some callback user-defined functions on certain Spicynodes flash events. Currently there are six events supported:

Event	Description
onAnimationStart(node)	Executed when spicytree is loaded into flash and initial animation begins, node is a reference to root node from Spicytree.
onAnimationEnd(node)	Executed when initial animation finishes, node is a reference to root node.
onZoomIn()	Called when users zooms in (once per each zoom level).
onZoomOut()	Called when user zooms out (once per each zoom level).
onNodeOver(node)	Executed when mouse enter over certain node, node is a reference to node from tree.
onNodeOut(node)	Executed when mouse leaves node, node is a reference.

Example:

Spicynodes.onNodeOver = function(node) {
	document.getElementById('c_count’) = “This node (“+node.label+”) contains: “+node.node.length+” children”;
}