Tree¶

Adding data¶

In the previous section, we used existing data and checked that it looked hierarchal via the method generateTreeList. However, usually you would add your data in exactly the same way as you would for any model. For example:

// pseudo controller code
$data['Category']['parent_id'] = 3;
$data['Category']['name'] = 'Skating';
$this->Category->save($data);

When using the tree behavior it’s not necessary to do any more than set the parent_id, and the tree behavior will take care of the rest. If you don’t set the parent_id, the tree behavior will add to the tree making your new addition a new top level entry:

// pseudo controller code
$data = array();
$data['Category']['name'] = 'Other People\'s Categories';
$this->Category->save($data);

Running the above two code snippets would alter your tree as follows:

• My Categories

  • Fun

    • Sport

      • Surfing

      • Extreme knitting

      • Skating New

    • Friends

      • Gerald

      • Gwendolyn

  • Work

    • Reports

      • Annual

      • Status

    • Trips

      • National

      • International

• Other People’s Categories New

Modifying data¶

Modifying data is as transparent as adding new data. If you modify something, but do not change the parent_id field - the structure of your data will remain unchanged. For example:

// pseudo controller code
$this->Category->id = 5; // id of Extreme knitting
$this->Category->save(array('name' => 'Extreme fishing'));

The above code did not affect the parent_id field - even if the parent_id is included in the data that is passed to save if the value doesn’t change, neither does the data structure. Therefore the tree of data would now look like:

• My Categories

  • Fun

    • Sport

      • Surfing

      • Extreme fishing Updated

      • Skating

    • Friends

      • Gerald

      • Gwendolyn

  • Work

    • Reports

      • Annual

      • Status

    • Trips

      • National

      • International

• Other People’s Categories

Moving data around in your tree is also a simple affair. Let’s say that Extreme fishing does not belong under Sport, but instead should be located under Other People’s Categories. With the following code:

// pseudo controller code
$this->Category->id = 5; // id of Extreme fishing
$newParentId = $this->Category->field(
  'id',
  array('name' => 'Other People\'s Categories')
);
$this->Category->save(array('parent_id' => $newParentId));

As would be expected the structure would be modified to:

• My Categories

  • Fun

    • Sport

      • Surfing

      • Skating

    • Friends

      • Gerald

      • Gwendolyn

  • Work

    • Reports

      • Annual

      • Status

    • Trips

      • National

      • International

• Other People’s Categories

  • Extreme fishing Moved

Deleting data¶

The tree behavior provides a number of ways to manage deleting data. To start with the simplest example; let’s say that the reports category is no longer useful. To remove it and any children it may have just call delete as you would for any model. For example with the following code:

// pseudo controller code
$this->Category->id = 10;
$this->Category->delete();

The category tree would be modified as follows:

• My Categories

  • Fun

    • Sport

      • Surfing

      • Skating

    • Friends

      • Gerald

      • Gwendolyn

  • Work

    • Trips

      • National

      • International

• Other People’s Categories

  • Extreme fishing

Querying and using your data¶

Using and manipulating hierarchical data can be a tricky business. In addition to the core find methods, with the tree behavior there are a few more tree-orientated permutations at your disposal.

class TreeBehavior

children($id = null, $direct = false, $fields = null, $order = null, $limit = null, $page = 1, $recursive = null)¶

Parameters:

• $id – The ID of the record to look up

• $direct – Set to true to return only the direct descendants

• $fields – Single string field name or array of fields to include in the return

• $order – SQL string of ORDER BY conditions

• $limit – SQL LIMIT statement

• $page – for accessing paged results

• $recursive – Number of levels deep for recursive associated Models

The children method takes the primary key value (the id) of a row and returns the children, by default in the order they appear in the tree. The second optional parameter defines whether or not only direct children should be returned. Using the example data from the previous section:

$allChildren = $this->Category->children(1); // a flat array with 11 items
// -- or --
$this->Category->id = 1;
$allChildren = $this->Category->children(); // a flat array with 11 items

// Only return direct children
$directChildren = $this->Category->children(1, true); // a flat array with
                                                      // 2 items

Note

If you want a recursive array use find('threaded')

childCount($id = null, $direct = false)¶

As with the method children, childCount takes the primary key value (the id) of a row and returns how many children it has. The second optional parameter defines whether or not only direct children are counted. Using the example data from the previous section:

$totalChildren = $this->Category->childCount(1); // will output 11
// -- or --
$this->Category->id = 1;
$directChildren = $this->Category->childCount(); // will output 11

// Only counts the direct descendants of this category
$numChildren = $this->Category->childCount(1, true); // will output 2

generateTreeList($conditions=null, $keyPath=null, $valuePath=null, $spacer= '_', $recursive=null)¶

Parameters:

• $conditions – Uses the same conditional options as find().

• $keyPath – Path to the field to use for the key, i.e. “{n}.Post.id”.

• $valuePath – Path to the field to use for the label, i.e. “{n}.Post.title”.

• $spacer – The string to use in front of each item to indicate depth.

• $recursive – The number of levels deep to fetch associated records

This method will return data similar to find(‘list’) but with a nested prefix that is specified in the spacer option to show the structure of your data. Below is an example of what you can expect this method to return:

$treelist = $this->Category->generateTreeList();

Output:

array(
    [1] =>  "My Categories",
    [2] =>  "_Fun",
    [3] =>  "__Sport",
    [4] =>  "___Surfing",
    [16] => "___Skating",
    [6] =>  "__Friends",
    [7] =>  "___Gerald",
    [8] =>  "___Gwendolyn",
    [9] =>  "_Work",
    [13] => "__Trips",
    [14] => "___National",
    [15] => "___International",
    [17] => "Other People's Categories",
    [5] =>  "_Extreme fishing"
)

formatTreeList($results, $options=array())¶

New in version 2.7.

Parameters:

• $results – Results of a find(‘all’) call.

• $options – Options to pass into.

This method will return data similar to find(‘list’) but with a nested prefix that is specified in the spacer option to show the structure of your data.

Supported options are:

• keyPath: A string path to the key, i.e. “{n}.Post.id”.

• valuePath: A string path to the value, i.e. “{n}.Post.title”.

• spacer: The character or characters which will be repeated.

An example would be:

$results = $this->Category->find('all');
$results = $this->Category->formatTreeList($results, array(
    'spacer' => '--'
));

getParentNode()¶

This convenience function will, as the name suggests, return the parent node for any node, or false if the node has no parent (it’s the root node). For example:

$parent = $this->Category->getParentNode(2); //<- id for fun
// $parent contains All categories

getPath($id = null, $fields = null, $recursive = null)¶

The ‘path’ when referring to hierarchal data is how you get from where you are to the top. So for example the path from the category “International” is:

• My Categories

  • …

  • Work

  • Trips

    • …

    • International

Using the id of “International” getPath will return each of the parents in turn (starting from the top).

$parents = $this->Category->getPath(15);

// contents of $parents
array(
    [0] =>  array(
      'Category' => array('id' => 1, 'name' => 'My Categories', ..)
    ),
    [1] =>  array(
      'Category' => array('id' => 9, 'name' => 'Work', ..)
    ),
    [2] =>  array(
      'Category' => array('id' => 13, 'name' => 'Trips', ..)
    ),
    [3] =>  array(
      'Category' => array('id' => 15, 'name' => 'International', ..)
    ),
)