How to show tree structure?

The Tree module is needed to show tree structure in Gridx:

var grid = new Grid({
     ......
     modules: [
          "gridx/modules/Tree"
     ],
     ......
});

But that's not enough, let's see what else should/could be done.

Prepare the Store

If your store does not support tree data, then neither does Gridx. Every tree store for Gridx should implement the following two methods:

store.hasChildren = function(id, item){
               // summary:
               //          Check whether a row has child rows. This function should not throw any error.
               // id: String|Number
               //          The row ID
               // item: Object
               //          The store item
               // returns:
               //          True if the given row has children, false otherwise.
};

store.getChildren = function(item){
               // summary:
               //          Get an array of the child items of the given row item.
               // item: Object
               //          The store item
               // returns:
               //          An array of the child items of the given row item.
};

The hasChildren function should always work synchronously. Gridx need this function to tell whether a row has child rows. If you are using dojo/store/Memory and all the children data are stored are directly put a "children" field of every item, then this function could be written as:

store.hasChildren = function(id, item){
     // we should be very careful here, because hasChildren should not throw.
     return item && item.children && item.children.length; 
};

The getChildren function should return an array of child items. But if your child data are on server, you might need to operate asynchronously here by returning a Deferred object:

store.getChildren = function(item){
     var d = new Deferred();
     // Suppose the child rows won't be ready until 2 seconds later.
     setTimeout(function(){
          d.callback([....]);
     }, 2000);
     return d;
};

If you are just ordinary user, you can stop here because your tree grid is already working. If you need more advanced configurations, please move on.

Decide where to put the expandoes

With the store ready, you can already run your tree grid. If you don't provide other parameters, all the expandoes will be in the first column:

What if you want the expansoes to appear somewhere else? Actually you can explicitly declare this in your column structure:

structure = [
          {id: 'id', name: 'id', field: 'id'},
          {id: 'number', name: 'number', field: 'number', expandLevel: 'all'},
          {id: 'string', name: 'string', field: 'string'},
          {id: 'date', name: 'date', field: 'date'},
          {id: 'time', name: 'time', field: 'time'},
          {id: 'bool', name: 'bool', field: 'bool'}
];

expandLevel means what level of expando should this column show. The root level is 1, the second is 2, and so on. All other values for this parameter means "all levels". But since we haven't set "treeNested" to true, all we need is a true value here.

Now the expandoes are moved to the 2nd column:

Just now I mentioned treeNested parameter, which might make you confused. This is parameter of Tree module, but you can directly declare it as grid parameter:

var grid = new Grid({
    modules: ["gridx/modules/Tree"],
    treeNested: true
});

By default this is set to false and all expandoes are put in one column. If it is set to true, then different levels of expandoes will be put in different columns:

Users can also explicitly declare which columns should the expandoes be shown:

structure = [
          {id: 'id', name: 'id', field: 'id', expandLevel: 1},
          {id: 'number', name: 'number', field: 'number'},
          {id: 'string', name: 'string', field: 'string', expandLevel: 2},
          {id: 'date', name: 'date', field: 'date'},
          {id: 'time', name: 'time', field: 'time', expandLevel: 3},
          {id: 'bool', name: 'bool', field: 'bool'}
];

As introduced before, the "id" column here will show root level expandoes, and the "string" column the second level, the "time" column the third:

[to be continue...]