Skip to main content

Work with TreeGrid

Working with columns and cells

The API of DHTMLX TreeGrid allows setting configuration of columns, getting an object of a particular column as well as the parameters of a certain cell.

Setting columns configuration

You can specify the configuration of TreeGrid columns on the fly via the setColumns method. It takes an array with columns objects as a parameter.

treegrid.setColumns([
{ id: "a", header: [{ text: "New header for column a" }] },
{ id: "b", header: [{ text: "New header for column b" }] },
// more columns objects
]);

You can find the full list of the available configuration options of a TreeGrid column here.

Getting configuration of a column

It is possible to return an object with attributes of a column via its id. Use the getColumn() method for this purpose.

const column = treegrid.getColumn("b"); // ->
// {width: 100, id: "b", header: Array(1), $cellCss: {…}, type: "string"

The method returns an object with configuration of the specified column. You can find the list of properties that the return object can contain here.

Getting configuration of a cell

There is the getCellRect() method that returns an object with coordinates of a cell. The method takes as parameters the ids of the row and the column the cell belongs to:

const rect = treegrid.getCellRect("1","c");
// -> {x: 200, y: -40, height: 40, width: 200}

The return object includes the following attributes:

x(number) the X coordinate of a cell
y(number) the Y coordinate of a cell
height(number) the height of a cell
width(number) the width of a cell

Hiding/showing a column

It is possible to show and hide a column in the grid via the showColumn() and hideColumn() methods.

//showing a column
treegrid.showColumn(col);
//hiding a column
treegrid.hideColumn(col);

Related sample: TreeGrid. Show/hide column

Since the object of a column has the hidden property, the showColumn() method changes the value of the hidden property to false while the hideColumn() method changes the value of the property to true.

Checking visibility of a column

You can check whether a column is hidden or shown on a page using the isColumnHidden() method. The method returns true, if a column is visible, and false if it's hidden.

treegrid.isColumnHidden("country"); // -> true|false

Related sample: TreeGrid. Is column hidden

Getting header filter

You may want to manipulate a filter specified in the header of a treegrid, for example, to set/unset focus on the filter, to change the filter, or clear it. To do that, you should apply the getHeaderFilter() method to get an object with methods of the header filter and apply the necessary method. For example:

// set a value by which a column will be filtered
treegrid.getHeaderFilter("name").setValue("Brazil");

// set focus on the filter
treegrid.getHeaderFilter("name").focus();

// remove focus from the filter
treegrid.getHeaderFilter("name").blur();

// get an object of the filter
const filter = treegrid.getHeaderFilter("name").getFilter();
console.log(filter);
// -> returns Combobox
//  {config: {…}, _uid: 'u1670576316762', events: o, data: d, popup: f, …}

// clear the value set in the filter
treegrid.getHeaderFilter("name").clear();

Related sample: TreeGrid. Get header filter

Working with rows

Adding/removing a row

Adding a row

You may add a new row into the treegrid by using the add() method of TreeCollection:

treegrid.data.add({
"name": "The Daughter of the Commandant",
"price": "6.99",
"cover": "Paperback",
"ships": "24 hours",
"inStock": "3 <input type='checkbox' checked />",
"parent": "c.3"
});

Removing a row

To remove the necessary row from the treegrid, apply the remove() method of TreeCollection. Pass the id of the row that should be removed to the method:

treegrid.data.remove("5");

Here is an example of removing a currently selected row:

const cell = treegrid.selection.getCell();
treegrid.data.remove(cell.row.id);

Related sample: TreeGrid. Delete row

For more information about the selection functionality in TreeGrid, read the Selection and Work with selection object articles.

Removing all rows

If you need to remove all rows at once, use the removeAll() method of TreeCollection:

treegrid.data.removeAll();

Hiding/showing a row

Starting from v7.0, it is possible to show and hide a row in the treegrid via the showRow() and hideRow() methods.

//showing a row
treegrid.showRow(rowId);
//hiding a row
treegrid.hideRow(rowId);

Related sample: TreeGrid. Show / hide row

Checking visibility of a row

You can check whether a row is hidden or shown on a page using the isRowHidden() method. The method returns true, if a row is hidden, and false if it's visible.

treegrid.isRowHidden("1"); // -> true|false

Related sample: TreeGrid. Show / hide row

Adding/removing spans

You can manipulate columns and rows spans inside the grid with the help of corresponding API methods: addSpan(), removeSpan() and getSpan().

