From a32e5db407960c450074c3d065818fff8ca1c353 Mon Sep 17 00:00:00 2001
From: joesimms <joesimms@625475ce-881a-0410-a577-b389adb331d8>
Date: Mon, 15 Jan 2007 13:43:03 +0000
Subject: [PATCH] joesimms: added draft documentation for hierarchical data
 support, and docs on how to use the tree interface, in particular the
 NestedSet implementation

---
 manual/codes/Hierarchical data - Examples.php | 388 ++++++++++++++++++
 ...l data - Introduction - Node interface.php |  92 +++++
 ...hical data - Introduction - Setting up.php |  22 +
 ...oduction - Traversing or Walking Trees.php |  42 ++
 ...l data - Introduction - Tree interface.php |  29 ++
 ...hical data - Nested set - Introduction.php |   0
 ...rchical data - Nested set - Setting up.php |  21 +
 ...hical data - Nested set - Tree options.php |  25 ++
 ...l data - Adjacency list - Introduction.php |   1 +
 ...l data - Adjacency list - Node support.php |   1 +
 ...chical data - Adjacency list - Read me.php |   0
 ...cal data - Adjacency list - Setting up.php |   0
 ...l data - Adjacency list - Tree options.php |   0
 ...l data - Adjacency list - Tree support.php |   1 +
 manual/docs/Hierarchical data - Examples.php  |   1 +
 ...erarchical data - Introduction - About.php |  16 +
 ...l data - Introduction - Node interface.php |   1 +
 ...archical data - Introduction - Read me.php |   9 +
 ...hical data - Introduction - Setting up.php |   5 +
 ...oduction - Traversing or Walking Trees.php |   3 +
 ...l data - Introduction - Tree interface.php |   1 +
 ...ata - Materialized path - Introduction.php |   1 +
 ...hical data - Nested set - Introduction.php |   6 +
 ...hical data - Nested set - Node support.php |   1 +
 ...erarchical data - Nested set - Read me.php |   4 +
 ...rchical data - Nested set - Setting up.php |   1 +
 ...hical data - Nested set - Tree options.php |   3 +
 ...hical data - Nested set - Tree support.php |   1 +
 manual/documentation.php                      |   8 +-
 29 files changed, 680 insertions(+), 3 deletions(-)
 create mode 100644 manual/codes/Hierarchical data - Examples.php
 create mode 100644 manual/codes/Hierarchical data - Introduction - Node interface.php
 create mode 100644 manual/codes/Hierarchical data - Introduction - Setting up.php
 create mode 100644 manual/codes/Hierarchical data - Introduction - Traversing or Walking Trees.php
 create mode 100644 manual/codes/Hierarchical data - Introduction - Tree interface.php
 create mode 100644 manual/codes/Hierarchical data - Nested set - Introduction.php
 create mode 100644 manual/codes/Hierarchical data - Nested set - Setting up.php
 create mode 100644 manual/codes/Hierarchical data - Nested set - Tree options.php
 create mode 100644 manual/docs/Hierarchical data - Adjacency list - Node support.php
 create mode 100644 manual/docs/Hierarchical data - Adjacency list - Read me.php
 create mode 100644 manual/docs/Hierarchical data - Adjacency list - Setting up.php
 create mode 100644 manual/docs/Hierarchical data - Adjacency list - Tree options.php
 create mode 100644 manual/docs/Hierarchical data - Adjacency list - Tree support.php
 create mode 100644 manual/docs/Hierarchical data - Examples.php
 create mode 100644 manual/docs/Hierarchical data - Introduction - About.php
 create mode 100644 manual/docs/Hierarchical data - Introduction - Node interface.php
 create mode 100644 manual/docs/Hierarchical data - Introduction - Read me.php
 create mode 100644 manual/docs/Hierarchical data - Introduction - Setting up.php
 create mode 100644 manual/docs/Hierarchical data - Introduction - Traversing or Walking Trees.php
 create mode 100644 manual/docs/Hierarchical data - Introduction - Tree interface.php
 create mode 100644 manual/docs/Hierarchical data - Nested set - Introduction.php
 create mode 100644 manual/docs/Hierarchical data - Nested set - Node support.php
 create mode 100644 manual/docs/Hierarchical data - Nested set - Read me.php
 create mode 100644 manual/docs/Hierarchical data - Nested set - Setting up.php
 create mode 100644 manual/docs/Hierarchical data - Nested set - Tree options.php
 create mode 100644 manual/docs/Hierarchical data - Nested set - Tree support.php

