Tree Data Grid
- Parent/Child Relation Dataset
- Hierarchical (Tree) Dataset
- Tree Formatter (with Collapsing icons
- Tree Custom Title Formatter
- Exporting Options (data export to Excel/Text File)
- Full List of
treeDataOptions - Filtering Options
Tree Data allows you to display a hierarchical (tree) dataset into the grid, it is visually very similar to Grouping but also very different in its implementation. A hierarchical dataset is commonly used for a parent/child relation and a great example is a Bill of Material (BOM), which you can't do with Grouping because parent/child relationship could be infinite tree level while Grouping is a defined and known level of Grouping.
For Tree Data to work with SlickGrid we need to mutate the original dataset, it will add a couple of new properties to your data, these properties are: __treeLevel, __parentId and children (these key names could be changed via the treeDataOptions). Also note that these properties become available in every Formatter (built-in and custom) which can be quite useful (especially in the tree level) in some cases... You might be thinking, could we do it without mutating the data? Probably but that would require to do a deep copy of the original data and that can be expensive on the performance side (no one it stopping you from doing a deep copy on your side though). The last thing to note is that internally for Tree Data to work, the lib always has 2 dataset (1x flat dataset and 1x hierarchical dataset which is basically a tree structure) and the lib keeps them in sync internally. So why do we do all of this? Well simply put, SlickGrid itself does not support a Tree Data structure and that is the reason we always have to keep 2 dataset structures internally because SlickGrid only works a flat dataset and nothing else.
Demo Parent/Child Relationship / Component
Hierarchial Dataset / Component
This is the most common Tree Data to use, we only use that one in our projects, and requires you to provide a key representing the relation between the parent and children (typically a parentId, which the default key when nothing is provided).
For example, we can see below is that we have a regular flat dataset with items that have a parentId property which defines the relation between the parent and child.
const dataset = [
{ id: 0, file: 'documents', parentId: null, },
{ id: 1, file: 'vacation.txt', parentId: 0, },
{ id: 2, file: 'bills.txt', parentId: 0, },
{ id: 55: file: 'music', parentId: null, },
{ id: 60, file: 'favorite-song.mp3', parentId: 55, },
{ id: 61, file: 'blues.mp3', parentId: 61, },
];For the full list of options, refer to the treeDataOptions interface
initializeGrid() {
this.columnDefinitions = [
{
id: 'title', name: 'Title', field: 'title', width: 220, cssClass: 'cell-title',
filterable: true, sortable: true,
formatter: Formatters.tree, exportCustomFormatter: Formatters.treeExport
},
// ...
};
this.gridOptions = {
enableFiltering: true, // <<-- REQUIRED, it won't work without filtering enabled
multiColumnSort: false, // <<-- REQUIRED to be Disabled since multi-column sorting is not currently supported with Tree Data
treeDataOptions: {
columnId: 'title', // the column where you will have the Tree with collapse/expand icons
parentPropName: 'parentId', // the parent/child key relation in your dataset
levelPropName: 'treeLevel', // optionally, you can define the tree level property name, it nothing is provided it will use "__treeLevel"
indentMarginLeft: 15, // optionally provide the indent spacer width in pixel, for example if you provide 10 and your tree level is 2 then it will have 20px of indentation
exportIndentMarginLeft: 4, // similar to `indentMarginLeft` but represent a space instead of pixels for the Export CSV/Excel
// you can optionally sort by a different column and/or sort direction
// this is the RECOMMENDED approach, unless you are 100% that your original array is already sorted (in most cases it's not)
initialSort: {
columnId: 'title', // which column are we using to do the initial sort? it doesn't have to be the tree column, it could be any column
direction: 'ASC'
},
},
};
}This is when your dataset is already in hierarchical (tree) structure, for example your items array already has a tree where the parents have a children property array that contains other items.
For example, we can see below the children are in the files array and the entire dataset is already in a hierarchical (tree) structure.
For the full list of options, refer to the treeDataOptions interface
const dataset = [
{ id: 0, file: 'documents', files: [
{ id: 1, file: 'vacation.txt', size: 12 },
{ id: 2, file: 'bills.txt', size: 0.5 }
]
},
{ id: 55: file: 'music', files: [
{ id: 60, file: 'favorite-song.mp3': size: 2.3 },
{ id: 61, file: 'blues.mp3', size: 5.5 }
]
},
];initializeGrid() {
this.columnDefinitions = [
{
id: 'file', name: 'Files', field: 'file',
type: FieldType.string, width: 150, formatter: this.treeFormatter,
filterable: true, sortable: true,
},
// ...
};
this.gridOptions = {
enableFiltering: true, // <<-- REQUIRED, it won't work without filtering enabled
multiColumnSort: false, // <<-- REQUIRED to be Disabled since multi-column sorting is not currently supported with Tree Data
treeDataOptions: {
columnId: 'file', // the column where you will have the Tree with collapse/expand icons
parentPropName: 'files', // the parent/child key relation in your dataset
levelPropName: 'treeLevel', // optionally, you can define the tree level property name, it nothing is provided it will use "__treeLevel"
// you can optionally sort by a different column and/or sort direction
// this is the RECOMMENDED approach, unless you are 100% that your original array is already sorted (in most cases it's not)
initialSort: {
columnId: 'size', // which column are we using to do the initial sort? it doesn't have to be the tree column, it could be any column
direction: 'DESC'
},
},
};
}The column with the Tree already has a Formatter, so how can we add our own Formatter without impacting the Tree collapse/expand icons? You can use the titleFormatter in your treeDataOptions, it will style the text title but won't impact the collapsing icons.
this.gridOptions = {
enableFiltering: true, // <<-- REQUIRED, it won't work without filtering enabled
multiColumnSort: false, // <<-- REQUIRED to be Disabled since multi-column sorting is not currently supported with Tree Data
treeDataOptions: {
columnId: 'title', // the column where you will have the Tree with collapse/expand icons
// ...
// we can also add a Custom Formatter just for the title text portion
titleFormatter: (_row, _cell, value, _def, dataContext) => {
let prefix = '';
if (dataContext.treeLevel > 0) {
prefix = `<span class="mdi mdi-subdirectory-arrow-right"></span>`;
}
return `${prefix}<span class="bold">${value}</span><span style="font-size:11px; margin-left: 15px;">(parentId: ${dataContext.parentId})</span>`;
},
},
};You would typically use the built-in Formatters.tree to show the tree but in some cases you might want to use your own Formatter and that is fine, it's like any other Custom Formatter. Here's a demo of the Example 6 Custom Formatter which is specific for showing the collapsing icon and folder and files icons.
treeFormatter: Formatter = (row, cell, value, columnDef, dataContext, grid) => {
const gridOptions = grid.getOptions() as GridOption;
const treeLevelPropName = gridOptions?.treeDataOptions?.levelPropName || '__treeLevel';
if (value === null || value === undefined || dataContext === undefined) {
return '';
}
const dataView = grid.getData() as SlickDataView;
const data = dataView.getItems();
const identifierPropName = dataView.getIdPropertyName() || 'id';
const idx = dataView.getIdxById(dataContext[identifierPropName]);
const prefix = this.getFileIcon(value);
value = value.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>');
const spacer = `<span style="display:inline-block; width:${(15 * dataContext[treeLevelPropName])}px;"></span>`;
if (data[idx + 1] && data[idx + 1][treeLevelPropName] > data[idx][treeLevelPropName]) {
const folderPrefix = `<i class="mdi icon ${dataContext.__collapsed ? 'mdi-folder' : 'mdi-folder-open'}"></i>`;
if (dataContext.__collapsed) {
return `${spacer} <span class="slick-group-toggle collapsed" level="${dataContext[treeLevelPropName]}"></span>${folderPrefix} ${prefix} ${value}`;
} else {
return `${spacer} <span class="slick-group-toggle expanded" level="${dataContext[treeLevelPropName]}"></span>${folderPrefix} ${prefix} ${value}`;
}
} else {
return `${spacer} <span class="slick-group-toggle" level="${dataContext[treeLevelPropName]}"></span>${prefix} ${value}`;
}
}Exporting the data and keeping the tree level indentation requires a few little tricks and a few options were added to configure them. First off we need a leading character on the left because Excel will trim any spaces and so if our indentation is only spaces then everything gets trimmed and so for that we reason we have the character · at the start of every text and then the indentation spaces and that won't be trimmed. Here's a few of the options available.
For the full list of options, refer to the treeDataOptions interface
/**
* Defaults to 5, indentation spaces to add from the left (calculated by the tree level multiplied by this number).
* For example if tree depth level is 2, the calculation will be (2 * 15 = 30), so the column will be displayed 30px from the left
*/
exportIndentMarginLeft?: number;
/**
* Defaults to centered dot (·), we added this because Excel seems to trim spaces leading character
* and if we add a regular character like a dot then it keeps all tree level indentation spaces
*/
exportIndentationLeadingChar?: string;
/**
* Defaults to 3, when using a collapsing icon then we need to add some extra spaces to compensate on parent level.
* If you don't want collapsing icon in your export then you probably want to put this option at 0.
*/
exportIndentationLeadingSpaceCount?: number;When using Tree Data, in most cases we will want to see the content (children) of a parent item when filtering but in some cases we might actually want to exclude them and that is what this flag is for.
The full explanation of how filter works is the following
by default (unless this feature is disabled) all child nodes of the tree will be included when a parent passes a filter and a group will be included if
1- it has any children that passes the filter or
2- current parent item passes the filter or
3- current parent item filter is the Tree column and it passes that filter criteria regardless of other criteria (this is optional via the flag autoApproveParentItemWhenTreeColumnIsValid: true)
-
- even when the other columns don't pass the filter criteria, as use case described below
-
- for example if we take the Example with File Explorer (live demo) and we filter (Files = "music" and Size > 7),
-
- then the File "Music" will always show even if it doesn't have a Size because its tree column passes the filter (which was Files = "music")
-
- and the reason we do this is that we'll be able to show music files with "Size > 7" even though these files might not include the word "music"
as described in previous paragraph on the number 3), we can auto-approve item if it's the column holding the Tree structure and is a Parent that passes the first filter criteria, in other words if we are on the column holding the Tree and its filter is valid (and is also a parent), then skip any other filter(s) that exist on the same line.
For demo purpose, let's take Example 6 live demo, if we filter with the word music on the "Files" column and also a Size that is > 15 nothing will show up unless we have this flag enabled. The reason is because none of the files have both criteria passing at the same time, however the "Files" column (which is the Tree column) does pass the filter criteria of music and so this flag will work and show the folder "music" because we skipped all other criteria, in our case > 15 on that line, note however that on the following lines (all children), it will require all filters to be valid (and so we are able to see any files under the "music" folder that have a size greater than 15Mb).