Adding spans

In order to add a col/row span into the grid, use the addSpan() method. Pass an object with configuration of a span as a parameter:

treegrid.addSpan({ 
row: "0",
column: "a",
rowspan: 5
});

These are possible fields of a span object:

row(string|number) mandatory, the id of a row
column(string|number) mandatory, the id of a column
rowspan(number) optional, the number of rows in a span
colspan(number) optional, the number of columns in a span
text(string|number) optional, the text in a spanned row/column
css(string) optional, the name of the CSS class that will be applied to a span

Getting spans

You can return the col/row span a cell is a part of using the getSpan() method. It takes the ids of the row and the column the cell belongs to as parameters:

const span = treegrid.getSpan("10","a"); 
// -> {row:"10", column:"a", colspan:4, text:"Some header", css:"myCustomColspan"}

As a result, you'll get an object with a span configuration, if any span includes the specified cell. Attributes of a span object are described above.

Removing spans

To remove an existing span, make use of the removeSpan() method. It takes the ids of the row and the column as parameters:

treegrid.removeSpan("10","a");

Working with data

Grouping data

To make data in TreeGrid well-structured and easily understood you can group data with the help of the groupBy() method. There are two options of grouping data.

Grouping by a column

To group the content of a treegrid by values of the specified column, pass the id of the column as a parameter to the groupBy() method:

  • id - (string, number) the id of a column
treegrid.groupBy("age");

Related sample: TreeGrid. Group data items by a property

Grouping by the result of calculation

You can pass a function with a rule of grouping data in the treegrid as a parameter to the groupBy() method. The function returns the name of a group and takes one parameter:

  • item - a data item
treegrid.groupBy(function (item) {
if (!item.area || item.area < 0) {
return "N.A.";
}
if (item.area < 25000) {
return "Small";
} else if (item.area < 60000) {
return "Medium";
}
return "Big";
});

Related sample: TreeGrid. Group data items by a property

If necessary, you can set a template to the title of the group via the groupTitleTemplate configuration option.

Filtering data

You can filter grid data by the specified criteria with the help of the filter() method of data collection. The method takes as a parameter an object with the properties described below:

rule(function | object) the filtering criteria. It can be:
  • a filtering function. It takes as a parameter a data item and returns true/false
  • or:
  • an object with the following attributes:
    - by - (string | number) mandatory, the id of a column
    - match - (string) mandatory, a pattern to match
    - compare - (function) a function for extended filtering that takes three parameters:
      - value - the value to compare (e.g. a column in a row)
      - match - a pattern to match
      - item - a data item the values of which should be compared (e.g. a row)
config(object) optional, an object with the following properties:
  • type (string) optional, defines the area the filtering will be applied: "all", "level", "leafs"
  • level (number) optional, the level the filtering will be applied to
  • add (boolean) optional, defines whether each next filtering will be applied to the already filtered data (true), or to the initial data (false, default)
  • id (string) optional, the id of the filter
  • permanent (boolean) - optional, true to make the current filter permanent. It will be applied even if the next filtering doesn't have the add:true property in its configuration object. Such a filter can be removed just with the resetFilter() method

// filtering by the specified rule
tree.data.filter(function (item) {
return item.value.toLowerCase().indexOf("a") !== -1;
});

// filtering the "b" column by value "Tyro"
treegrid.data.filter({ by:"b", match:"Tyro" });

// filtering data by several criteria at once
treegrid.data.filter({
by:"b",
compare:function(val,match,item){
if(item.a!=="Some"){
return val === "New"
}
return false;
}
});

Related sample: TreeGrid. Filter

Related sample: TreeGrid. External filter

Sorting data

It is possible to sort data in the grid via the sort() method of data collection. The method takes an object with the following attributes:

by(string | number) the id of a column
dir(string) the direction of sorting "asc" or "desc"
as(function) a function that specifies the type to sort data as

treeGrid.data.sort({
by: "price",
dir: "asc",
as: function (value) { return value ? value : "" }
});

Related sample: TreeGrid. Sorting

To discard all applied sorting rules, call the method without parameters:

treegrid.data.sort();

Custom sorting

You can also specify the rule attribute in a passed object instead of the default ones and set a custom function for sorting. For example:

treegrid.data.sort({
rule: (a, b) => a.id > b.id ? 1 : (a.id < b.id ? -1 : 0)
});

Getting the sorting state

To get the current state of sorting data in TreeGrid, use the getSortingState() method. The method returns an object with two attributes:

