JavaScript/jQuery DataGrid - columns
By default, a column is created for each field of a data source object, but in most cases, it is redundant. To specify a set of columns to be created in a grid, assign an array specifying these columns to the columns option. Each grid column is represented in this array by an object containing column settings or by a data source field that this column is bound to. Detailed information on specifying grid columns is given in the Columns Overview article.
Column options define the behavior and appearance of a grid column. One of the other capabilities allows you to control the sorting of column values using the allowSorting and sortOrder options, apply a filter to grid records using the allowFiltering and filterOperations options, and group grid records using the allowGrouping and groupIndex options. In addition, you can change the visibility and width of a column using corresponding options.
To get or set an option or several options for a column at runtime, use the columnOption method with the required arguments.
See Also
alignment
The default alignment of the content depends on the type of data.
dataType | alignment |
---|---|
'number' | 'right' |
'boolean' | 'center' |
'string' | 'left' |
'date' | 'left' |
'datetime' | 'left' |
Use the HorizontalAlignment
enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: Left
, Center
, and Right
.
allowEditing
Specifies whether a user can edit values in the column at runtime. By default, inherits the value of the editing.allowUpdating option.
See Also
allowExporting
Specifies whether data from this column should be exported. Applies only if the column is visible.
allowFiltering
Specifies whether data can be filtered by this column. Applies only if filterRow.visible is true.
allowFixing
Specifies whether a user can fix the column at runtime. Applies only if columnFixing.enabled is true.
allowGrouping
Specifies whether the user can group data by values of this column. Applies only when grouping is enabled.
When grouping is enabled in the widget, the user can group data by values of any column. To prohibit a particular column from being used for grouping, set the allowGrouping option of this column to false.
See Also
allowHeaderFiltering
Specifies whether the header filter can be used to filter data by this column. Applies only if headerFilter.visible is true. By default, inherits the value of the allowFiltering option.
allowHiding
Specifies whether a user can hide the column using the column chooser at runtime. Applies only if columnChooser.enabled is true.
allowReordering
Specifies whether this column can be used in column reordering at runtime. Applies only if allowColumnReordering is true.
allowResizing
Specifies whether a user can resize the column at runtime. Applies only if allowColumnResizing is true.
allowSearch
Specifies whether this column can be searched. Applies only if searchPanel.visible is true. Inherits the value of the allowFiltering option by default.
allowSorting
Specifies whether a user can sort rows by this column at runtime. Applies only if sorting.mode differs from "none".
autoExpandGroup
Specifies whether groups appear expanded or not when records are grouped by a specific column. Setting this option makes sense only when grouping is allowed for this column.
buttons[]
Allows you to customize buttons in the edit column or create a custom command column. Applies only if the column's type is "buttons".
calculateCellValue
Unlike data columns bound to a data field, unbound columns display custom values returned from the calculateCellValue function. It is called each time a new row is rendered.
In the following code, the calculateCellValue function is used to create an unbound column that displays a calculated sales amount. Data objects contain the Price
and UnitsSold
fields used in the calculation:
jQuery
var products = [{ ProductID: 1, ProductName: "Fabrikam SLR Camera 35\" X358 Blue", Price: 168, UnitsSold: 4 }, // ... ]; $(function() { $("#dataGridContainer").dxDataGrid({ dataSource: products, columns: [{ caption: "Sales Amount", calculateCellValue: function(rowData) { return rowData.Price * rowData.UnitsSold; } }, // ... ] }); });
Angular
<dx-data-grid [dataSource]="products"> <dxi-column caption="Sales Amount" [calculateCellValue]="calculateSalesAmount"> </dxi-column> </dx-data-grid>
import { Component } from '@angular/core'; import { Product, Service } from './app.service'; @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { products: Product[]; constructor(service: Service) { this.products = service.getProducts(); } calculateSalesAmount(rowData) { return rowData.Price * rowData.UnitsSold; } }
import { Injectable } from '@angular/core'; export class Product { ProductID: number, ProductName: string, Price: number, UnitsSold: number } let products: Product[] = [{ ProductID: 1, ProductName: "Fabrikam SLR Camera 35\" X358 Blue", Price: 168, UnitsSold: 4 }, // ... ]; @Injectable() export class Service { getProducts(): Product[] { return products; } }
import { BrowserModule } from '@angular/platform-browser'; import { NgModule } from '@angular/core'; import { AppComponent } from './app.component'; import { DxDataGridModule } from 'devextreme-angular'; import { Service } from './app.service'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, DxDataGridModule ], providers: [ Service ], bootstrap: [AppComponent] }) export class AppModule { }
Vue
<template> <DxDataGrid :data-source="products"> <DxColumn caption="Sales Amount" :calculate-cell-value="calculateSalesAmount"> </DxColumn> </DxDataGrid> </template> <script> import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DxDataGrid, { DxColumn } from 'devextreme-vue/data-grid'; import service from './data.js'; export default { components: { DxDataGrid, DxColumn }, data() { const products = service.getProducts(); return { products } }, methods: { calculateSalesAmount(rowData) { return rowData.Price * rowData.UnitsSold; } } } </script>
const products = [{ ProductID: 1, ProductName: "Fabrikam SLR Camera 35\" X358 Blue", Price: 168, UnitsSold: 4 }, // ... ]; export default { getProducts() { return products; } };
React
import React from 'react'; import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DataGrid, { Column } from 'devextreme-react/data-grid'; import service from './data.js'; class App extends React.Component { constructor(props) { super(props); this.products = service.getProducts(); } calculateSalesAmount(rowData) { return rowData.Price * rowData.UnitsSold; } render() { return ( <DataGrid dataSource={this.products}> <Column caption="Sales Amount" calculateCellValue={this.calculateSalesAmount} /> </DataGrid> ); } } export default App;
const products = [{ ProductID: 1, ProductName: "Fabrikam SLR Camera 35\" X358 Blue", Price: 168, UnitsSold: 4 }, // ... ]; export default { getProducts() { return products; } };
The following features are disabled in an unbound column, but you can enable them as described in this table:
Feature | Action that enables it |
---|---|
Editing | Implement the setCellValue function. |
Sorting | Set the allowSorting option to true. |
Filtering | Set the allowFiltering option to true. |
Searching | Set the allowSearch option to true. |
Grouping (DataGrid only) | Set the allowGrouping option to true. |
To invoke the default behavior, call the defaultCalculateCellValue function and return its result.
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ columns: [{ calculateCellValue: function(rowData) { // ... return this.defaultCalculateCellValue(rowData); } }] }); });
Angular
import { Component } from '@angular/core'; @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { calculateCellValue(rowData) { // ... const column = this as any; return column.defaultCalculateCellValue(rowData); } }
<dx-data-grid ... > <dxi-column ... [calculateCellValue]="calculateCellValue"> </dxi-column> </dx-data-grid>
Vue
<template> <DxDataGrid ... > <DxColumn ... :calculate-cell-value="calculateCellValue"> </DxColumn> </DxDataGrid> </template> <script> // ... export default { // ... methods: { calculateCellValue(rowData) { // ... const column = this as any; return column.defaultCalculateCellValue(rowData); } } } </script>
React
// ... class App extends React.Component { calculateCellValue(rowData) { // ... const column = this as any; return column.defaultCalculateCellValue(rowData); } render() { return ( <DataGrid ... > <Column ... calculateCellValue={this.calculateCellValue} /> </DataGrid> ); } } export default App;
this
keyword refers to the column's configuration.See Also
- columns[].customizeText
- columns[].calculateDisplayValue
calculateDisplayValue
Calculates custom display values for column cells. Requires specifying the dataField or calculateCellValue option. Used in lookup optimization.
This option accepts the name of the data source field that provides display values...
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ columns: [{ dataField: "countryID", // provides values for editing calculateDisplayValue: "country" // provides display values }] }); });
Angular
<dx-data-grid ... > <dxi-column dataField="countryID" <!-- provides values for editing --> calculateDisplayValue="country"> <!-- provides display values --> </dxi-column> </dx-data-grid>
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
Vue
<template> <DxDataGrid> <DxColumn data-field="countryID" <!-- provides values for editing --> calculate-display-value="country"> <!-- provides display values --> /> </DxDataGrid> </template> <script> import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DxDataGrid, { DxColumn } from 'devextreme-vue/data-grid'; export default { components: { DxDataGrid, DxColumn }, // ... } </script>
React
import React from 'react'; import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DataGrid, { Column } from 'devextreme-react/data-grid'; class App extends React.Component { // ... render() { return ( <DataGrid> <Column dataField="countryID" <!-- provides values for editing --> calculateDisplayValue="country" <!-- provides display values --> /> </DataGrid> ); } } export default App;
ASP.NET MVC Controls
@(Html.DevExtreme().DataGrid() .Columns(columns => columns.Add() .DataField("CountryID") .CalculateDisplayValue("Country") ) )
@(Html.DevExtreme().DataGrid() _ .Columns(Sub(columns) columns.Add() _ .DataField("CountryID") _ .CalculateDisplayValue("Country") End Sub) )
... or a function that combines display values. Specify this function only if all data processing operations are executed on the client.
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ columns: [{ dataField: "countryID", // provides values for editing calculateDisplayValue: function (rowData) { // combines display values return rowData.capital + " (" + rowData.country + ")"; } }] }); });
Angular
<dx-data-grid ... > <dxi-column dataField="countryID" <!-- provides values for editing --> [calculateDisplayValue]="getCountryWithCapital"> <!-- combines display values --> </dxi-column> </dx-data-grid>
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { getCountryWithCapital(rowData) { return rowData.capital + " (" + rowData.country + ")"; } } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
Vue
<template> <DxDataGrid> <DxColumn data-field="countryID" <!-- provides values for editing --> :calculate-display-value="getCountryWithCapital" <!-- combines display values --> /> </DxDataGrid> </template> <script> import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DxDataGrid, { DxColumn } from 'devextreme-vue/data-grid'; export default { components: { DxDataGrid, DxColumn }, methods: { getCountryWithCapital(rowData) { return rowData.capital + " (" + rowData.country + ")"; } } } </script>
React
import React from 'react'; import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DataGrid, { Column } from 'devextreme-react/data-grid'; class App extends React.Component { // ... render() { return ( <DataGrid> <Column dataField="countryID" <!-- provides values for editing --> calculateDisplayValue={this.getCountryWithCapital} <!-- combines display values --> /> </DataGrid> ); } getCountryWithCapital(rowData) { return rowData.capital + " (" + rowData.country + ")"; } } export default App;
ASP.NET MVC Controls
@(Html.DevExtreme().DataGrid() .Columns(columns => columns.Add() .DataField("CountryID") .CalculateDisplayValue(new JS("getCountryWithCapital")) ) ) <script> function getCountryWithCapital(rowData) { return rowData.capital + " (" + rowData.country + ")"; } </script>
@(Html.DevExtreme().DataGrid() _ .Columns(Sub(columns) columns.Add() _ .DataField("CountryID") _ .CalculateDisplayValue(New JS("getCountryWithCapital")) End Sub) ) <script> function getCountryWithCapital(rowData) { return rowData.capital + " (" + rowData.country + ")"; } </script>
The widget uses the specified display values in sorting, searching, and grouping (in case of DataGrid).
this
keyword refers to the column's configuration.Do not use this option to format text in cells. Instead, use the format, customizeText, or cellTemplate option.
calculateFilterExpression
A filter expression. If you are using remoteOperations, it should not contain functions.
This function must return a filter expression. The simplest filter expression has the following format:
[selector, selectedFilterOperation, filterValue]
- selector
A data source field or a function providing actual column values. Pass this.calculateCellValue if your column contains calculated values. selectedFilterOperation
A comparison operator. One of the following: "=", "<>", ">", ">=", "<", "<=", "between", "startswith", "endswith", "contains", "notcontains".NOTEFor the "between" operator, the returned filter expression has a slightly different format:[[selector, ">=", startValue], "and", [selector, "<=", endValue]]
.filterValue
A user input value. Values the selector provides are compared to this value.
In the following code, the calculateFilterExpression function implements an exclusive between operation. This is done by overriding the default inclusive implementation.
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ // ... columns: [{ calculateFilterExpression: function (filterValue, selectedFilterOperation) { // Implementation for the "between" comparison operator if (selectedFilterOperation === "between" && $.isArray(filterValue)) { var filterExpression = [ [this.dataField, ">", filterValue[0]], "and", [this.dataField, "<", filterValue[1]] ]; return filterExpression; } // Invokes the default filtering behavior return this.defaultCalculateFilterExpression.apply(this, arguments); }, // ... }] }); });
Angular
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { calculateFilterExpression (filterValue, selectedFilterOperation) { let column = this as any; // Implementation for the "between" comparison operator if (selectedFilterOperation === "between" && Array.isArray(filterValue)) { var filterExpression = [ [column.dataField, ">", filterValue[0]], "and", [column.dataField, "<", filterValue[1]] ]; return filterExpression; } // Invokes the default filtering behavior return column.defaultCalculateFilterExpression.apply(column, arguments); } } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
<dx-data-grid ... > <dxi-column [calculateFilterExpression]="calculateFilterExpression" ... ></dxi-column> </dx-data-grid>
In the previous code, the defaultCalculateFilterExpression function invokes default behavior. You can omit this function call if you so choose.
this
keyword refers to the column's configuration.calculateGroupValue
Specifies a field name or a function that returns a field name or a value to be used for grouping column cells.
By default, grouping is conducted using the exact values that the grouping column contains. However, in some cases, this approach may be giving poor results, e.g., when a user tries to group records by a column that contains dates. In such cases, it may be preferable to use calculated values in grouping. For this purpose, assign a function to the calculateGroupValue option. This function must return the calculated value for grouping.
this
keyword refers to the column's configuration.calculateSortValue
This option accepts the name of the data source field that provides values to be used in sorting...
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ columns: [{ dataField: "Position", // provides values for the column calculateSortValue: "isOnVacation" // provides values to be used in sorting }] }); });
Angular
<dx-data-grid ... > <dxi-column dataField="Position" <!--provides values for the column --> calculateSortValue="isOnVacation"> <!-- provides values to be used in sorting --> </dxi-column> </dx-data-grid>
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
... or a function that returns such a value.
jQuery
$(function() { var dataGrid = $("#dataGridContainer").dxDataGrid({ columns: [{ dataField: "Position", sortOrder: "asc", calculateSortValue: function (rowData) { if (rowData.Position == "CEO") return dataGrid.columnOption("Position", "sortOrder") == "asc" ? "aaa" : "zzz"; // CEOs are always displayed at the top else return rowData.Position; // Others are sorted as usual } }] }).dxDataGrid("instance"); });
Angular
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { customSortingFunction (rowData) { let column = this as any; if (rowData.Position == "CEO") return column.sortOrder == "asc" ? "aaa" : "zzz"; // CEOs are always displayed at the top else return rowData.Position; // Others are sorted as usual } } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
<dx-data-grid ... > <dxi-column dataField="Position" sortOrder="asc" [calculateSortValue]="customSortingFunction"> </dxi-column> </dx-data-grid>
Please review the following notes about the calculateSortValue option.
The
this
keyword refers to the column's configuration.When the DataGrid is grouped by the column, this option is ignored. Use the calculateGroupValue option instead or additionally.
See Also
caption
Use this option to display a descriptive or friendly name for the column. If this option is not set, the caption will be generated from the name of the dataField.
cellComponent
An alias for the cellTemplate property specified in React. Accepts a custom component. Refer to Using a Custom Component for more information.
cellRender
An alias for the cellTemplate property specified in React. Accepts a rendering function. Refer to Using a Rendering Function for more information.
cellTemplate
Name | Type | Description |
---|---|---|
column |
The column's properties. |
|
columnIndex |
The index of the cell's column. |
|
component |
The widget's instance. |
|
data |
The data of the row to which the cell belongs. |
|
displayValue | any |
The cell's display value. Differs from the value field only when the column uses lookup or calculateDisplayValue. |
oldValue | any |
The cell's previous raw value. Defined only if repaintChangesOnly is true. |
row |
The cell's row. |
|
rowIndex |
The index of the cell's row. Begins with 0 on each page. Group rows are included. |
|
rowType |
The row's type. |
|
text |
displayValue after applying format and customizeText. |
|
value | any |
The cell's raw value. |
watch |
Allows tracking a variable and performing actions when it changes. Applies when repaintChangesOnly is true.
|
See Also
columns
Unlike normal columns, band columns do not hold data. Instead, they collect two or more columns under one column header. To set up this layout, declare the band column using a hierarchical structure. For this, assign the nested columns to the columns field of the band column. For example, the following code declares the "Address" band column and nests three columns within it.
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ // ... columns: [{ caption: "Address", columns: ["City", "Street", "Apartment"] }, { // ... }] }); });
Angular
<dx-data-grid ... > <dxi-column caption="Address"> <dxi-column dataField="City"></dxi-column> <dxi-column dataField="Street"></dxi-column> <dxi-column dataField="Apartment"></dxi-column> </dxi-column> </dx-data-grid>
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
A nested column has almost every option a regular column has. These options are described in the columns section of the Reference.
For example, the following code specifies the width and sortOrder options of the "Street" column nested within the fixed "Address" band column.
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ // ... columns: [{ caption: "Address", fixed: true, fixedPosition: "right", columns: [ "City", { dataField: "Street", width: 100, sortOrder: "asc" }, "Apartment" ] }, { // ... }] }); });
Angular
<dx-data-grid ... > <dxi-column caption="Address" [fixed]="true" fixedPosition="right"> <dxi-column dataField="City"></dxi-column> <dxi-column dataField="Street" [width]="100" sortOrder="asc"></dxi-column> <dxi-column dataField="Apartment"></dxi-column> </dxi-column> </dx-data-grid>
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
Band columns support hierarchies of any nesting level. It means that the following structure is acceptable.
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ // ... columns: [{ caption: "A", columns: [ "A1", "A2", { caption: "A3", columns: ["A31", "A32", { caption: "A33", columns: ["A331", "A332", "A333"] }] }] }, { caption: "B", columns: // ... }] }); });
Angular
<dx-data-grid ... > <dxi-column caption="A"> <dxi-column dataField="A1"></dxi-column> <dxi-column dataField="A2"></dxi-column> <dxi-column caption="A3"> <dxi-column dataField="A31"></dxi-column> <dxi-column dataField="A32"></dxi-column> <dxi-column caption="A33"> <dxi-column dataField="A331"></dxi-column> <dxi-column dataField="A332"></dxi-column> <dxi-column dataField="A333"></dxi-column> </dxi-column> </dxi-column> </dxi-column> <dxi-column caption="B"> ... </dxi-column> </dx-data-grid>
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
Band columns have the isBand flag. Banded columns have the ownerBand option set. Use these options to distinguish band and banded columns from regular ones in code.
See Also
cssClass
Specifies a CSS class to be applied to the column.
In the following code, this option is assigned a cell-highlighted
CSS class that customizes the position
column's cell and header styles:
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ dataSource: [{ ID: 1, position: "CTO" }, // ... ], columns: [ "ID", { dataField: "position", cssClass: "cell-highlighted" } ], }); })
.dx-data-row .cell-highlighted { background-color: #e6e6e6; } .dx-header-row .cell-highlighted { color: gray; font-style: italic; }
Angular
<dx-data-grid ... [dataSource]="employees"> <dxi-column dataField="ID"></dxi-column> <dxi-column dataField="position" cssClass="cell-highlighted"></dxi-column> </dx-data-grid>
import { Component } from '@angular/core'; @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { employees = [{ ID: 1, position: "CTO" }, // ... ]; }
import { BrowserModule } from '@angular/platform-browser'; import { NgModule } from '@angular/core'; import { AppComponent } from './app.component'; import { DxDataGridModule } from 'devextreme-angular'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, DxDataGridModule ], providers: [ ], bootstrap: [AppComponent] }) export class AppModule { }
::ng-deep .dx-data-row .cell-highlighted { background-color: #e6e6e6; } ::ng-deep .dx-header-row .cell-highlighted { color: gray; font-style: italic; }
Vue
<template> <DxDataGrid ... :data-source="employees"> <DxColumn data-field="ID" /> <DxColumn data-field="position" css-class="cell-highlighted" /> </DxDataGrid> </template> <script> import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import { DxDataGrid, DxColumn } from 'devextreme-vue/data-grid'; const employees = [{ ID: 1, position: "CTO" }, // ... ]; export default { components: { DxDataGrid, DxColumn }, data() { employees } }; </script> <style> .dx-data-row .cell-highlighted { background-color: #e6e6e6; } .dx-header-row .cell-highlighted { color: gray; font-style: italic; } </style>
React
import React from 'react'; import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import { DataGrid, Column } from 'devextreme-react/data-grid'; const employees = [{ ID: 1, position: "CTO" }, // ... ]; class App extends React.Component { constructor(props) { super(props); } render() { return ( <DataGrid ... dataSource={employees}> <Column dataField="ID" /> <Column dataField="position" cssClass="cell-highlighted" /> </DataGrid> ); } } export default App;
.dx-data-row .cell-highlighted { background-color: #e6e6e6; } .dx-header-row .cell-highlighted { color: gray; font-style: italic; }
ASP.NET MVC Controls
@(Html.DevExtreme().DataGrid() .DataSource(new JS("employees")) .Columns(c => { c.Add().DataField("ID"); c.Add().DataField("position").CssClass("cell-highlighted"); }) ) <script type="text/javascript"> var employees = [{ ID: 1, position: "CTO" }, // ... ]; </script>
.dx-data-row .cell-highlighted { background-color: #e6e6e6; } .dx-header-row .cell-highlighted { color: gray; font-style: italic; }
customizeText
Name | Type | Description |
---|---|---|
groupInterval | | |
Indicates how header filter values were combined into groups. Available if target is "headerFilter". |
target |
The UI element where the customizeText function was called: "row", "filterRow", "headerFilter", "search", "filterPanel", or "filterBuilder". |
|
value | | | |
The cell's raw value. |
valueText |
The fomatted value converted to a string. |
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ // ... columns: [{ dataField: "Temperature", customizeText: function(cellInfo) { return cellInfo.value + " °C"; } }] }); });
Angular
<dx-data-grid ... > <dxi-column dataField="Temperature" [customizeText]="customizeText" ></dxi-column> </dx-data-grid>
import { Component } from '@angular/core'; @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { customizeText(cellInfo) { return cellInfo.value + " °C"; } }
import { BrowserModule } from '@angular/platform-browser'; import { NgModule } from '@angular/core'; import { AppComponent } from './app.component'; import { DxDataGridModule } from 'devextreme-angular'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, DxDataGridModule ], providers: [ ], bootstrap: [AppComponent] }) export class AppModule { }
Vue
<template> <DxDataGrid ... > <DxColumn data-field="Temperature" :customize-text="customizeText" /> </DxDataGrid> </template> <script> import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import { DxDataGrid, DxColumn } from "devextreme-vue/data-grid"; export default { components: { DxDataGrid, DxColumn }, methods: { customizeText(cellInfo) { return cellInfo.value + " °C"; } } } </script>
React
import React from 'react'; import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DataGrid, { Column } from "devextreme-react/data-grid"; class App extends React.Component { customizeText = (cellInfo) => { return cellInfo.value + " °C"; } render() { return ( <DataGrid ... > <Column dataField="Temperature" customizeText={this.customizeText} /> </DataGrid> ); } } export default App;
ASP.NET MVC Controls
@(Html.DevExtreme().DataGrid() //... .Columns(columns => { columns.Add().DataField("Temperature") .CustomizeText("customizeText"); }) ) <script type="text/javascript"> function customizeText(cellInfo) { return cellInfo.value + " °C"; } </script>
The customizeText function can be called to highlight the matching text correctly when the data displayed in the column matches the search condition.
this
keyword refers to the column's configuration.See Also
dataField
Binds the column to a field of the dataSource.
The columns array can contain only the names of data source fields, which is sufficient if you do not need to specify any other column options. But if you do, then this array should contain objects that configure columns. To bind the columns to data source fields, use the dataField option. Note that you can combine both declarations in a single array as shown in the following code.
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ // ... columns: [ "CustomerID", { dataField: "EmployeeID", width: 200 }, "OrderDate", { dataField: "Freight", format: "fixedPoint" }, "ShipName", "ShipCity" ] }); });
Angular
<dx-data-grid ... > <dxi-column dataField="CustomerID"></dxi-column> <dxi-column dataField="EmployeeID" [width]="200"></dxi-column> <dxi-column dataField="OrderDate"></dxi-column> <dxi-column dataField="Freight" format="fixedPoint"></dxi-column> <dxi-column dataField="ShipName"></dxi-column> <dxi-column dataField="ShipCity"></dxi-column> </dx-data-grid>
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
See Also
dataType
If a data field provides values of one data type, but the widget should cast them to another, specify the proper type in this option. In the following code, values of the ID
and hireDate
fields are cast to numeric and date data types, respectively.
jQuery
$(function() { $("#dataGrid").dxDataGrid({ // ... dataSource: [{ ID: "1", hireDate: 1491821760000 }, // ... ], columns: [{ dataField: "ID", dataType: "number" }, { dataField: "hireDate", dataType: "date" }] }); })
Angular
<dx-data-grid ... [dataSource]="employees"> <dxi-column dataField="ID" dataType="number"> </dxi-column> <dxi-column dataField="hireDate" dataType="date"> </dxi-column> </dx-data-grid>
import { DxDataGridModule } from 'devextreme-angular'; // ... export class AppComponent { employees = [{ ID: "1", hireDate: 1491821760000 }, // ... ]; } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
ASP.NET MVC Controls
@(Html.DevExtreme().DataGrid() .DataSource(new JS("employees")) .Columns(c => { c.Add() .DataField("ID") .DataType(GridColumnDataType.Number); c.Add() .DataField("hireDate") .DataType(GridColumnDataType.Date); }) ) <script> var employees = [{ ID: "1", hireDate: 1491821760000 }, // ... ]; </script>
Vue
<template> <DxDataGrid ... :data-source="employees"> <DxColumn data-field="ID" data-type="number" /> <DxColumn data-field="hireDate" data-type="date" /> </DxDataGrid> </template> <script> import { DxDataGrid, DxColumn } from 'devextreme-vue/data-grid'; const employees = [{ ID: '1', hireDate: 1491821760000 }, // ... ]; export default { components: { DxDataGrid, DxColumn }, data() { employees } }; </script>
React
import React from 'react'; import { DataGrid, Column } from 'devextreme-react/data-grid'; const employees = [{ ID: '1', hireDate: 1491821760000 }, // ... ]; class App extends React.Component { render() { return ( <DataGrid ... dataSource={employees}> <Column dataField="ID" dataType="number" /> <Column dataField="hireDate" dataType="date" /> </DataGrid> ); } } export default App;
"yyyy/MM/dd"
, "yyyy/MM/dd HH:mm:ss"
, "yyyy-MM-ddTHH:mm:ssx"
or "yyyy-MM-ddTHH:mm:ss"
. Use the GridColumnDataType
enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: String
, Number
, Date
, DateTime
, Boolean
, and Object
.
See Also
editCellComponent
An alias for the editCellTemplate property specified in React. Accepts a custom component. Refer to Using a Custom Component for more information.
editCellRender
An alias for the editCellTemplate property specified in React. Accepts a rendering function. Refer to Using a Rendering Function for more information.
editCellTemplate
Name | Type | Description |
---|---|---|
column |
The settings of the column the cell belongs to. |
|
columnIndex |
The index of the column the cell belongs to. |
|
component |
The widget's instance. |
|
data |
The data of the cell's row. |
|
displayValue | any |
The displayed cell value. Differs from the value field only when the column uses lookup or calculateDisplayValue. |
row |
The cell's row. |
|
rowIndex |
The index of the row the cell belongs to. Begins with 0 on each page. Group rows are included. |
|
rowType |
The row's type. |
|
setValue(newValue, newText) | any |
A method you should call to change the cell value and, optionally, the displayed value after the editor's value is changed. NOTE In batch editing mode, check that the value is actually changed before calling this method to ensure correct cell highlighting. |
text |
displayValue after applying format and customizeText. |
|
value | any |
The cell value as it is specified in the data source. |
watch |
Allows you to track a variable and perform actions when it changes. Applies when repaintChangesOnly is true.
|
Use the editCellTemplate to replace the default editor. In the template, specify the replacement editor's appearance and behavior.
Other options that allow editor customization include:
columns[].editorOptions
Use it to specify the default editor's options (except onValueChanged).onEditorPreparing
Use it to:- Change the editor's type.
- Override the default editor's onValueChanged handler.
- Dynamically change the editor's options in the editing state.
- Implement other customization cases.
See Also
- columns[].showEditorAlways
- Custom Templates
editorOptions
Configures the default widget used for editing and filtering in the filter row.
In this object, you can specify the default widget's options (except onValueChanged, which you can specify in onEditorPreparing).
The default editor widget depends on the column configuration. The following table illustrates the dependency:
Column Configuration | Default Editor | |
---|---|---|
dataType: | "date" "datetime" |
DateBox |
"number" | NumberBox | |
"boolean" | CheckBox | |
"string" "object" |
TextBox | |
lookup is defined | SelectBox |
Because of this dependency, editorOptions cannot be typed and are not implemented as nested configuration components in Angular, Vue, and React. In these frameworks, specify editorOptions with an object. We recommend that you declare the object outside the configuration component in Vue and React to prevent possible issues caused by unnecessary re-rendering.
Angular
<dx-data-grid ... > <dxi-column ... [editorOptions]="{ format: 'currency', showClearButton: true }"> </dxi-column> </dx-data-grid>
import { BrowserModule } from '@angular/platform-browser'; import { NgModule } from '@angular/core'; import { AppComponent } from './app.component'; import { DxDataGridModule } from 'devextreme-angular'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, DxDataGridModule ], providers: [ ], bootstrap: [AppComponent] }) export class AppModule { }
Vue
<template> <DxDataGrid ... > <DxColumn ... :editor-options="columnEditorOptions" /> </DxDataGrid> </template> <script> import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DxDataGrid, { DxColumn } from 'devextreme-vue/data-grid'; export default { components: { DxDataGrid, DxColumn }, data() { return { columnEditorOptions: { format: 'currency', showClearButton: true } } } } </script>
React
import React from 'react'; import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DataGrid, { Column } from 'devextreme-react/data-grid'; class App extends React.Component { columnEditorOptions = { format: 'currency', showClearButton: true }; render() { return ( <DataGrid ... > <Column ... editorOptions={this.columnEditorOptions} /> </DataGrid> ); } } export default App;
Other options that allow editor customization include:
columns[].editCellTemplate
Use it to replace the default editor.onEditorPreparing
Use it to:- Change the editor type.
- Override the default editor's onValueChanged handler.
- Dynamically change editor options in the editing state.
- Implement other customization cases.
See Also
- columns[].showEditorAlways
falseText
In a boolean column, replaces all false items with a specified text. Applies only if showEditorAlways option is false.
filterOperations
Specifies the available filter operations. Applies if allowFiltering is true and the filterRow and/or filterPanel are visible.
The following table lists the available filter operations by data types. Users can apply these filter operations in the filter row and nested filterBuilder component. The same operations are assigned to columns of a specific data type.
dataType | filterOperations |
---|---|
"string" | [ "contains", "notcontains", "startswith", "endswith", "=", "<>" ] |
"numeric" | [ "=", "<>", "<", ">", "<=", ">=", "between" ] |
"date" | [ "=", "<>", "<", ">", "<=", ">=", "between" ] |
The nested filter builder also allows users to select from an extended set of operations that include "anyof", "noneof", "isblank", "isnotblank", and names of custom operations (if there are any).
The filterOperations option can also accept an empty array. In this case, the selected filter operation is "=" for all data types, and a user cannot change it.
Use the FilterOperations
enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: Equal
, NotEqual
, LessThan
, LessThanOrEqual
, GreaterThan
, GreaterThanOrEqual
, NotContains
, Contains
, StartsWith
, EndsWith
, and Between
.
See Also
- columns[].selectedFilterOperation
- columns[].filterValue
filterType
Specifies whether a user changes the current filter by including (selecting) or excluding (clearing the selection of) values. Applies only if headerFilter.visible and allowHeaderFiltering are true.
This option accepts the following values.
- include
Values in the header filter are unselected initially, and a user can select values to apply a filter. - exclude
All values in the header filter are selected initially. A user can deselect values to change the filter.
This option changes when the user clicks the Select All checkbox in the header filter:
Select All | filterType / filterValues |
---|---|
filterType: "include" filterValues: null |
|
filterType: "exclude" filterValues: null |
Use the FilterType
enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: Include
and Exclude
.
See Also
- Filtering API
- columns[].filterValues
filterValue
Specifies the column's filter value displayed in the filter row.
This value is applied using the selectedFilterOperation.
filterValues
Specifies values selected in the column's header filter.
If the headerFilter.groupInterval option is set, each value in the filterValues array specifies the beginning of an interval instead of an exact value:
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ // ... columns: [{ dataField: "ID", dataType: "number", headerFilter: { groupInterval: 100 }, filterValues: [500, 700], // Filter intervals are 500-600 and 700-800 }, // ... ] }) });
Angular
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { columns = [{ dataField: "ID", dataType: "number", headerFilter: { groupInterval: 100 }, filterValues: [500, 700], // Filter intervals are 500-600 and 700-800 }, // ... ]; } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
<dx-data-grid ... [columns]="columns"> </dx-data-grid>
See Also
fixedPosition
Specifies the widget's edge to which the column is fixed. Applies only if columns[].fixed is true.
Use the HorizontalEdge
enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: Left
and Right
.
See Also
format
See the format section for details on accepted values.
In the following code, the "fixedPoint" format type with a precision of 2 decimal places is applied to column values:
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ // ... columns: [{ // ... format: { type: "fixedPoint", precision: 2 } }] }); });
Angular
<dx-data-grid ... > <dxi-column ... > <dxo-format type="fixedPoint" [precision]="2"> </dxo-format> </dxi-column> </dx-data-grid>
import { BrowserModule } from '@angular/platform-browser'; import { NgModule } from '@angular/core'; import { AppComponent } from './app.component'; import { DxDataGridModule } from 'devextreme-angular'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, DxDataGridModule ], providers: [ ], bootstrap: [AppComponent] }) export class AppModule { }
Vue
<template> <DxDataGrid ... > <DxColumn ... > <DxFormat type="fixedPoint" :precision="2" /> </DxColumn> </DxDataGrid> </template> <script> import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DxDataGrid, { DxColumn, DxFormat } from 'devextreme-vue/data-grid'; export default { components: { DxDataGrid, DxColumn, DxFormat }, data() { // ... } } </script>
React
import React from 'react'; import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DataGrid, { Column, Format } from 'devextreme-react/data-grid'; class App extends React.Component { // ... render() { return ( <DataGrid> <Column ... > <Format type="fixedPoint" precision={2} /> </Column> </DataGrid> ); } } export default App;
The format option also limits user input in cells that use the DateBox widget for editing. For cells that use the NumberBox widget, you can specify the editorOptions.format option, as shown in the following demo:
When being exported to Excel, the specified format is converted to an Excel format as follows:
Numeric
Converted to the Number format, except for "largeNumber", which is exported without formatting.Currency
Converted to the Currency format.Date-Time
Converted to the Date or Time format, depending on the cell value. Exceptions: "quarter" and "quarterAndYear" are exported as Short Date; "minute" and "millisecond" are exported as Long Time.Function
Cannot be converted automatically. Assign this function to the customizeText option instead of the format option.Custom format string
Cannot be converted, the cell value is exported without formatting. To export this format, return the formatted string from the customizeText callback as follows:jQuery
index.js$(function() { $("#gridContainer").dxDataGrid({ // ... columns:[{ // ... format: "0.##", customizeText: (options) => { return options.valueText; } }], export: { enabled: true } }); });
Angular
app.component.htmlapp.component.tsapp.module.ts<dx-data-grid ... > <dxi-column ... format="0.##" [customizeText]="customizeText"> </dxi-column> <dxo-export [enabled]="true"> </dxo-export> </dx-data-grid>
import { Component } from '@angular/core'; @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { customizeText(options) { return options.valueText; } }
import { BrowserModule } from '@angular/platform-browser'; import { NgModule } from '@angular/core'; import { AppComponent } from './app.component'; import { DxDataGridModule } from 'devextreme-angular'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, DxDataGridModule ], providers: [], bootstrap: [AppComponent] }) export class AppModule { }
Vue
App.vue<template> <DxDataGrid ... > <DxColumn ... format="0.##" :customize-text="customizeText" /> <DxExport :enabled="true" /> </DxDataGrid> </template> <script> import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DxDataGrid, { DxExport, DxColumn } from 'devextreme-vue/data-grid'; export default { components: { DxDataGrid, DxExport, DxColumn }, methods: { customizeText(options) { return options.valueText; } } } </script>
React
App.jsimport React from 'react'; import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DataGrid, { Export, Column } from 'devextreme-react/data-grid'; class App extends React.Component { render() { return ( <DataGrid ... > <Column ... format="0.##" customizeText={this.customizeText} /> <Export enabled={true} /> </DataGrid> ); } customizeText(options) { return options.valueText; } } export default App;
formItem
Configures the form item that the column produces in the editing state. Applies only if editing.mode is "form" or "popup".
In the following code, the Full_Name
grid column in the editing state produces a form item that spans two form columns. The item's label is on top of the editor:
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ // ... editing: { allowUpdating: true, mode: "form" }, columns: [{ dataField: "Full_Name", formItem: { colSpan: 2, label: { location: "top" } } }, // ... ] }); });
Angular
<dx-data-grid ... > <dxo-editing [allowUpdating]="true" mode="form"> </dxo-editing> <dxi-column dataField="Full_Name"> <dxo-form-item [colSpan]="2"> <dxo-label location="top"></dxo-label> </dxo-form-item> </dxi-column> </dx-data-grid>
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
ASP.NET MVC Controls
@(Html.DevExtreme().DataGrid() // ... .Editing(e => e .AllowUpdating(true) .Mode(GridEditMode.Form) ) .Columns(cols => { // ... cols.Add().DataField("Full_Name") .FormItem(item => item .ColSpan(2) .Label(l => l.Location(FormLabelLocation.Top) ) ); }) )
See Also
groupCellComponent
An alias for the groupCellTemplate property specified in React. Accepts a custom component. Refer to Using a Custom Component for more information.
groupCellRender
An alias for the groupCellTemplate property specified in React. Accepts a rendering function. Refer to Using a Rendering Function for more information.
groupCellTemplate
Name | Type | Description |
---|---|---|
column |
The settings of the column the cell belongs to. |
|
columnIndex |
The index of the column the cell belongs to. |
|
component |
The widget's instance. |
|
data |
An object of the following structure: { key: "Group 1", // The group's name items: [ // Data objects that fall into the group { ... }, { ... }, // ... ] } |
|
displayValue | any |
The value displayed in the group cell. Differs from the value field only when the column to which the cell belongs uses lookup. |
groupContinuedMessage |
Contains the grouping.groupContinuedMessage if the current group is continued from the previous page. Otherwise, this field is undefined. |
|
groupContinuesMessage |
Contains the grouping.groupContinuesMessage if the current group continues on the next page. Otherwise, this field is undefined. |
|
row |
The cell's row. |
|
rowIndex |
The index of the row the cell belongs to. Begins with 0 on each page. Group rows are included. |
|
summaryItems | Array<any> |
Group summary items displayed in the group row. Objects in this array have the structure of the group summary items extended by the value (the summary item value) and columnCaption (usually used to present a summary value) fields. |
text |
The group cell's value with applied format. |
|
value | any |
The group cell's value as it is specified in a data source. |
See Also
groupIndex
Specifies the index of a column when grid records are grouped by the values of this column.
At runtime, the user can group grid records using the context menu or the group panel. But there may be cases when grid records must be grouped initially. To do this, assign an integer value to the groupIndex option of those columns that should be used for grouping grid records. For example, consider the following data source.
var dataSource = [ { FirstName: "John", LastName: "Doe", Title: "Sales Manager" }, { FirstName: "Michael", LastName: "King", Title: "Sales Representative" }, // ... ];
To group these records first by the "LastName" field and then by the "FirstName" field, use the following code.
jQuery
$("#dataGridContainer").dxDataGrid({ // ... columns: [ { dataField: "FirstName", groupIndex: 1 }, { dataField: "LastName", groupIndex: 0 }, // ... ] });
Angular
<dx-data-grid ... > <dxi-column dataField="FirstName" [groupIndex]="1"></dxi-column> <dxi-column dataField="LastName" [groupIndex]="0"></dxi-column> </dx-data-grid>
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
See Also
headerCellComponent
An alias for the headerCellTemplate property specified in React. Accepts a custom component. Refer to Using a Custom Component for more information.
headerCellRender
An alias for the headerCellTemplate property specified in React. Accepts a rendering function. Refer to Using a Rendering Function for more information.
headerCellTemplate
Name | Type | Description |
---|---|---|
column |
The settings of the column to which the header belongs. |
|
columnIndex |
The index of the column to which the header belongs. |
|
component |
The widget's instance. |
hidingPriority
Specifies the order in which columns are hidden when the widget adapts to the screen or container size. Ignored if allowColumnResizing is true and columnResizingMode is "widget".
The hidingPriority is a unique positive integer that ascends from right to left beginning with 0 by default. Columns with low hidingPriority are hidden first.
See Also
isBand
Unlike normal columns, band columns do not hold data. Instead, they collect two or more columns under one column header. In most cases, to set up this layout, you can declare the band column using a hierarchical structure. For example, the following code bands three columns under the "Address" header.
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ // ... columns: [{ caption: "Address", columns: ["City", "Street", "Apartment"] }, { // ... }] }); });
Angular
<dx-data-grid ... > <dxi-column caption="Address"> <dxi-column dataField="City"></dxi-column> <dxi-column dataField="Street"></dxi-column> <dxi-column dataField="Apartment"></dxi-column> </dxi-column> </dx-data-grid>
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
If you use the customizeColumns option to configure columns, the hierarchical structure cannot be implemented. To band columns in this case, use the isBand and ownerBand options.
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ // ... customizeColumns: function(columns) { columns.push({ // Pushes the "Address" band column into the "columns" array caption: "Address", isBand: true }); var addressFields = ["City", "Street", "Apartment"]; for (var i = 0; i < columns.length-1; i++) { if (addressFields.indexOf(columns[i].dataField) > -1) // If the column belongs to "Address", columns[i].ownerBand = columns.length-1; // assigns "Address" as the owner band column } } }); });
Angular
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { customizeColumns (columns) { columns.push({ // Pushes the "Address" band column into the "columns" array caption: "Address", isBand: true }); let addressFields = ["City", "Street", "Apartment"]; for (let i = 0; i < columns.length - 1; i++) { if (addressFields.indexOf(columns[i].dataField) > -1) // If the column belongs to "Address", columns[i].ownerBand = columns.length - 1; // assigns "Address" as the owner band column } } } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
<dx-data-grid ... [customizeColumns]="customizeColumns"> </dx-data-grid>
Band columns can have the following properties only:
- alignment
- allowHiding
- allowReordering
- caption
- columns
- cssClass
- fixed
- fixedPosition
- headerCellTemplate
- name
- ownerBand
- showInColumnChooser
- visible
- visibleIndex
See Also
lookup
A lookup column restricts the set of values that can be chosen when a user edits or filters the column. In a lookup column, each cell is a drop-down menu. You can use a lookup column when you need to substitute displayed values with required values. For example, consider that you have two arrays of objects: drivers
and buses
.
var drivers = [ { driverID: 1, firstName: "John", lastName: "Smith", busID: 2 }, { driverID: 2, firstName: "Lizzy", lastName: "Cook", busID: 1 }, { driverID: 3, firstName: "Brian", lastName: "Hawkins", busID: 3 } ]; var buses = [ { busID: 1, plates: "123456" }, { busID: 2, plates: "AB-1234" }, { busID: 3, plates: "CD-9876" } ];
All drivers
have the busID
field, which refers to a bus. If drivers
is the main dataSource, the Bus ID column displays bus IDs, which provides little information to a user. It will be more useful to display bus license plates instead of IDs. For this, the buses
array must be set as a lookup dataSource for the Bus ID column. Then, the names of data fields must be assigned to the valueExpr and displayExpr options. Values from the valueExpr data field will be replaced with values from the displayExpr data field.
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ dataSource: drivers, // ... columns: [{ dataField: "busID", lookup: { dataSource: buses, valueExpr: "busID", displayExpr: "plates" } }] }); });
Angular
<dx-data-grid [dataSource]="drivers"> <dxi-column dataField="busID"> <dxo-lookup [dataSource]="buses" valueExpr="busID" displayExpr="plates"> </dxo-lookup> </dxi-column> </dx-data-grid>
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { drivers = [ { driverID: 1, firstName: "John", lastName: "Smith", busID: 2 }, { driverID: 2, firstName: "Lizzy", lastName: "Cook", busID: 1 }, { driverID: 3, firstName: "Brian", lastName: "Hawkins", busID: 3 } ]; buses = [ { busID: 1, plates: "123456" }, { busID: 2, plates: "AB-1234" }, { busID: 3, plates: "CD-9876" } ]; } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
With this code, the Bus ID column contains license plates instead of IDs. Moreover, the user can choose a plate number from the drop-down menu when editing cells or applying a filter to this column.
See Also
name
Set this option if you need to refer to the column in your code afterwards, for example, when changing a column option.
ownerBand
Specifies the band column that owns the current column. Accepts the index of the band column in the columns array.
Main article: isBand
renderAsync
Specifies whether to render the column after other columns and elements. Use if column cells have a complex template. Requires the width option specified.
selectedFilterOperation
Specifies the column's filter operation displayed in the filter row.
The following table lists default filter operations by data type:
dataType | Default filter operation |
---|---|
"string" | "contains" |
"number" | "=" |
"date" | "=" |
Use the FilterOperations
enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: Equal
, NotEqual
, LessThan
, LessThanOrEqual
, GreaterThan
, GreaterThanOrEqual
, NotContains
, Contains
, StartsWith
, EndsWith
, and Between
.
See Also
setCellValue
Specifies a function to be invoked after the user has edited a cell value, but before it will be saved in the data source.
This function allows you to process user input before it is saved to the data source. It accepts the newData, value, and currentRowData parameters. value is the user input that you should assign to one of the newData fields. Fill the empty newData object with fields whose values should be saved in the current row's data object. The read-only currentRowData parameter can be used to access the current row's data.
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ // ... columns: [ "Price", { dataField: "Count", dataType: "number", setCellValue: function(newData, value, currentRowData) { newData.Count = value; newData.TotalPrice = currentRowData.Price * value; } }, "TotalPrice", // ... ] }); });
Angular
<dx-data-grid ... > <dxi-column dataField="Price"></dxi-column> <dxi-column dataField="Count" dataType="number" [setCellValue]="setCellValue"> </dxi-column> <dxi-column dataField="TotalPrice"></dxi-column> </dx-data-grid>
import { Component } from '@angular/core'; @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { setCellValue (newData, value, currentRowData) { newData.Count = value; newData.TotalPrice = currentRowData.Price * value; } }
import { BrowserModule } from '@angular/platform-browser'; import { NgModule } from '@angular/core'; import { AppComponent } from './app.component'; import { DxDataGridModule } from 'devextreme-angular'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, DxDataGridModule ], providers: [ ], bootstrap: [AppComponent] }) export class AppModule { }
Vue
<template> <DxDataGrid ... > <DxColumn data-field="Price" /> <DxColumn data-field="Count" data-type="number" /> <DxColumn data-field="TotalPrice" :set-cell-value="setCellValue" /> </DxDataGrid> </template> <script> import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import { DxDataGrid, DxColumn } from 'devextreme-vue/data-grid'; export default { components: { DxDataGrid, DxColumn }, // ... methods: { setCellValue(newData, value, currentRowData) { newData.Count = value; newData.TotalPrice = currentRowData.Price * value; } } }; </script>
React
import React from 'react'; import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import { DataGrid, Column } from 'devextreme-react/data-grid'; class App extends React.Component { setCellValue(newData, value, currentRowData) { newData.Count = value; newData.TotalPrice = currentRowData.Price * value; } render() { return ( <DataGrid ... > <Column dataField="Price" /> <Column dataField="Count" dataType="numeric" setCellValue={this.setCellValue}/> <Column dataField="TotalPrice" /> </DataGrid> ); } } export default App;
ASP.NET MVC Controls
@(Html.DevExtreme().DataGrid() // ... .Columns(c => { c.Add().DataField("Price"); c.Add().DataField("Count") .DataType(GridColumnDataType.Number) .SetCellValue(@<text> function(newData, value, currentRowData) { newData.Count = value; newData.TotalPrice = currentRowData.Price * value; } </text>); c.Add().DataField("TotalPrice"); }) )
If you need to perform asynchronous operations in the setCellValue function, return a promise from it. In the following code, this technique is used to get the Tax
value from the server when the State
value is changed:
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ // ... columns: [{ dataField: "State", setCellValue: function(newData, value, currentRowData) { return getTaxRates(value) .done(function(data) { newData.State = value; newData.Tax = data.Tax; }); } }, "Tax", // ... ] }); function getTaxRates(state) { var promise = $.ajax({ // The URL returns { State: 1, Tax: 10 } url: "https://www.mywebsite.com/api/getTaxRates", dataType: "json", data: { State: state } }); return promise; } });
Angular
<dx-data-grid ... > <dxi-column dataField="State" [setCellValue]="setCellValue"> </dxi-column> <dxi-column dataField="Tax"></dxi-column> <!-- ... --> </dx-data-grid>
import { Component } from '@angular/core'; import { HttpClient, HttpParams } from '@angular/common/http'; import 'rxjs/add/operator/toPromise'; @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { constructor(private httpClient: HttpClient) { this.setCellValue = this.setCellValue.bind(this); } setCellValue(newData, value, currentRowData) { return this.getTaxRates(value).then((data: any) => { newData.State = value; newData.Tax = data.Tax; }); } getTaxRates(state) { const params = new HttpParams().set('State', state); return this.httpClient.get("https://www.mywebsite.com/api/getTaxRates", { params }) .toPromise() .then(data => { // "data" is { State: 1, Tax: 10 } return data; }) .catch(error => { throw "Data Loading Error" }); } }
import { BrowserModule } from '@angular/platform-browser'; import { NgModule } from '@angular/core'; import { AppComponent } from './app.component'; import { HttpClientModule } from '@angular/common/http'; import { DxDataGridModule } from 'devextreme-angular'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, HttpClientModule, DxDataGridModule ], providers: [ ], bootstrap: [AppComponent] }) export class AppModule { }
Vue
<template> <DxDataGrid ... > <DxColumn data-field="State" :set-cell-value="setCellValue" /> <DxColumn data-field="Tax" /> <!-- ... --> </DxDataGrid> </template> <script> import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import { DxDataGrid, DxColumn } from 'devextreme-vue/data-grid'; import 'whatwg-fetch'; export default { components: { DxDataGrid, DxColumn }, // ... methods: { setCellValue(newData, value, currentRowData) { return this.getTaxRates(value).then(data => { newData.State = value; newData.Tax = data.Tax; }); }, getTaxRates(state) { let params = '?' + 'State=' + state; return fetch("https://www.mywebsite.com/api/getTaxRates${params}") .toPromise() .then(data => { // "data" is { State: 1, Tax: 10 } return data; }) .catch(error => { throw "Data Loading Error" }); } } }; </script>
React
import React from 'react'; import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import { DataGrid, Column } from 'devextreme-react/data-grid'; import 'whatwg-fetch'; class App extends React.Component { constructor(props) { super(props); this.setCellValue = this.setCellValue.bind(this); } setCellValue(newData, value, currentRowData) { return this.getTaxRates(value).then(data => { newData.State = value; newData.Tax = data.Tax; }); } getTaxRates(state) { let params = '?' + 'State=' + state; return fetch("https://www.mywebsite.com/api/getTaxRates${params}") .toPromise() .then(data => { // "data" is { State: 1, Tax: 10 } return data; }) .catch(error => { throw "Data Loading Error" }); } render() { return ( <DataGrid ... > <Column dataField="State" setCellValue={this.setCellValue}/> <Column dataField="Tax" /> {/* ... */} </DataGrid> ); } } export default App;
ASP.NET MVC Controls
@(Html.DevExtreme().DataGrid() // ... .Columns(c => { c.Add().DataField("State") .SetCellValue("setCellValue"); c.Add().DataField("Tax"); // ... }) ) <script type="text/javascript"> function setCellValue(newData, value, currentRowData) { return getTaxRates(value).done(function(data) { newData.State = value; newData.Tax = data.Tax; }); } function getTaxRates(state) { var promise = $.ajax({ // The URL returns { State: 1, Tax: 10 } url: "https://www.mywebsite.com/api/getTaxRates", dataType: "json", data: { State: state } }); return promise; } </script>
To invoke the default behavior, call the this.defaultSetCellValue(newData, value) function.
this
keyword refers to the column's configuration.showEditorAlways
A column cell has normal and editing states. In a normal state, the cell value is text. In the editing state, the cell contains an editor that indicates the cell value and allows a user to edit it. In certain cases, a viewer reads the cell value easier if it is indicated by an editor even in the normal state. For example, boolean values are more comprehensible when they are indicated by check boxes. To display editors in cells permanently, set the showEditorAlways option to true.
This option has the following peculiarities.
- The default value of this option depends on the column's dataType. For boolean columns, it is true; for columns of other types - false.
- If you use templates, setting this option to true means that the column will always use editCellTemplate instead of cellTemplate.
See Also
- columns[].editorOptions
showInColumnChooser
Specifies whether the column chooser can contain the column header.
showWhenGrouped
Displaying a grouping column may be useful if you calculate its grouping values. Consider that you need to group records by a column that contains dates. Grouping by full dates seems inconvenient. It would be smarter to group by months or years instead. For this purpose, you calculate grouping values within the calculateGroupValue function and leave the grouping column visible by setting the showWhenGrouped option to true so that the user can view the full dates.
sortIndex
This option accepts an integer specifying the index of the column in a collection of columns with applied sorting. For example, consider the following data source that can provide data for three columns.
var dataSource = [ { firstName: "John", lastName: "Doe", title: "Sales Manager" }, { firstName: "Michael", lastName: "King", title: "Sales Representative" }, // ... ];
To sort data first by the "Last Name" and then by the "First Name" column, use the following code. Note that the sortOrder option should also be specified.
jQuery
$(function() { $("#dataGridContainer").dxDataGrid({ // ... columns: [ { dataField: "firstName", sortIndex: 1, sortOrder: "asc" }, { dataField: "lastName", sortIndex: 0, sortOrder: "asc" }, // ... ] }); });
Angular
<dx-data-grid ... > <dxi-column dataField="firstName" [sortIndex]="1" sortOrder="asc"></dxi-column> <dxi-column dataField="lastName" [sortIndex]="0" sortOrder="asc"></dxi-column> </dx-data-grid>
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
You can set the sortIndex option at design time to specify initial sorting, or change this option using the columnOption method to sort at runtime.
sortingMethod
Specifies a custom comparison function for sorting. Applies only when sorting is performed on the client.
This function accepts two cell values and should return a number indicating their sort order:
- Less than zero
value1 goes before value2. - Zero
value1 and value2 remain unchanged relative to each other. - Greater than zero
value1 goes after value2.
The string comparison is culture-insensitive by default. Use the following code to make it culture-sensitive:
jQuery
$(function () { $("#dataGridContainer").dxDataGrid({ // ... columns: [{ dataField: "fieldName", sortingMethod: function (value1, value2) { // Handling null values if(!value1 && value2) return -1; if(!value1 && !value2) return 0; if(value1 && !value2) return 1; // Determines whether two strings are equivalent in the current locale return value1.localeCompare(value2); } }] }); });
Angular
import { DxDataGridModule } from "devextreme-angular"; // ... export class AppComponent { sortStringsConsideringCulture (value1, value2) { // Handling null values if(!value1 && value2) return -1; if(!value1 && !value2) return 0; if(value1 && !value2) return 1; // Determines whether two strings are equivalent in the current locale return value1.localeCompare(value2); } } @NgModule({ imports: [ // ... DxDataGridModule ], // ... })
<dx-data-grid ... > <dxi-column dataField="fieldName" [sortingMethod]="sortStringsConsideringCulture"> </dxi-column> </dx-data-grid>
this
keyword refers to the column's configuration.sortOrder
By default, rows are sorted according to the data source. Set the sortOrder option to sort rows in a required order. If you need to sort by multiple columns, specify the sortIndex option as well, or otherwise, each sorted column will get a sort index according to the position in the columns array.
Use the SortOrder
enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: Asc
and Desc
.
See Also
trueText
In a boolean column, replaces all true items with a specified text. Applies only if showEditorAlways option is false.
type
Specifies the command column that this object customizes.
validationRules
Specifies validation rules to be checked when cell values are updated.
Array<RequiredRule | NumericRule | RangeRule | StringLengthRule | CustomRule | CompareRule | PatternRule | EmailRule | AsyncRule>
See Also
visibleIndex
Visible indexes are normalized after the widget's creation: the leftmost column is assigned an index of 0; the rightmost column's index becomes equal to the number of visible columns minus 1; other columns get the indexes in between.
See Also
width
Specifies the column's width in pixels or as a percentage. Ignored if it is less than minWidth.
The option supports the following types of values:
- Number
The column's width in pixels. String
A CSS-accepted column width measurement (for example, "55px", "80%" and "auto") except relative units such as em, ch, vh, etc.NOTEFixed columns ignore widths specified as a percentage.