diff --git a/manual/codes/Hierarchical data - Examples.php b/manual/codes/Hierarchical data - Examples.php
new file mode 100644
index 000000000..5886a866d
--- /dev/null
+++ b/manual/codes/Hierarchical data - Examples.php	
@@ -0,0 +1,388 @@
+<?php
+
+require_once("path/to/Doctrine.php");
+ 
+function __autoload($classname) {
+
+    return Doctrine::autoload($classname);
+
+}
+
+// define our tree
+class Menu extends Doctrine_Record { 
+    public function setTableDefinition() {
+
+        $this->setTableName('menu');
+
+        // add this your table definition to set the table as NestedSet tree implementation
+        $this->actsAsTree('NestedSet');
+       
+        // you do not need to add any columns specific to the nested set implementation
+		// these are added for you
+        $this->hasColumn("name","string",30);
+
+    }
+    
+    // this __toString() function is used to get the name for the path, see node::getPath
+    public function __toString() {
+        return $this->get('name');
+    }
+}
+
+// set connections to database
+$dsn = 'mysql:dbname=nestedset;host=localhost';
+$user = 'user';
+$password = 'pass';
+ 
+try {
+    $dbh = new PDO($dsn, $user, $password);
+} catch (PDOException $e) {
+    echo 'Connection failed: ' . $e->getMessage();
+}
+ 
+$manager = Doctrine_Manager::getInstance();
+ 
+$conn = $manager->openConnection($dbh);
+
+// create root
+$root = new Menu();
+$root->set('name', 'root');
+
+$manager->getTable('Menu')->getTree()->createRoot($root);
+
+// build tree
+$two = new Menu();
+$two->set('name', '2');
+$root->getNode()->addChild($two);
+
+$one = new Menu();
+$one->set('name', '1');
+$one->getNode()->insertAsPrevSiblingOf($two);
+
+// refresh as node's lft and rgt values have changed
+$two->refresh();
+
+$three = new Menu();
+$three->set('name', '3');
+$three->getNode()->insertAsNextSiblingOf($two);
+$two->refresh();
+
+$one_one = new Menu();
+$one_one->set('name', '1.1');
+$one_one->getNode()->insertAsFirstChildOf($one);
+$one->refresh();
+
+$one_two = new Menu();
+$one_two->set('name', '1.2');
+$one_two->getNode()->insertAsLastChildOf($one);
+$one_two->refresh();
+
+$one_two_one = new Menu();
+$one_two_one->set('name', '1.2.1');
+$one_two->getNode()->addChild($one_two_one);
+
+$root->refresh();
+$four = new Menu();
+$four->set('name', '4');
+$root->getNode()->addChild($four);
+
+$root->refresh();
+$five = new Menu();
+$five->set('name', '5');
+$root->getNode()->addChild($five);
+
+$root->refresh();
+$six = new Menu();
+$six->set('name', '6');
+$root->getNode()->addChild($six);
+
+output_message('initial tree');
+output_tree($root);
+
+$one_one->refresh();
+$six->set('name', '1.0 (was 6)');
+$six->getNode()->moveAsPrevSiblingOf($one_one);
+
+$one_two->refresh();
+$five->refresh();
+$five->set('name', '1.3 (was 5)');
+$five->getNode()->moveAsNextSiblingOf($one_two);
+
+$one_one->refresh();
+$four->refresh();
+$four->set('name', '1.1.1 (was 4)');
+$four->getNode()->moveAsFirstChildOf($one_one);
+
+$root->refresh();
+$one_two_one->refresh();
+$one_two_one->set('name', 'last (was 1.2.1)');
+$one_two_one->getNode()->moveAsLastChildOf($root);
+
+output_message('transformed tree');
+output_tree($root);
+
+$one_one->refresh();
+$one_one->deleteNode();
+
+output_message('delete 1.1');
+output_tree($root);
+
+// now test fetching root
+$tree_root = $manager->getTable('Menu')->getTree()->findRoot();
+output_message('testing fetch root and outputting tree from the root node');
+output_tree($tree_root);
+
+// now test fetching the tree
+output_message('testing fetching entire tree using tree::fetchTree()');
+$tree = $manager->getTable('Menu')->getTree()->fetchTree();
+while($node = $tree->next())
+{
+  output_node($node);
+}
+
+// now test fetching the tree
+output_message('testing fetching entire tree using tree::fetchTree(), excluding root node');
+$tree = $manager->getTable('Menu')->getTree()->fetchTree(array('include_record' => false));
+while($node = $tree->next())
+{
+  output_node($node);
+}
+
+// now test fetching the branch
+output_message('testing fetching branch for 1, using tree::fetchBranch()');
+$one->refresh();
+$branch = $manager->getTable('Menu')->getTree()->fetchBranch($one->get('id'));
+while($node = $branch->next())
+{
+  output_node($node);
+}
+
+// now test fetching the tree
+output_message('testing fetching branch for 1, using tree::fetchBranch() excluding node 1');
+$tree = $manager->getTable('Menu')->getTree()->fetchBranch($one->get('id'), array('include_record' => false));
+while($node = $tree->next())
+{
+  output_node($node);
+}
+
+// now perform some tests
+output_message('descendants for 1');
+$descendants = $one->getNode()->getDescendants();
+while($descendant = $descendants->next())
+{
+  output_node($descendant);
+}
+
+// move one and children under two
+$two->refresh();
+$one->getNode()->moveAsFirstChildOf($two);
+
+output_message('moved one as first child of 2');
+output_tree($root);
+
+output_message('descendants for 2');
+$two->refresh();
+$descendants = $two->getNode()->getDescendants();
+while($descendant = $descendants->next())
+{
+  output_node($descendant);
+}
+
+output_message('number descendants for 2');
+echo $two->getNode()->getNumberDescendants() .'</br>';
+
+output_message('children for 2 (notice excludes children of children, known as descendants)');
+$children = $two->getNode()->getChildren();
+while($child = $children->next())
+{
+  output_node($child);
+}
+
+output_message('number children for 2');
+echo $two->getNode()->getNumberChildren() .'</br>';
+
+output_message('path to 1');
+$path = $one->getNode()->getPath(' > ');
+echo $path .'<br />';
+
+output_message('path to 1 (including 1)');
+$path = $one->getNode()->getPath(' > ', true);
+echo $path .'<br />';
+
+output_message('1 has parent');
+$hasParent = $one->getNode()->hasParent();
+$msg = $hasParent ? 'true' : 'false';
+echo $msg . '</br/>';
+
+output_message('parent to 1');
+$parent = $one->getNode()->getParent();
+if($parent->exists())
+{
+  echo $parent->get('name') .'<br />';  
+}
+
+output_message('root isRoot?');
+$isRoot = $root->getNode()->isRoot();
+$msg = $isRoot ? 'true' : 'false';
+echo $msg . '</br/>';
+
+output_message('one isRoot?');
+$isRoot = $one->getNode()->isRoot();
+$msg = $isRoot ? 'true' : 'false';
+echo $msg . '</br/>';
+
+output_message('root hasParent');
+$hasParent = $root->getNode()->hasParent();
+$msg = $hasParent ? 'true' : 'false';
+echo $msg . '</br/>';
+
+output_message('root getParent');
+$parent = $root->getNode()->getParent();
+if($parent->exists())
+{
+  echo $parent->get('name') .'<br />';  
+}
+
+output_message('get first child of root');
+$record = $root->getNode()->getFirstChild();
+if($record->exists())
+{
+  echo $record->get('name') .'<br />';  
+}
+
+output_message('get last child of root');
+$record = $root->getNode()->getLastChild();
+if($record->exists())
+{
+  echo $record->get('name') .'<br />';  
+}
+
+$one_two->refresh();
+
+output_message('get prev sibling of 1.2');
+$record = $one_two->getNode()->getPrevSibling();
+if($record->exists())
+{
+  echo $record->get('name') .'<br />';  
+}
+
+output_message('get next sibling of 1.2');
+$record = $one_two->getNode()->getNextSibling();
+if($record->exists())
+{
+  echo $record->get('name') .'<br />';  
+}
+
+output_message('siblings of 1.2');
+$siblings = $one_two->getNode()->getSiblings();
+foreach($siblings as $sibling)
+{
+  if($sibling->exists())
+    echo $sibling->get('name') .'<br />'; 
+}
+
+output_message('siblings of 1.2 (including 1.2)');
+$siblings = $one_two->getNode()->getSiblings(true);
+foreach($siblings as $sibling)
+{
+  if($sibling->exists())
+    echo $sibling->get('name') .'<br />'; 
+}
+
+$new = new Menu();
+$new->set('name', 'parent of 1.2');
+$new->getNode()->insertAsParentOf($one_two);
+
+output_message('added a parent to 1.2');
+output_tree($root);
+
+try {
+  $dummy = new Menu();
+  $dummy->set('name', 'dummy');
+  $dummy->save();  
+}
+catch (Doctrine_Exception $e)
+{
+  output_message('You cannot save a node unless it is in the tree');
+}
+
+try {
+  $fake = new Menu();
+  $fake->set('name', 'dummy');
+  $fake->set('lft', 200);
+  $fake->set('rgt', 1);
+  $fake->save();  
+}
+catch (Doctrine_Exception $e)
+{
+  output_message('You cannot save a node with bad lft and rgt values');
+}
+
+// check last remaining tests
+output_message('New parent is descendant of 1');
+$one->refresh();
+$res = $new->getNode()->isDescendantOf($one);
+$msg = $res ? 'true' : 'false';
+echo $msg . '</br/>';
+
+output_message('New parent is descendant of 2');
+$two->refresh();
+$res = $new->getNode()->isDescendantOf($two);
+$msg = $res ? 'true' : 'false';
+echo $msg . '</br/>';
+
+output_message('New parent is descendant of 1.2');
+$one_two->refresh();
+$res = $new->getNode()->isDescendantOf($one_two);
+$msg = $res ? 'true' : 'false';
+echo $msg . '</br/>';
+
+output_message('New parent is descendant of or equal to 1');
+$one->refresh();
+$res = $new->getNode()->isDescendantOfOrEqualTo($one);
+$msg = $res ? 'true' : 'false';
+echo $msg . '</br/>';
+
+output_message('New parent is descendant of or equal to 1.2');
+$one_two->refresh();
+$res = $new->getNode()->isDescendantOfOrEqualTo($one_two);
+$msg = $res ? 'true' : 'false';
+echo $msg . '</br/>';
+
+output_message('New parent is descendant of or equal to 1.3');
+$five->refresh();
+$res = $new->getNode()->isDescendantOfOrEqualTo($new);
+$msg = $res ? 'true' : 'false';
+echo $msg . '</br/>';
+
+function output_tree($root)
+{
+  // display tree
+  // first we must refresh the node as the tree has been transformed
+  $root->refresh();
+
+  // next we must get the iterator to traverse the tree from the root node
+  $traverse = $root->getNode()->traverse();
+
+  output_node($root);
+  // now we traverse the tree and output the menu items
+  while($item = $traverse->next())
+  {
+    output_node($item);
+  }  
+
+  unset($traverse);
+}
+
+function output_node($record)
+{
+  echo str_repeat('-', $record->getNode()->getLevel()) . $record->get('name') 
+						. ' (has children:'.$record->getNode()->hasChildren().') '
+						. ' (is leaf:'.$record->getNode()->isLeaf().') '.'<br/>';  
+}
+
+function output_message($msg)
+{
+  echo "<br /><strong><em>$msg</em></strong>".'<br />';
+}
+?>
\ No newline at end of file
diff --git a/manual/codes/Hierarchical data - Introduction - Node interface.php b/manual/codes/Hierarchical data - Introduction - Node interface.php
new file mode 100644
index 000000000..f63357bc8
--- /dev/null
+++ b/manual/codes/Hierarchical data - Introduction - Node interface.php	
@@ -0,0 +1,92 @@
+<?php
+interface Doctrine_Node_Interface {
+
+    /**
+     * insert node into tree
+     */
+    public function insertAsParentOf(Doctrine_Record $dest);
+
+    public function insertAsPrevSiblingOf(Doctrine_Record $dest);
+
+    public function insertAsNextSiblingOf(Doctrine_Record $dest);
+
+    public function insertAsFirstChildOf(Doctrine_Record $dest);
+
+    public function insertAsLastChildOf(Doctrine_Record $dest);
+
+    public function addChild(Doctrine_Record $record);
+
+    /**
+     * moves node (if has children, moves branch)
+     *
+     */  
+    public function moveAsPrevSiblingOf(Doctrine_Record $dest);
+
+    public function moveAsNextSiblingOf(Doctrine_Record $dest);
+
+    public function moveAsFirstChildOf(Doctrine_Record $dest);
+
+    public function moveAsLastChildOf(Doctrine_Record $dest);
+
+    /**
+     * node information
+     */
+    public function getPrevSibling();
+
+    public function getNextSibling();
+
+    public function getSiblings($includeNode = false);
+
+    public function getFirstChild();
+
+    public function getLastChild();
+
+    public function getChildren();
+
+    public function getDescendants();
+
+    public function getParent();
+
+    public function getAncestors();
+
+    public function getPath($seperator = ' > ', $includeNode = false);
+
+    public function getLevel();
+
+    public function getNumberChildren();
+
+    public function getNumberDescendants();
+
+    /**
+     * node checks
+     */
+    public function hasPrevSibling();
+
+    public function hasNextSibling();
+
+    public function hasChildren();
+
+    public function hasParent();
+
+    public function isLeaf();
+
+    public function isRoot();
+
+    public function isEqualTo(Doctrine_Record $subj);
+
+    public function isDescendantOf(Doctrine_Record $subj);
+
+    public function isDescendantOfOrEqualTo(Doctrine_Record $subj);
+
+    public function isValidNode();
+
+    /**
+     * deletes node and it's descendants
+     */
+    public function delete();
+}
+
+// if your model acts as tree you can retrieve the associated node object as follows
+$record = $manager->getTable('Model')->find($pk);
+$nodeObj = $record->getNode();
+?>
\ No newline at end of file
diff --git a/manual/codes/Hierarchical data - Introduction - Setting up.php b/manual/codes/Hierarchical data - Introduction - Setting up.php
new file mode 100644
index 000000000..1798fb40b
--- /dev/null
+++ b/manual/codes/Hierarchical data - Introduction - Setting up.php	
@@ -0,0 +1,22 @@
+<?php
+class Menu extends Doctrine_Record { 
+    public function setTableDefinition() {
+
+        $this->setTableName('menu');
+
+        // add this your table definition to set the table as NestedSet tree implementation
+		// $implName is 'NestedSet' or 'AdjacencyList' or 'MaterializedPath'
+		// $options is an assoc array of options, see implementation docs for options
+        $this->actsAsTree($implName, $options);
+       
+        // you do not need to add any columns specific to the nested set implementation, these are added for you
+        $this->hasColumn("name","string",30);
+
+    }
+    
+    // this __toString() function is used to get the name for the path, see node::getPath()
+    public function __toString() {
+        return $this->get('name');
+    }
+}
+?>
\ No newline at end of file
diff --git a/manual/codes/Hierarchical data - Introduction - Traversing or Walking Trees.php b/manual/codes/Hierarchical data - Introduction - Traversing or Walking Trees.php
new file mode 100644
index 000000000..40337b672
--- /dev/null
+++ b/manual/codes/Hierarchical data - Introduction - Traversing or Walking Trees.php	
@@ -0,0 +1,42 @@
+<?php
+/*
+ * traverse the entire tree from root
+ */
+$root = $manager->getTable('Model')->getTree()->fetchRoot();
+if($root->exists())
+{
+	$tree = $root->traverse();
+	while($node = $tree->next())
+	{
+		// output your tree here
+	}
+}
+
+// or the optimised approach using tree::fetchTree
+$tree = $manager->getTable('Model')->getTree()->fetchTree();
+while($node = $tree->next())
+{
+	// output tree here
+}
+
+/*
+ * traverse a branch of the tree
+ */
+$record = $manager->getTable('Model')->find($pk);
+if($record->exists())
+{
+	$branch = $record->traverse();
+	while($node = $branch->next())
+	{
+		// output your tree here
+	}
+}
+
+// or the optimised approach
+$branch = $manager->getTable('Model')->getTree()->fetchBranch($pk);
+while($node = $branch->traverse())
+{
+	// output your tree here
+}
+
+?>
\ No newline at end of file
diff --git a/manual/codes/Hierarchical data - Introduction - Tree interface.php b/manual/codes/Hierarchical data - Introduction - Tree interface.php
new file mode 100644
index 000000000..3cac1f234
--- /dev/null
+++ b/manual/codes/Hierarchical data - Introduction - Tree interface.php	
@@ -0,0 +1,29 @@
+<?php
+
+interface Doctrine_Tree_Interface {
+
+    /**
+     * creates root node from given record or from a new record
+     */
+    public function createRoot(Doctrine_Record $record = null);
+
+    /**
+     * returns root node
+     */
+    public function findRoot($root_id = 1);
+
+    /**
+     * optimised method to returns iterator for traversal of the entire tree from root
+     */
+    public function fetchTree($options = array());
+
+    /**
+     * optimised method that returns iterator for traversal of the tree from the given record's primary key
+     */
+    public function fetchBranch($pk, $options = array());
+}
+
+// if your model acts as tree you can retrieve the associated tree object as follows
+$treeObj = $manager->getTable('Model')->getTree();
+
+?>
\ No newline at end of file
diff --git a/manual/codes/Hierarchical data - Nested set - Introduction.php b/manual/codes/Hierarchical data - Nested set - Introduction.php
new file mode 100644
index 000000000..e69de29bb
diff --git a/manual/codes/Hierarchical data - Nested set - Setting up.php b/manual/codes/Hierarchical data - Nested set - Setting up.php
new file mode 100644
index 000000000..0dca96527
--- /dev/null
+++ b/manual/codes/Hierarchical data - Nested set - Setting up.php	
@@ -0,0 +1,21 @@
+<?php
+class Menu extends Doctrine_Record { 
+    public function setTableDefinition() {
+
+        $this->setTableName('menu');
+		
+        // add this your table definition to set the table as NestedSet tree implementation
+		$options = array();
+        $this->actsAsTree('NestedSet', $options);
+       
+        // you do not need to add any columns specific to the nested set implementation, these are added for you
+        $this->hasColumn("name","string",30);
+
+    }
+    
+    // this __toString() function is used to get the name for the path, see node::getPath()
+    public function __toString() {
+        return $this->get('name');
+    }
+}
+?>
\ No newline at end of file
diff --git a/manual/codes/Hierarchical data - Nested set - Tree options.php b/manual/codes/Hierarchical data - Nested set - Tree options.php
new file mode 100644
index 000000000..eaeec7fdd
--- /dev/null
+++ b/manual/codes/Hierarchical data - Nested set - Tree options.php	
@@ -0,0 +1,25 @@
+<?php
+$options = array('has_many_roots' => true,			// enable many roots
+	  			 'root_column_name' => 'root_id')	// set root column name, defaults to 'root_id'
+
+// To create new root nodes, if you have manually set the root_id, then it will be used
+// otherwise it will automatically use the next available root id
+$root = new Menu();
+$root->set('name', 'root');
+
+// insert first root, will auto be assigned root_id = 1
+$manager->getTable('Menu')->getTree()->createRoot($root);
+
+$another_root = new Menu();
+$another_root->set('name', 'another root');
+
+// insert another root, will auto be assigned root_id = 2
+$manager->getTable('Menu')->getTree()->createRoot($another_root);
+
+// fetching a specifc root
+$root = $manager->getTable('Menu')->getTree()->fetchRoot(1);
+$another_root = $manager->getTable('Menu')->getTree()->fetchRoot(2);
+
+// fetching all roots
+$roots = $manager->getTable('Menu')->getTree()->fetchRoots();
+?>
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Adjacency list - Introduction.php b/manual/docs/Hierarchical data - Adjacency list - Introduction.php
index e69de29bb..e22100a60 100644
--- a/manual/docs/Hierarchical data - Adjacency list - Introduction.php	
+++ b/manual/docs/Hierarchical data - Adjacency list - Introduction.php	
@@ -0,0 +1 @@
+Not yet implemented
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Adjacency list - Node support.php b/manual/docs/Hierarchical data - Adjacency list - Node support.php
new file mode 100644
index 000000000..e2ea433ab
--- /dev/null
+++ b/manual/docs/Hierarchical data - Adjacency list - Node support.php	
@@ -0,0 +1 @@
+Partially supported, available methods
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Adjacency list - Read me.php b/manual/docs/Hierarchical data - Adjacency list - Read me.php
new file mode 100644
index 000000000..e69de29bb
diff --git a/manual/docs/Hierarchical data - Adjacency list - Setting up.php b/manual/docs/Hierarchical data - Adjacency list - Setting up.php
new file mode 100644
index 000000000..e69de29bb
diff --git a/manual/docs/Hierarchical data - Adjacency list - Tree options.php b/manual/docs/Hierarchical data - Adjacency list - Tree options.php
new file mode 100644
index 000000000..e69de29bb
diff --git a/manual/docs/Hierarchical data - Adjacency list - Tree support.php b/manual/docs/Hierarchical data - Adjacency list - Tree support.php
new file mode 100644
index 000000000..e2ea433ab
--- /dev/null
+++ b/manual/docs/Hierarchical data - Adjacency list - Tree support.php	
@@ -0,0 +1 @@
+Partially supported, available methods
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Examples.php b/manual/docs/Hierarchical data - Examples.php
new file mode 100644
index 000000000..6db94816c
--- /dev/null
+++ b/manual/docs/Hierarchical data - Examples.php	
@@ -0,0 +1 @@
+This is an example to show how you would set up and use the doctrine tree interface with the NestedSet implementation (currently the most comprehensively supported by Doctrine)
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Introduction - About.php b/manual/docs/Hierarchical data - Introduction - About.php
new file mode 100644
index 000000000..4d6862245
--- /dev/null
+++ b/manual/docs/Hierarchical data - Introduction - About.php	
@@ -0,0 +1,16 @@
+<p>Most users at one time or another have dealt with hierarchical data in a SQL database and no doubt learned that the management of hierarchical data is not what a relational database is intended for. The tables of a relational database are not hierarchical (like XML), but are simply a flat list. Hierarchical data has a parent-child relationship that is not naturally represented in a relational database table.</p>
+
+<p>For our purposes, hierarchical data is a collection of data where each item has a single parent and zero or more children (with the exception of the root item, which has no parent). Hierarchical data can be found in a variety of database applications, including forum and mailing list threads, business organization charts, content management categories, and product categories.</p>
+
+<p>In a hierarchical data model, data is organized into a tree-like structure. The tree structure allows repeating information using parent/child relationships. For an explanation of the tree data structure, see here <a href="http://en.wikipedia.org/wiki/Tree_data_structure" >http://en.wikipedia.org/wiki/Tree_data_structure</a></p>
+
+<p>There are three major approaches to managing tree structures in relational databases, these are:</p>
+
+<ul>
+	<li>the adjacency list model</li>
+	<li>the nested set model (otherwise known as the modified pre-order tree traversal algorithm)</li> 
+	<li>materialized path model</li> 
+</ul>
+
+<p>These are explained in more detail in the following chapters, or see<br />
+<a href="http://www.dbazine.com/oracle/or-articles/tropashko4" >http://www.dbazine.com/oracle/or-articles/tropashko4</a>, <a href="http://dev.mysql.com/tech-resources/articles/hierarchical-data.html" >http://dev.mysql.com/tech-resources/articles/hierarchical-data.html</a></p>
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Introduction - Node interface.php b/manual/docs/Hierarchical data - Introduction - Node interface.php
new file mode 100644
index 000000000..3d8d9d843
--- /dev/null
+++ b/manual/docs/Hierarchical data - Introduction - Node interface.php	
@@ -0,0 +1 @@
+<p>The node interface, for inserting and manipulating nodes within the tree, is accessed on a record level. A full implementation of this interface will be as follows:</p>
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Introduction - Read me.php b/manual/docs/Hierarchical data - Introduction - Read me.php
new file mode 100644
index 000000000..2be9cb626
--- /dev/null
+++ b/manual/docs/Hierarchical data - Introduction - Read me.php	
@@ -0,0 +1,9 @@
+<p>If performing batch tree manipulation tasks, then remember to refresh your records (see record::refresh()), as any transformations of the tree are likely to affect all instances of records that you have in your scope.</p>
+
+<p>You can save an already existing node using record::save() without affecting it's position within the tree. Remember to never set the tree specific record attributes manually.</p>
+
+<p>If you are inserting or moving a node within the tree, you must use the appropriate node method. Note: you do not need to save a record once you have inserted it or moved it within the tree, any other changes to your record will also be saved within these operations. You cannot save a new record without inserting it into the tree.</p>
+
+<p>If you wish to delete a record, you MUST delete the node and not the record, using $record->deleteNode() or $record->getNode()->delete(). Deleting a node, will by default delete all its descendants. if you delete a record without using the node::delete() method you tree is likely to become corrupt (and fall down)!</p>
+
+<p>The difference between descendants and children is that descendants include children of children whereas children are direct descendants of their parent (real children not gran children and great gran children etc etc).</p>
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Introduction - Setting up.php b/manual/docs/Hierarchical data - Introduction - Setting up.php
new file mode 100644
index 000000000..3df395fd0
--- /dev/null
+++ b/manual/docs/Hierarchical data - Introduction - Setting up.php	
@@ -0,0 +1,5 @@
+<p>Managing tree structures in doctrine is easy. Doctrine currently fully supports Nested Set, and plans to support the other implementations soon. To set your model to act as a tree, simply add the code below to your models table definition.</p>
+
+<p>Now that Doctrine knows that this model acts as a tree, it will automatically add any required columns for your chosen implementation, so you do not need to set any tree specific columns within your table definition.</p>
+
+<p>Doctrine has standard interface's for managing tree's, that are used by all the implementations. Every record in the table represents a node within the tree (the table), so doctrine provides two interfaces, Tree and Node.</p>
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Introduction - Traversing or Walking Trees.php b/manual/docs/Hierarchical data - Introduction - Traversing or Walking Trees.php
new file mode 100644
index 000000000..dba521edd
--- /dev/null
+++ b/manual/docs/Hierarchical data - Introduction - Traversing or Walking Trees.php	
@@ -0,0 +1,3 @@
+<p>You can traverse a Tree in different ways, please see here for more information http://en.wikipedia.org/wiki/Tree_traversal.</p>
+
+<p>The most common way of traversing a tree is Pre Order Traversal as explained in the link above, this is also what is known as walking the tree, this is the default approach when traversing a tree in Doctrine, however Doctrine does plan to provide support for Post and Level Order Traversal (not currently implemented)</p>
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Introduction - Tree interface.php b/manual/docs/Hierarchical data - Introduction - Tree interface.php
new file mode 100644
index 000000000..49e27c648
--- /dev/null
+++ b/manual/docs/Hierarchical data - Introduction - Tree interface.php	
@@ -0,0 +1 @@
+<p>The tree interface, for creating and accessing the tree, is accessed on a table level. A full implementation of this interface would be as follows:</p>
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Materialized path - Introduction.php b/manual/docs/Hierarchical data - Materialized path - Introduction.php
index e69de29bb..e22100a60 100644
--- a/manual/docs/Hierarchical data - Materialized path - Introduction.php	
+++ b/manual/docs/Hierarchical data - Materialized path - Introduction.php	
@@ -0,0 +1 @@
+Not yet implemented
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Nested set - Introduction.php b/manual/docs/Hierarchical data - Nested set - Introduction.php
new file mode 100644
index 000000000..d6353f581
--- /dev/null
+++ b/manual/docs/Hierarchical data - Nested set - Introduction.php	
@@ -0,0 +1,6 @@
+<p>Basically Nested Set is optimized for traversing trees, as this can be done with minimal queries, however updating the tree can be costly as it will affect all rows within the table.</p>
+
+<p>For more information, read here:<br />
+<a href="http://www.sitepoint.com/article/hierarchical-data-database/2" >http://www.sitepoint.com/article/hierarchical-data-database/2</a>,
+<a href="http://dev.mysql.com/tech-resources/articles/hierarchical-data.html" >http://dev.mysql.com/tech-resources/articles/hierarchical-data.html</a>
+</p>
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Nested set - Node support.php b/manual/docs/Hierarchical data - Nested set - Node support.php
new file mode 100644
index 000000000..24aec3f2c
--- /dev/null
+++ b/manual/docs/Hierarchical data - Nested set - Node support.php	
@@ -0,0 +1 @@
+The nested set implementation fully supports the full Doctrine node interface
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Nested set - Read me.php b/manual/docs/Hierarchical data - Nested set - Read me.php
new file mode 100644
index 000000000..301775d16
--- /dev/null
+++ b/manual/docs/Hierarchical data - Nested set - Read me.php	
@@ -0,0 +1,4 @@
+<p>The most effective way to traverse a tree from the root node, is to use the tree::fetchTree() method.
+It will by default include the root node in the tree and will return an iterator to traverse the tree.</p>
+
+<p>To traverse a tree from a given node, it will normally cost 3 queries, one to fetch the starting node, one to fetch the branch from this node, and one to determine the level of the start node, the traversal algorithm with then determine the level of each subsequent node for you.</p>
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Nested set - Setting up.php b/manual/docs/Hierarchical data - Nested set - Setting up.php
new file mode 100644
index 000000000..6407181f2
--- /dev/null
+++ b/manual/docs/Hierarchical data - Nested set - Setting up.php	
@@ -0,0 +1 @@
+<p>To set up your model as Nested Set, you must add the following code to your model's table definition.</p>
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Nested set - Tree options.php b/manual/docs/Hierarchical data - Nested set - Tree options.php
new file mode 100644
index 000000000..6ef340e4e
--- /dev/null
+++ b/manual/docs/Hierarchical data - Nested set - Tree options.php	
@@ -0,0 +1,3 @@
+<p>The nested implementation can be configured to allow your table to have multiple root nodes, and therefore multiple trees within the same table.</p>
+
+<p>The example below shows how to setup and use multiple roots based upon the set up above:</p>
\ No newline at end of file
diff --git a/manual/docs/Hierarchical data - Nested set - Tree support.php b/manual/docs/Hierarchical data - Nested set - Tree support.php
new file mode 100644
index 000000000..1a8a56c24
--- /dev/null
+++ b/manual/docs/Hierarchical data - Nested set - Tree support.php	
@@ -0,0 +1 @@
+The nested set implementation fully supports the full Doctrine tree interface
\ No newline at end of file
diff --git a/manual/documentation.php b/manual/documentation.php
index f2029c2a9..2fd548d79 100644
--- a/manual/documentation.php
+++ b/manual/documentation.php
@@ -278,14 +278,16 @@ $menu = array('Getting started' =>
                                         ),
                         ),
            'Hierarchical data' => array(
-                        'Introduction',
+                        'Introduction' => array(
+								'About', 'Setting up', 'Node interface', 'Tree interface', 'Traversing or Walking Trees', 'Read me'),
                         'Adjacency list' => array(
                                 'Introduction'),
-                        'NestedSet' => array(
-                                'Introduction'),
+                        'Nested set' => array(
+                                'Introduction', 'Setting up', 'Tree options', 'Node support', 'Tree support', 'Read me'),
                         'Materialized path' => array(
                                 'Introduction',
                                     ),
+						'Examples'
                         ),