319_complex_trees.ngdoc

@ngdoc overview
@name Tutorial: 319 Complex Trees
@description The tree feature offers a number of advanced features, care should be taken in
using these that you understand exactly what you are trying to achieve, and how to utilise
the tree to achieve that.

Firstly, aggregation.  The baseTree provides aggregation logic, this logic is used by grouping
to provide totals, averages etc.  The aggregation logic works well with grouping, as grouping
creates new blank rows into which the aggregated totals can be written.

With treeView, you can set aggregations, and that aggregation will by default be written into the entity
for the non-leaf nodes, masking (but not replacing) the data in that column for that entity.

Note also that aggregation only aggregates data from leaf nodes - a node with a $$treeLevel will not
be aggregated.

There are therefore a few options for how you use aggregation with treeView:

1.  You have a column that has data only for leaf nodes, and therefore this data can be aggregated in
the non-leaf nodes.  For example, if you were building a tree representing a file system, the files themselves
might have sizes, and you might want to aggregate these sizes to show folder size.  The folders wouldn't have
their own sizes, therefore there is an available space to write the aggregation data
2.  You create a custom column that references the same field as an existing column but has it's own
column name.  The aggregations are visible in this column, and you work some magic with the cellTemplates
to make this work as you desire
3.  You write a custom cellTemplate that shows both the value for that non-leaf node and the aggregated value in 
the same cell.  These values are in different places in the entity - the original value is in `entity.fieldName`, 
the aggregated value is in `entity.$$colUid.value` (refer to the treeBase documentation to get more details from
the aggregation such as the label or the rendered value).  You can write a cellTemplate that displays both of these.
4.  You set the `treeAggregationUpdateEntity` flag on the colDef.  The data will then be left in `row.treeNode.aggregations`
in an array form.  You need to process that array to get the data out.  You might use this if you're building 
a graph behind the scenes, or something similar.  If so, you'd probably look to get the aggregation data out
of grid.treeBase.tree, rather than extracting it from the rows.  You can access the subtree under a given
row (if you're building a graph for the selected row) through `row.treeNode`.

TreeView doesn't provide a UI for setting aggregations - unlike grouping you cannot select a column and pick an
aggregation.  You can add this UI yourself through custom menu items, but given the above comments
you need to be careful how you use it.

Aggregations are set on the columnDef or column in the format:
```
  colDef.treeAggregationType = uiGridTreeViewConstants.SUM;
```

You can provide a custom aggregation function, but note that the aggregation is performed as a running total, so
your function needs to work within that framework.  Refer the documentation for `treeAggregationFn` under
{@link api/ui.grid.treeBase.api:ColumnDef columnDef}.

You can provide a custom finalizer function, which can be used to format or otherwise complete your aggregation
once the leaf nodes under a particular node have been aggregated.  Refer the documentation for `customTreeAggregationFinalizerFn`
under {@link api/ui.grid.treeBase.api:ColumnDef columnDef}.

For better performance with the following example, you can choose to load the ui-grid.core.js and specific feature files instead:
<pre>
  <script src="/release/ui-grid.core.min.js"></script>
  <script src="/release/ui-grid.tree-base.min.js"></script>
  <script src="/release/ui-grid.tree-view.min.js"></script>
</pre>

@example
In this example the balance field is averaged, and then displayed in the standard column using a custom cellTemplate
that shows both the value for that row as well as the aggregated value.

<example module="app">
  <file name="app.js">
    var app = angular.module('app', ['ngAnimate', 'ngTouch', 'ui.grid', 'ui.grid.treeView']);

    app.controller('MainCtrl', ['$scope', '$http', '$interval', 'uiGridTreeViewConstants', function ($scope, $http, $interval, uiGridTreeViewConstants ) {
      $scope.gridOptions = {
        enableSorting: true,
        enableFiltering: true,
        columnDefs: [
          { name: 'name', width: '30%' },
          { name: 'gender', width: '20%' },
          { name: 'age', width: '20%' },
          { name: 'company', width: '25%' },
          { name: 'state', width: '35%', field: 'address.state' },
          { name: 'balance', width: '25%', treeAggregationType: uiGridTreeViewConstants.aggregation.SUM, cellFilter: 'currency', cellTemplate: '<div class="ui-grid-cell-contents" title="TOOLTIP"><span>{{row.entity.balance CUSTOM_FILTERS}}</span><span ng-if="row.entity[\'$$\' + col.uid]"> ({{row.entity["$$" + col.uid].value CUSTOM_FILTERS}})</span></div>' }
        ],
        onRegisterApi: function( gridApi ) {
          $scope.gridApi = gridApi;
          $scope.gridApi.treeBase.on.rowExpanded($scope, function(row) {
            if( row.entity.$$hashKey === $scope.gridOptions.data[50].$$hashKey && !$scope.nodeLoaded ) {
              $interval(function() {
                $scope.gridOptions.data.splice(51,0,
                  {name: 'Dynamic 1', gender: 'female', age: 53, company: 'Griddable grids', balance: 38000, $$treeLevel: 1},
                  {name: 'Dynamic 2', gender: 'male', age: 18, company: 'Griddable grids', balance: 29000, $$treeLevel: 1}
                );
                $scope.nodeLoaded = true;
              }, 2000, 1);
            }
          });
        }
      };

     $http.get('/data/500_complex.json')
     .then(function(response) {
       var data = response.data;

       for ( var i = 0; i < data.length; i++ ){
         data[i].balance = Number( data[i].balance.slice(1).replace(/,/,'') );
       }
       data[0].$$treeLevel = 0;
       data[1].$$treeLevel = 1;
       data[10].$$treeLevel = 1;
       data[20].$$treeLevel = 0;
       data[25].$$treeLevel = 1;
       data[50].$$treeLevel = 0;
       data[51].$$treeLevel = 0;
       $scope.gridOptions.data = data;
     });
 
      $scope.expandAll = function(){
        $scope.gridApi.treeBase.expandAllRows();
      };

      $scope.toggleRow = function( rowNum ){
        $scope.gridApi.treeBase.toggleRowTreeState($scope.gridApi.grid.renderContainers.body.visibleRowCache[rowNum]);
      };
    }]);
  </file>

  <file name="index.html">
    <div ng-controller="MainCtrl">
      <button id="expandAll" type="button" class="btn btn-success" ng-click="expandAll()">Expand All</button>
      <button id="toggleFirstRow" type="button" class="btn btn-success" ng-click="toggleRow(0)">Toggle First Row</button>
      <button id="toggleSecondRow" type="button" class="btn btn-success" ng-click="toggleRow(1)">Toggle Second Row</button>
      <div id="grid1" ui-grid="gridOptions" ui-grid-tree-view class="grid"></div>
    </div>
  </file>

  <file name="main.css">
    .grid {
      width: 500px;
      height: 400px;
    }
  </file>
  <file name="scenario.js">
    var gridTestUtils = require('../../test/e2e/gridTestUtils.spec.js');
    describe( '215 tree view', function() {
    });
  </file>  
</example>