Work with Grid
Working with columns and cells
The API of DHTMLX Grid 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 Grid columns on the fly via the setColumns() method. It takes an array with columns objects as a parameter.
grid.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 Grid 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 = grid.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 = grid.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
grid.showColumn(colId);
//hiding a column
grid.hideColumn(colId);
Related sample: Grid. 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 hidden, and false if it's visible.
grid.isColumnHidden("country"); // -> true|false
Related sample: Grid. Is column hidden
Getting header filter
You may want to manipulate a filter specified in the header of a grid, 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
grid.getHeaderFilter("country").setValue("Brazil");
// set focus on the filter
grid.getHeaderFilter("country").focus();
// remove focus from the filter
grid.getHeaderFilter("country").blur();
// get an object of the filter
const filter = grid.getHeaderFilter("country").getFilter();
console.log(filter);
// -> returns Combobox
// {config: {…}, _uid: 'u1670500020936', events: o, data: d, popup: f, …}
// clear the value set in the filter
grid.getHeaderFilter("country").clear();
Related sample: Grid. Get header filter
Working with rows
Adding/removing a row
Adding a row
You may add a new row into the grid by using the add() method of DataCollection:
grid.data.add({
"country": "Estonia",
"population": "1326535",
"yearlyChange": "0.0070",
"netChange": "3782",
"density": "31",
"area": "45339",
"migrants": "3911",
"fert": "1.59",
"age": "42.4",
"urban": "0.6790",
"id": "136"
}, 0);
Removing a row
To remove the necessary row from the grid, apply the remove() method of DataCollection. Pass the id of the row that should be removed to the method:
grid.data.remove("5");
Here is an example of removing a currently selected row:
const cell = grid.selection.getCell();
grid.data.remove(cell.row.id);
Related sample: Grid. Delete row
For more information about the selection functionality in Grid, 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 DataCollection:
grid.data.removeAll();
Hiding/showing a row
Starting from v7.0, it is possible to show and hide a row in the grid via the showRow() and hideRow() methods.
//showing a row
grid.showRow(rowId);
//hiding a row
grid.hideRow(rowId);
Related sample:Grid. 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.
grid.isRowHidden("1"); // -> true|false
Related sample: Grid. Show / hide row
Adding/removing spans
You can manipulate columns and rows spans inside the grid with the help of the corresponding API methods: addSpan(), removeSpan() and getSpan().
Adding spans
In order to add a column/row span into the grid, use the addSpan() method. Pass an object with configuration of a span as a parameter:
grid.addSpan({
row: "0",
column: "a",
rowspan: 5
});
// grid.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 column/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 = grid.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:
grid.removeSpan("10", "a");
Working with data
Filtering data
You can filter grid data by the specified criteria with the help of the filter() method of DataCollection. The method takes as a parameter an object with the properties described below:
| rule | (object|function) the filtering criteria. It can be:
|
| config | (object) optional, an object with the following properties:
|
grid.data.filter(function (item) {
return item.a > 0 && item.b !== "Apple";
});
grid.data.filter(function (item) {
return item.a > 0 && item.b !== "Apple";
}, {
add: true
});
grid.data.filter({
by: "a",
match: "Orange",
compare: function (value, match, item) {
if (item.a !== "Some") {
return val === "New";
}
return false;
}
}, {
add: true,
});
Related sample: Grid. Basic filter
Sorting data
It is possible to sort data in the grid via the sort() method of DataCollection. The method takes two parameters:
| rule | (object) an object with parameters for sorting. It can take the following attributes:
|
| config | (object) defines the parameter of sorting. It takes one attribute:
|
grid.data.sort({
by:"a",
dir:"desc",
as: function(item){
return item.toUpperCase();
},
{
smartSorting: true
}
});
Related sample: Grid. Sorting
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:
grid.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 Grid, 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 grid is sorted by |
const state = grid.getSortingState();
// -> { dir: "desc", by: "country" }
Related sample: Grid. Get sorting state
Editing data
You can easily edit the desired cell of a grid with the help of the editCell() method. It takes two parameters:
| rowId | (string, number) the id of a row |
| colId | (string, number) the id of a column |
For example, you can edit the first cell of the "project" column like this:
grid.editCell(grid.data.getId(0), "project");
Related sample: Grid. Edit the 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).
grid.editEnd(); // the edited data will be saved
grid.editEnd(true); // the edited data won't be saved
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 Grid into the Excel, CSV, PDF, or PNG format.
Exporting data to Excel
DHTMLX Grid provides the possibility to export data from Grid into an Excel file by calling the xlsx() method of the Export module. The method takes an object with export settings as a parameter.
grid.export.xlsx({
name:"grid_data",
url: "//export.dhtmlx.com/excel"
});
Related sample: Grid. Export to xlsx and csv
Exporting data to CSV
You can export data from Grid to the CSV format with the csv() method of the Export module.
grid.export.csv({
name:"grid_data", // grid data will be exported to a CSV file named "grid_data"
rowDelimiter: "\t", // the tab delimiter will be used to separate rows
columnDelimiter: ";" // the semicolon delimiter will be used to separate columns
});
Related sample: Grid. Export to xlsx and csv
The csv() method returns a CSV string with Grid data.
Exporting data to PDF
The pdf() method of the Export module allows you to export data from Grid into a PDF file. The method takes an object with export settings as a parameter.
grid.export.pdf({
format: "A4",
scale: 0.75,
displayHeaderFooter: true,
theme: "dark",
});
Related sample: Grid. Export to PDF/PNG
Exporting data to PNG
The png() method of the Export module allows you to export data from Grid into a PNG file. The method takes an object with export settings as a parameter.
grid.export.png({
theme: "dark",
});
Related sample: Grid. Export to PDF/PNG
Controlling scroll behavior
The API of DHTMLX Grid provides the possibility to set scrolls to the necessary 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.
grid.scroll(75, 230);
Scrolling to specific grid cell
It is also possible to scroll grid content to a particular cell. Pass the ids of the row and the column as parameters:
grid.scrollTo("15", "c");
Related sample: Grid. Controlling scroll behavior
Getting the state of scroll
To return the current state of scroll, use the getScrollState() method.
const state = grid.getScrollState(); // -> {x:0, y:0}
It returns an object with x,y coordinates of a position the grid has been scrolled to.
Repainting Grid
In case you've changed some configuration settings of a grid, you can repaint it on a page via the paint() method:
grid.paint();
Destructing Grid
When it's necessary to release resources occupied by Grid during its activity, you can make use of the destructor() method:
grid.destructor();
Using Selection API
For information on using Selection API, read Work with Selection Object.