dir(string) the sorting direction (desc, asc)
by(string | number)the id of a column that the treegrid is sorted by

const state = treegrid.getSortingState(); 
// -> {dir: "desc", by: "country"}

Related sample: TreeGrid. Get sorting state

Editing data

You can easily edit the desired cell of a treegrid with the help of the editCell() method. It takes two parameters:

row(string, number) the id of a row
col(string, number) the id of a column
editorType(string) optional, the type of an editor used in a cell: "input"|"select"|"datePicker"|"checkbox"|"combobox"|"textarea"|"multiselect"

For example, you can edit the first cell of the "project" column like this:

treegrid.editCell(grid.data.getId(0),"project");

Related sample: TreeGrid. Edit first cell

To finish editing of a cell, use the editEnd() method. The method takes a boolean value as a parameter to define whether the edited data will be saved after the editing of a cell is complete (if true, the made changes won't be saved).

treegrid.editEnd(); // the edited data will be saved

treegrid.editEnd(true); // the edited data won't be saved
note

The editEnd() method does not work if the type of the column editor is defined as checkbox.

Exporting data

You can easily export data of TreeGrid into the Excel, CSV, PDF or PNG format.

Exporting data to Excel

DHTMLX TreeGrid provides the possibility to export data from TreeGrid into an Excel file by calling the xlsx() method of the export module. The method takes an object with export settings as a parameter.

treegrid.export.xlsx({
url: "//export.dhtmlx.com/excel"
});

Related sample: TreeGrid. Export to .xlsx and .csv

Exporting data to CSV

You can export data from TreeGrid to the CSV format with the csv() method of the Export module. The method takes an object with export settings as a parameter.

treegrid.export.csv({
name:"treegrid_data", // data will be exported to a CSV file named "treegrid_data"
rowDelimiter: "\t", // the tab delimiter will be used to separate rows
columnDelimiter: ";" // the semicolon delimiter will be used to separate columns
});

Related sample: TreeGrid. Export to .xlsx and .csv

The csv() method returns a CSV string with TreeGrid data.

Exporting data to PDF

The pdf() method of the Export module allows you to export data from TreeGrid into a PDF file. The method takes an object with export settings as a parameter.

treegrid.export.pdf({
format: "A4",
scale: 0.85,
displayHeaderFooter: true,
theme: "dark",
});

Related sample: TreeGrid. Export to PDF/PNG

Exporting data to PNG

The png() method of the Export module allows you to export data from TreeGrid into a PNG file. The method takes an object with export settings as a parameter.

treegrid.export.pdf({
theme: "dark",
});

Related sample: TreeGrid. Export to PDF/PNG

Expanding/collapsing nodes

Expand/collapse a certain node

To expand a particular node in a treegrid by its id, use the expand() method:

treegrid.expand("native");

To collapse a treegrid node, make use of the collapse() method:

treegrid.collapse("native");

Related sample: TreeGrid. Expand / collapse rows

Expand/collapse all nodes

It is also possible to expand/collapse all TreeGrid nodes using the two corresponding methods - expandAll() and collapseAll():

// expand all treegrid nodes
treegrid.expandAll();
// collapse all treegrid nodes
treegrid.collapseAll();

Related sample: TreeGrid. Expand / collapse rows

Controlling scroll behavior

The API of DHTMLX TreeGrid provides the possibility to set scrolls to the nevessary position and to get the current state of scrolls.

Scrolling to specific coordinates

You can scroll grid content to exact position defined by x and y coordinates via the scroll() method. Pass the coordinates as parameters of the method.

treegrid.scroll(75,230);

Scrolling to specific treegrid cell

It is also possible to scroll treegrid content to a particular cell. Pass the ids of the row and the column as parameters:

treegrid.scrollTo("15","c");

Related sample: TreeGrid. Controlling scroll behavior

Getting the state of scroll

To return the current state of scroll, use the getScrollState() method.

const state = treegrid.getScrollState(); // -> {x:0,y:0}

It returns an object with x,y coordinates of a position the grid has been scrolled to.

Repainting TreeGrid

In case you've changed some configuration settings of a treegrid, you can repaint it on a page via the paint() method:

treegrid.paint();

Destructing TreeGrid

When it's necessary to release resources occupied by TreeGrid during its activity, you can make use of the destructor() method:

treegrid.destructor();

Using selection API

For information on using Selection API, read Work with Selection Object.