Work with TreeGrid

Working with columns and cells

The API of dhtmlxTreeGrid 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
]);
// treegrid.paint();

Each column object may contain the followings fields:

  • id - (string|number) the id of a column
  • width - (number) the width of a column
  • header - (array) an array of objects with header rows configuration. Each header object may include:
    • text - (string|number) the text of a header
    • colspan - (number) the number of columns in a colspan
    • css - (any) styling to be applied to a header
    • content - (string) additional content of a header, which can be:
      • a filter: "inputFilter" or "selectFilter"
      • one of the methods that process values in a column and show result in the header: "avg" | "sum" | "max" | "min"
      • some other string
  • footer - (array) an array of objects with footer rows configuration. Each footer object may include:
    • text - (string|number) the text of a header
    • colspan - (number) the number of columns in a colspan
    • css - (any) styling to be applied to a header
    • content - (string) additional content of a header, which can be:
      • a filter: "inputFilter" or "selectFilter"
      • one of the methods that process values in a column and show result in the footer: "avg" | "sum" | "max" | "min"
      • some other string
  • maxWidth - (number) the maximal width to be set for a column
  • mark - (object|function) returns a template for marking a cell(s)
    • as an object contains min and max properties, to apply desired CSS classes to cells with minimal|maximal values in a column
    • as a function takes several parameters:
      • cell - (string) the value of a cell
      • columnCells - (array) an array of all cell values in the specified column
      • row - (object) an object with all cells in a row
      • col - (object) the config of a column (see the columns config)
  • type - (string) the type of a column: "string"|"number"|"boolean"|"any"
  • template - (function) returns a template with content for a cell(s). Takes 3 parameters:
    • cellValue - (any) the value of a cell
    • row - (object) an object with all cells in a row
    • col - (object) the config of a column (see the columns config)

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.

var 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. Such an object contains a set of fields:

  • id - (string|number) the id of a column
  • width - (number) the width of a column
  • header - (array) an array of objects with header rows configuration. Each header object may include:
    • text - (string|number) the text of a header
    • colspan - (number) the number of columns in a colspan
    • css - (any) styling to be applied to a header
    • content - (string) additional content of a header, which can be:
      • a filter: "inputFilter" or "selectFilter"
      • one of the methods that process values in a column and show result in the header: "avg" | "sum" | "max" | "min"
      • some other string
  • footer - (array) an array of objects with footer rows configuration. Each footer object may include:
    • text - (string|number) the text of a header
    • colspan - (number) the number of columns in a colspan
    • css - (any) styling to be applied to a header
    • content - (string) additional content of a header, which can be:
      • a filter: "inputFilter" or "selectFilter"
      • one of the methods that process values in a column and show result in the footer: "avg" | "sum" | "max" | "min"
      • some other string
  • maxWidth - (number) the maximal width to be set for a column
  • mark - (object|function) returns a template for marking a cell(s)
    • as an object contains min and max properties, to apply desired CSS classes to cells with minimal|maximal values in a column
    • as a function takes several parameters:
      • cell - (string) the value of a cell
      • columnCells - (array) an array of all cell values in the specified column
      • row - (object) an object with all cells in a row
      • col - (object) the config of a column (see the columns config)
  • type - (string) the type of a column: "string"|"number"|"boolean"|"any"
  • template - (function) returns a template with content for a cell(s). Takes 3 parameters:
    • cellValue - (any) the value of a cell
    • row - (object) an object with all cells in a row
    • col - (object) the config of a column (see the columns config)
  • $cellCss - (array) readonly, an array of objects with CSS classes (as key:value pairs) for each cell of a column
  • $uniqueData - (array) readonly, an array that contains some unique data, can't be redefined

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:

var 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:  Show/Hide column - DHTMLX TreeGrid

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

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 
});
// treegrid.paint();

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:

var 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");

Controlling scroll behavior

The API of dhtmlxTreeGrid 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");

Getting the state of scroll

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

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

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

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 - (object|function) the filtering criteria. It can be:
    • an object with the following attributes:
      • by - (string) 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)
          or:
    • a filtering function for setting a "global" filter for data before applying "local" filters. It takes as a parameter a data item (e.g. a row) and returns an object with a filtering rule. Works all the time, unless redefined by a different global filter or removed
  • config - (object) optional, an object with two properties:
    • add - (boolean) defines whether each next filtering will be applied to the already filtered data (true), or to the initial data (false, default)
    • multiple - (boolean) defines whether a filtering rule will be added to the already applied filters (true, default), or previous filters should be removed in advance (false)
// prefiltering grid before using separate filters for columns
treegrid.data.filter((item)=>{item.b>43&&item.a!=="Some"});
 
// 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;
    }
});

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) 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:"a",
    dir:"desc",
    as: function(item){
        item.toUpperCase(); 
    }
});

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) 
});

Editing data

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

  • row - (string) the id of a row
  • col - (string) the id of a column

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

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

Related sample:  Editing data - DHTMLX Grid

Exporting TreeGrid

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

Exporting data to Excel

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

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

Related sample:  Export - DHTMLX TreeGrid

Export settings include:

  • url - (string) the link to the server side where export will be processed. By default, it is "//export.dhtmlx.com/excel"
  • name - (string) the name of a ready Excel file

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:

  • asFile - (boolean) defines whether TreeGrid should be exported to a file, true by default. To export TreeGrid only as a CSV string, you need to set asFile:false.
  • name - (string) the name of the exported CSV file (if asFile is not set to false).
  • flat - (boolean) defines whether TreeGrid data should be exported as a flat structure. false by default.
  • rowDelimiter - (string) a newline ("\n") by default. A separator between rows, can be a tab - "\t", or any other value.
  • columnDelimiter - (string) a comma (",") by default. A separator between columns, can be a semicolon - ";", or any other value.
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:  Export - DHTMLX TreeGrid

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

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();
Back to top