Amazing Tree

Amazing Tree is also listed on the projects page

Contents

  1. What is Amazing Tree ?
  2. Demo
  3. Features
  4. Browser Support
  5. Documentation
    1. AT_Node
    2. node.addChildNode / node.removeChildNode
    3. node.isParentOf
    4. node.permission.parent / node.permission.above / node.permission.below
    5. node.render
    6. node.expand / node.collapse
    7. AmazingTree.successfulDragDrop / AmazingTree.unsuccessfulDragDrop
    8. AmazingTree.pointsOfInterest
    9. AmazingTree.baseURL
    10. AmazingTree.enableDragDrop
    11. AmazingTree.scroll.speed / AmazingTree.scroll.boundary
  6. License

What is Amazing Tree ?

Amazing Tree is a javascript A navigation tree that allows you to drag and drop nodes around the tree. It provides a number of features while working within most of the popular browsers. If you like it, you will find the license flexible enough to use it in almost any project.

Demo

Scroll Demo: Demo that shows scrolling when the mouse is at the edge of the frame.

Full Demo: Shows off many different features of the library.

Clone Demo: Shows the clone feature which allows nodes to be cloned on drag and drop instead of moving them to the new location.

Features

  1. callback function on successful and unsuccessful drag and drop
  2. Points of intrest can be defined with callbacks for mouse events
  3. Enable and disable drag drop on the tree
  4. Set scroll speed and boundaries when mouse reaches the edges
  5. Dynamically add and remove nodes
  6. Expand and collapse nodes through function calls
  7. Permission callbacks to allow and disallow certain drag drop situations

Browser Support

Internet explorer 6+

FireFox 1.5+

Opera 9.5+

Safari

Google Chrome

Documentation

AT_Node

An AT_Node represents one link in the tree. It contains the properties and functions related to the node.

1 new AT_Node({
2     text: string,
3     url: string,
4     target: "_blank",
5     icon: string,
6     iconOpen: string,
7     clone: boolean,
8     data: object
9 })

text is the link text.
url is the address to visit when the link is clicked.
target is added to the anchor tag.
icon is the url of the icon to show when the node is not expanded.
iconOpen is the url of the icon to show when the link is expanded.
If clone is set to true, the node is cloned instead of being moved to the new location on drag and drop.
data is any user defined data associated with the node and is an object.
All the above parameters are optional.

Example:

01 var node = new AT_Node({
02     text: "Link Name",
03     url: "http://www.ankur.com",
04     target: "_blank",
05     icon: "images/icon1.png",
06     iconOpen: "images/icon2.png",
07     clone: false,
08     data: {
09         linkID: 1,
10         status: "new_node"
11     }
12 });

node.addChildNode / node.removeChildNode

The AT_Node functions addChildNode and removeChildNode add or remove one AT_Node as a child of another AT_Node.

1 parentNode.addChildNode( childNode );
2 parentNode.removeChildNode( childNode );

Example:

01 parentNode = new AT_Node({
02     text: "Node 1",
03     url: "http://www.ankur.com/"
04 });
05  
06 childNode = new AT_Node({
07     text: "Node 1.1",
08     url: "http://www.ankur.com/"
09 });
10  
11 parentNode.addChildNode( childNode );
12  
13 parentNode.removeChildNode( childNode );

node.isParentOf

The AT_Node function isParentOf return is used to check if one node is a child of another node or not.

1 parentNode.isParentOf( childNode );

The function call returns true if parentNode is a parent of childNode and false otherwise. You should note that parent is not necessarily the direct parent. The function returns true as long as parentNode is an ancestor of childNode.

Example:

1 if ( parentNode.isParentOf( childNode ) ) {
2     alert(parentNode.text + " is an ancestor of " + childNode.text);
3 } else {
4     alert(parentNode.text + " is not an ancestor of " + childNode.text);
5 }

node.permission.parent / node.permission.above / node.permission.below

The AT_Node variables permission.parent, permission.above and permission.below are function references that indicate if a particular drag drop of a node is allowed or not.

1 node.permission.parent = functionName;
2 node.permission.above = functionName;
3 node.permission.below = functionName;

The function for each of them should return true if the drag drop is allowed and false if it isn’t. The functions are passed the dragged node and the dropped node (drbopped node will be nothing but node in the above code snippet). You can use these to return true to allow the drag drop operation or return false not to allow it.
node.permission.parent decides if node can become the parent of the dragged node. node.permission.above decides if the dragged node can be dropped above node. node.permission.below decides if the dragged node can be dropped below node.

Example:

1 node1.permission.parent = function(draggedNode, dropNode) {
2  
3     if (draggedNode.text == "Blog") {
4         return true;
5     }
6     return false;
7  
8 }

