Getting Started - part 3 - JTree and JNode

[jbruni]

Getting started? 

There is a good discussion about if the approach of this "Getting started" series is a good starting point to begginers...

In short: it MAY be a nice starting point, among many others that are possible. Possibly, this approach is very interesting to a few, while most others wish something with faster results.

Well, we all know there are as many tastes as tongues, so, you are invited to explore every other channel for learning Joomla! This one is only one.

I also invite the community to join efforts and produce more material, following the guidelines discussed in the mentioned thread.

Now you´ve been warned, let´s finish our Base subpackage detailed overview...

There is only one more file, with two classes, and we´re finished!

The file is tree.php and the classes are JTree and JNode.

[jbruni]

Maybe next subpackage/class overview won´t be detailed so much "from the inside" as "from the outside" (we shall study only the HOW TO USE aspect).

But for now let´s keep our scuba diving method.

Here is JTree class definition code (comments ripped):

Code: Select all

<?php

class JTree extends JObject
{
   var $_root = null;  // Root node
   var $_current = null;     // Current working node

   function __construct()
   {
      $this->_root = new JNode('ROOT');
      $this->_current = & $this->_root;
   }

   function addChild(&$node, $setCurrent = false)
   {
      $this->_current->addChild($node);
      if ($setCurrent) {
         $this->_current =& $node;
      }
   }

   function getParent()
   {
      $this->_current =& $this->_current->getParent();
   }

   function reset()
   {
      $this->_current =& $this->_root;
   }
}

?>

[jbruni]

Before discovering what this mysterious masterpiece snippet does, and how we should use it, we shall think about what TREE is it all about!

Certainly, it is not a Christmas tree... but a folder tree, or an XML tree, or a hierarchic content summary tree. Any hierarchic data can fit the tree that JTree class helps us to implement and gives us a padronized interface.

Each element in a tree will be called NODE.

How do we BUILD a tree and NAVIGATE thorugh its NODES with JTree and JNode classes?

First of all, remember a TREE must have a ROOT node. Yes! It is from the root node that every CHILD nodes will "grow" from.

(If you have access to the ROOT, you have access to all the tree... If you have access to your TRUE INNER SELF, your deepest root, you have access to ALL, you are enligthened!)

So, there is no tree without a root.

Another idea we must talk about is CURRENT NODE: as we NAVIGATE THROUGH the tree´s nodes, we can do something with them (for example, call a method...) The node we are working with at a given moment, THIS is called the current node. (It´s more or less like the pointer of an array.)

Finally, we shall keep in mind the CHILDREN / PARENT relationship that starts from the root. A node can have many children nodes (as a folder have its subfolders). And a node that is part of a tree always have its parent node (except the root), to which it is attached.

Now we refreshed our mind remembering this concepts, let´s go on!

[jbruni]

JTree have two private properties:

Code: Select all

   var $_root = null;  // Root node
   var $_current = null;     // Current working node

Yes, the root and the current nodes.

Both are initialized in the constructor:

Code: Select all

   function __construct()
   {
      $this->_root = new JNode('ROOT');
      $this->_current = & $this->_root;
   }

For the root is assigned a new JNode. And for the current is assigned the root. So, right after the tree is constructed, the current node is the root node.

[jbruni]

And JTree provides three methods: addChild, getParent and reset.

Code: Select all

   function addChild(&$node, $setCurrent = false)
   {
      $this->_current->addChild($node);
      if ($setCurrent) {
         $this->_current =& $node;
      }
   }

For example:

Code: Select all

<?php
$tree = new JTree;
$node = new JNode;
$tree->addChild($node, true);
?>

The addChild call will add $node as a child of the $tree root node (which was currently the current node), and, also, set the $tree current node to the added $node (as we passed true as the second parameter).

[jbruni]

The getParent method gets the parent of the current node and sets it as the current node.

Code: Select all

   function getParent()
   {
      $this->_current =& $this->_current->getParent();
   }

Be careful not to call this method when the current node is the root node! In this case, the current node will be set to null.
I ask the Dev Team: Is this the desired behavior?

Example:
$tree->getParent();

Finally, we have the reset method:

Code: Select all

   function reset()
   {
      $this->_current =& $this->_root;
   }

This is quite simple: the current node is reset to the root node.

Example:
$tree->reset();

[jbruni]

Time to go to sleep. I shall continue tomorrow with JNode class.

Keep in mind that you may extend JNode class, and then you have JTree and JNode features avaiable to make a tree from your custom object: it means, you are able to make trees from every object you want: JOranges, JApples, and so on (JNode's descendants).