According to the above function, if the text of the dragged node is “Blog”, it is allowed to be dropped as a child of node1. Otherwise, it is not allowed. Please note that this function is called only if the drag drop will result in the dragged node becoming a child of node1. If that situation does not arise due to the drag drop, the function is not called.

node.render

The AT_Node function render will construct the tree structure on the page. You need to pass it an element inside which the markup of the tree will be placed.

1 node.render( element );

node will usually be the root of the tree, though you can use any other node to render part of the tree.

Example:

1 node.render( getElementById("treeContainer") );

node.expand / node.collapse

The AT_Node functions expand and collapse will expand or collapse a node exactly the same way clicking on + expands the node and – collapses the node. If the node does not have any childrent, calling these functions has no effect.

1 node.expand();
2 node.collapse();

AmazingTree.successfulDragDrop / AmazingTree.unsuccessfulDragDrop

The variables AmazingTree.successfulDragDrop and AmazingTree.unsuccessfulDragDrop are function references which are called on mouse up after a drag and drop operation. If the drag drop operation resulted in a node being moved, AmazingTree.successfulDragDrop is called. If no node was moved, AmazingTree.unsuccessfulDragDrop is called.

1 AmazingTree.successfulDragDrop = functionName;
2 AmazingTree.unsuccessfulDragDrop = functionName;

Each of the functions are passed two objects – dragged and dropped. They contain the variables node, parent, above and below each of which are AT_Node objects. Some of them might be null if they are not aplicable for the situation.

Example:

1 AmazingTree.successfulDragDrop = function(dragged, dropped) {
2     alert("dragged node text is " + dragged.node.text);
3     alert("dropped parent node text is " + dropped.parent.text);
4 }

AmazingTree.pointsOfInterest

The variable AmazingTree.pointsOfInterest contains objects defining elements for which you would like your functions to be called when certain mouse events fire on them. The mouse events you can watch are mouse over, mouse out and mouse up. These events are called only when a node of the tree is being dragged and the event occurs.

1 AmazingTree.pointsOfInterest[ index] = {
2     element: element,
3     mouseOverCallback: functionName,
4     mouseOutCallback: functionName,
5     mouseUpCallback: functionName
6 }

Each of the functions are passed the dragged node and the mouse position. The mouse position is an object with variables x and y representing the distances in pixels from the left and top of the window respectively.

Example:

01 AmazingTree.pointsOfInterest[0] = {
02     element: document.getElementById("delete"),
03     mouseOverCallback: function(draggedNode, mousePos) {
04         document.getElementById("status").innerHTML = "About to delete " + draggedNode.text;
05     },
06     mouseOutCallback: function(draggedNode, mousePos) {
07         document.getElementById("status").innerHTML = "";
08     },
09     mouseUpCallback: function(draggedNode, mousePos) {
10         document.getElementById("status").innerHTML = "deleting " + draggedNode.text;
11         // Code to delete node
12     }
13 }

AmazingTree.baseURL

The variable AmazingTree.baseURL is a string which sets the URL to reach the Amazing Tree directory. If this is set incorrectly, the default images of the tree will not load.

1 AmazingTree.baseURL = url;

Example:

1 AmazingTree.baseURL = "http://www.ankur.com/amazingTree/";

AmazingTree.enableDragDrop

The variable AmazingTree.enableDragDrop can be set to true or false to enable or disable drag drop on the tree.

1 AmazingTree.enableDragDrop = boolean;

Example:

1 AmazingTree.enableDragDrop = true;

AmazingTree.scroll.speed / AmazingTree.scroll.boundary

The variables within AmazingTree.scroll are used to set the scroll speed and scroll boundaries used to scroll when a dragged node reaches the edge of the window. AmazingTree.scroll.speed can be set to a number between 1 and 1000 with 1000 being the fastest and 1 being the slowest scroll speed. Practically, you probably will not notice much difference beyond 200. AmazingTree.scroll.boundary.top, AmazingTree.scroll.boundary.bottom, AmazingTree.scroll.boundary.left and AmazingTree.scroll.boundary.right set the number of pixels from the top, bottom, left and right boundaries when scrolling should begin.

1 AmazingTree.scroll.speed = number;
2 AmazingTree.scroll.boundary.top = number;
3 AmazingTree.scroll.boundary.bottom = number;
4 AmazingTree.scroll.boundary.left = number;
5 AmazingTree.scroll.boundary.right = number;

Example:

1 AmazingTree.scroll.speed = 100;
2 AmazingTree.scroll.boundary.top = 20;
3 AmazingTree.scroll.boundary.bottom = 20;
4 AmazingTree.scroll.boundary.left = 20;
5 AmazingTree.scroll.boundary.right = 20;

License

Amazing Tree is licensed under the BSD license. This should allow you to use it for any project. If this license is unsuitable for you, please contact me. In most reasonable cases, there won’t be any problem in giving it to you under a slightly different license.