columns[]

An array of grid columns.

Type: Array
Default Value: undefined

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 Specifying Grid Columns 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.

View Demo Watch Video

alignment

Aligns the content of the column.

Type: String
Default Value: undefined
Accepted Values: undefined | 'left' | 'center' | 'right'

The default alignment of the content depends on the type of data.

dataType alignment
'number' 'right'
'boolean' 'center'
'string' 'left'
'date' 'left'

When using the widget as an ASP.NET MVC Control, specify this option using the HorizontalAlignment enum. This enum accepts the following values: Left, Center and Right.

Show Example:
AngularJS
Knockout
jQuery

In this example, the content of the "First Name" and "Last Name" columns is centered using the alignment option specified for these columns in the columns array.


                                    

                                    

In this example, the content of the "First Name" and "Last Name" columns is centered using the alignment option specified for these columns in the columns array.


                                    

                                    

In this example, the content of the "First Name" and "Last Name" columns is centered using the alignment option specified for these columns in the columns array.


                                    

                                    

allowEditing

Specifies whether a user can edit values in the column at runtime. By default, inherits the value of the editing | allowUpdating option.

Type: Boolean
Default Value: true
NOTE
If values in the column are calculated customarily using the calculateCellValue option, they cannot be edited at runtime.
See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, editing is enabled in a grid using the editing | allowUpdating option. However, you cannot edit values in the "Author", "Title" and "Year" columns as the allowEditing option for them is set to false.


                                    

                                    

In this example, editing is enabled in a grid using the editing | allowUpdating option. However, you cannot edit values in the "Author", "Title" and "Year" columns as the allowEditing option for them is set to false.


                                    

                                    

In this example, editing is enabled in a grid using the editing | allowUpdating option. However, you cannot edit values in the "Author", "Title" and "Year" columns as the allowEditing option for them is set to false.


                                    

                                    

allowExporting

Specifies whether data from this column should be exported.

Type: Boolean
Default Value: true
See Also

allowFiltering

Specifies whether data can be filtered by this column. Applies only if filterRow | visible is true.

Type: Boolean
Default Value: true
See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, you can filter grid records by values from different columns using the filter row. Note that filtering is enabled for all columns by making the filter row visible, but for the "Customer ID" column it is disabled explicitly by setting the allowFiltering option of this column to false. Try to type several symbols in a filter row cell or the search panel, and grid records will be filtered by them.


                                    

                                    

In this example, you can filter grid records by values from different columns using the filter row. Note that filtering is enabled for all columns by making the filter row visible, but for the "Customer ID" column it is disabled explicitly by setting the allowFiltering option of this column to false. Try to type several symbols in a filter row cell or the search panel, and grid records will be filtered by them.


                                    

                                    

In this example, you can filter grid records by values from different columns using the filter row. Note that filtering is enabled for all columns by making the filter row visible, but for the "Customer ID" column it is disabled explicitly by setting the allowFiltering option of this column to false. Try to type several symbols in a filter row cell or the search panel, and grid records will be filtered by them.


                                    

                                    

allowFixing

Specifies whether a user can fix the column at runtime. Applies only if columnFixing | enabled is true.

Type: Boolean
Default Value: true
See Also

allowGrouping

Specifies whether the user can group data by values of this column. Applies only when grouping is enabled.

Type: Boolean
Default Value: true

When grouping is enabled in the widget (refer to the See Also section), 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.

NOTE
In a column with calculated values, this option is set to false by default.
See Also
  • grouping | contextMenuEnabled - enables the user to group data using the context menu.
  • groupPanel | visible - enables the user to group data using the group panel.
  • groupPanel | allowColumnDragging - allows the user to move column headers to/from the group panel using drag-and-drop.
  • columns[] | groupIndex - specifies initial grouping.
Show Example:
AngularJS
Knockout
jQuery

In this example, grouping is enabled for the whole grid by making the group panel visible. However, grouping by the "Order ID" and "Shipped Date" columns is prohibited as the allowGrouping option is set to false for them. To group grid records by one of the other columns, drag it by the header and drop it onto the group panel.


                                    

                                    

In this example, grouping is enabled for the whole grid by making the group panel visible. However, grouping by the "Order ID" and "Shipped Date" columns is prohibited as the allowGrouping option is set to false for them. To group grid records by one of the other columns, drag it by the header and drop it onto the group panel.


                                    

                                    

In this example, grouping is enabled for the whole grid by making the group panel visible. However, grouping by the "Order ID" and "Shipped Date" columns is prohibited as the allowGrouping option is set to false for them. To group grid records by one of the other columns, drag it by the header and drop it onto the group panel.


                                    

                                    

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.

Type: Boolean
Default Value: true

allowHiding

Specifies whether a user can hide the column using the column chooser at runtime. Applies only if columnChooser | enabled is true.

Type: Boolean
Default Value: true
See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, you can hide grid columns by dragging their headers onto the column chooser panel. To invoke this panel, click the column chooser icon. However, the "Author", "Title" and "Year" columns cannot be hidden as the allowHiding option is set to false for them.


                                    

                                    

In this example, you can hide grid columns by dragging their headers onto the column chooser panel. To invoke this panel, click the column chooser icon. However, the "Author", "Title" and "Year" columns cannot be hidden as the allowHiding option is set to false for them.


                                    

                                    

In this example, you can hide grid columns by dragging their headers onto the column chooser panel. To invoke this panel, click the column chooser icon. However, the "Author", "Title" and "Year" columns cannot be hidden as the allowHiding option is set to false for them.


                                    

                                    

allowReordering

Specifies whether this column can be used in column reordering at runtime. Applies only if allowColumnReordering is true.

Type: Boolean
Default Value: true

Show Example:
AngularJS
Knockout
jQuery

In this example, column reordering is enabled in a grid using the allowColumnReordering option. Drag a column by its header and drop it on the required place to change the order of grid columns. Note that the "Author", "Title" and "Year" columns cannot be used in reordering as the allowReordering option for them is set to false.


                                    

                                    

In this example, column reordering is enabled in a grid using the allowColumnReordering option. Drag a column by its header and drop it on the required place to change the order of grid columns. Note that the "Author", "Title" and "Year" columns cannot be used in reordering as the allowReordering option for them is set to false.


                                    

                                    

In this example, column reordering is enabled in a grid using the allowColumnReordering option. Drag a column by its header and drop it on the required place to change the order of grid columns. Note that the "Author", "Title" and "Year" columns cannot be used in reordering as the allowReordering option for them is set to false.


                                    

                                    

allowResizing

Specifies whether a user can resize the column at runtime. Applies only if allowColumnResizing is true.

Type: Boolean
Default Value: true
See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, grid columns can be resized by dragging their borders as the allowColumnResizing option is set to true. However, the "Title" column, which has its width specified, is restricted from being resized by setting its allowResizing option to false.


                                    

                                    

In this example, grid columns can be resized by dragging their borders as the allowColumnResizing option is set to true. However, the "Title" column, which has its width specified, is restricted from being resized by setting its allowResizing option to false.


                                    

                                    

In this example, grid columns can be resized by dragging their borders as the allowColumnResizing option is set to true. However, the "Title" column, which has its width specified, is restricted from being resized by setting its allowResizing option to false.


                                    

                                    

allowSearch

Specifies whether this column can be searched. Applies only if searchPanel | visible is true. Inherits the value of the allowFiltering option by default.

Type: Boolean
Default Value: true

allowSorting

Specifies whether a user can sort rows by this column at runtime. Applies only if sorting | mode differs from "none".

Type: Boolean
Default Value: true
NOTE
In a column with calculated values, this option is set to false by default.
See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, you can sort grid records by any column, except "Customer ID" and "Ship Name". For these columns, sorting is disabled using the allowSorting option set to false. To sort grid records by any other column, click its header.


                                    

                                    

In this example, you can sort grid records by any column, except "Customer ID" and "Ship Name". For these columns, sorting is disabled using the allowSorting option set to false. To sort grid records by any other column, click its header.


                                    

                                    

In this example, you can sort grid records by any column, except "Customer ID" and "Ship Name". For these columns, sorting is disabled using the allowSorting option set to false. To sort grid records by any other column, click its header.


                                    

                                    

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.

Type: Boolean
Default Value: true
Show Example:
AngularJS
Knockout
jQuery

In this example, the visible group panel enables you to group records. Note that for the "Format" column, the autoExpandGroup option is set to false. Thus, when you group records by this column, the corresponding groups appear collapsed. As for other columns, this option preserves its default value - true. Thus, when you group records by these columns, the groups appear expanded.


                                    

                                    

In this example, the visible group panel enables you to group records. Note that for the "Format" column, the autoExpandGroup option is set to false. Thus, when you group records by this column, the corresponding groups appear collapsed. As for other columns, this option preserves its default value - true. Thus, when you group records by these columns, the groups appear expanded.


                                    

                                    

In this example, the visible group panel enables you to group records. Note that for the "Format" column, the autoExpandGroup option is set to false. Thus, when you group records by this column, the corresponding groups appear collapsed. As for other columns, this option preserves its default value - true. Thus, when you group records by these columns, the groups appear expanded.


                                    

                                    

calculateCellValue

Calculates custom values for column cells.

Type: function(rowData)
Function parameters:
rowData: Object
Data of the row to which the cell belongs.
Return Value: any
A cell's custom value.

Column cells contain values from the data field by default, but you can populate them with custom values instead. For this, declare the calculateCellValue function that is called each time a new row is rendered.

Certain features are disabled in a column with calculated values by default. The following list specifies these features and how you can enable them:

Feature Action that enables it
Editing Implement the setCellValue function.
Sorting Set the allowSorting option to true.
Grouping Set the allowGrouping option to true.
Filtering Set the allowFiltering option to true.
Searching Set the allowSearch option to true.
NOTE

Call the this.defaultCalculateCellValue(rowData) function and return its result to invoke the default behavior.

JavaScript
$(function() {
    $("#dataGridContainer").dxDataGrid({
        columns: [{
            calculateCellValue: function(rowData) {
                // ...
                return this.defaultCalculateCellValue(rowData);
            }
        }]
    });
});
See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, the orders data array is presented in a grid. The "Employee" column is populated with the values that are calculated using the function specified for the column's calculateCellValue option. In this function, the employees data array is scanned until an Employee object with the ID equal to the current order's EmployeeID field value is found. The value returned by this function is a concatenation of the "TitleOfCourtesy", "FirstName" and "LastName" field values of the found Employee object.


                                    

                                    

In this example, the orders data array is presented in a grid. The "Employee" column is populated with the values that are calculated using the function specified for the column's calculateCellValue option. In this function, the employees data array is scanned until an Employee object with the ID equal to the current order's EmployeeID field value is found. The value returned by this function is a concatenation of the "TitleOfCourtesy", "FirstName" and "LastName" field values of the found Employee object.


                                    

                                    

In this example, the orders data array is presented in a grid. The "Employee" column is populated with the values that are calculated using the function specified for the column's calculateCellValue option. In this function, the employees data array is scanned until an Employee object with the ID equal to the current order's EmployeeID field value is found. The value returned by this function is a concatenation of the "TitleOfCourtesy", "FirstName" and "LastName" field values of the found Employee object.


                                    

                                    

calculateDisplayValue

Calculates custom display values for column cells. Used when display values should differ from values for editing.

Type: String| function(rowData)
Function parameters:
rowData: Object
The data of the row to which the cell belongs.
Return Value: any
A display value for the cell.

This option accepts the name of the data source field that provides display values...

JavaScript
$(function() {
    $("#dataGridContainer").dxDataGrid({
        columns: [{
            dataField: "countryID", // provides values for editing
            calculateDisplayValue: "country" // provides display values
        }]
    });
});

... or a function that combines display values.

JavaScript
$(function() {
    $("#dataGridContainer").dxDataGrid({
        columns: [{
            dataField: "countryID", // provides values for editing
            calculateDisplayValue: function (rowData) { // combines display values
                return rowData.capital + " (" + rowData.country + ")";
            }
        }]
    });
});
NOTE
Do not use this option to format text in cells. Use customizeText for this.
See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, the orders data array is presented in a grid. Display values of the "Employee" column are calculated using the function specified for a column's calculateDisplayValue option. In this function, the employees data array is scanned until an Employee object with the ID equal to the current order's EmployeeID field value is found. The value returned by this function is a concatenation of the "TitleOfCourtesy" and "LastName" field values of the found Employee object.


                                    

                                    

In this example, the orders data array is presented in a grid. Display values of the "Employee" column are calculated using the function specified for a column's calculateDisplayValue option. In this function, the employees data array is scanned until an Employee object with the ID equal to the current order's EmployeeID field value is found. The value returned by this function is a concatenation of the "TitleOfCourtesy" and "LastName" field values of the found Employee object.


                                    

                                    

In this example, the orders data array is presented in a grid. Display values of the "Employee" column are calculated using the function specified for a column's calculateDisplayValue option. In this function, the employees data array is scanned until an Employee object with the ID equal to the current order's EmployeeID field value is found. The value returned by this function is a concatenation of the "TitleOfCourtesy" and "LastName" field values of the found Employee object.


                                    

                                    

calculateFilterExpression

Specifies the column's custom filtering rules.

Type: function(filterValue, selectedFilterOperation, target)
Function parameters:
filtervalue: any
A user input value.
selectedFilterOperation: String
The currently selected filter operation.
target: String
The UI element where the filter expression was set.
Possible values: "filterRow", "headerFilter" and "search".
Return Value: Filter expression
A filter expression.

This function must return a filter expression, which is an array of the following format:

[selector, selectedFilterOperation, filterValue]
  • selector
    A data source field or a function providing actual values for the column. If you are in doubt what to pass here, pass this.calculateCellValue.
  • selectedFilterOperation
    A comparison operator. One of the following: "=", "<>", ">", ">=", "<", "<=", "between", "startswith", "endswith", "contains", "notcontains".
  • filterValue
    A user input value. Values provided by the selector are compared to this value.

The following code snippet shows the default implementation of the calculateFilterExpression function. Adapt it according to your needs.

JavaScript
$(function() {
    $("#dataGridContainer").dxDataGrid({
        // ...
        columns: [{
            calculateFilterExpression: function (filterValue, selectedFilterOperation) {
                // Implementation for the "between" comparison operator
                if (selectedFilterOperation === "between" && $.isArray(filterValue)) {
                    var filterExpression = [
                        [this.calculateCellValue, ">=", filterValue[0]], 
                        "and", 
                        [this.calculateCellValue, "<=", filterValue[1]]
                    ];
                    return filterExpression;
                }
                return [this.calculateCellValue, selectedFilterOperation || '=', filterValue];
            },
            // ...
        }]
    });
});

As you can see from the previous code, the filter expression for the "between" comparison operator should have a slightly different format.

[[selector, ">=", startValue], "and", [selector, "<=", endValue]]
NOTE

Call the this.defaultCalculateFilterExpression(filterValue, selectedFilterOperation) function and return its result to invoke the default behavior.

JavaScript
$(function() {
    $("#dataGridContainer").dxDataGrid({
        columns: [{
            calculateFilterExpression: function(filterValue, selectedFilterOperation) {
                // ...
                return this.defaultCalculateFilterExpression(filterValue, selectedFilterOperation);
            }
        }]
    });
});

calculateGroupValue

Specifies a field name or a function that returns a field name or a value to be used for grouping column cells.

Type: String| function(rowData)
Function parameters:
rowData: Object
The data object presented by the current grid row.
Return Value: any
The calculated value to be used for grouping.

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.

calculateSortValue

Calculates custom values to be used in sorting.

Type: String| function(rowData)
Function parameters:
rowData: Object
The data of the row to which the cell belongs.
Return Value: any
The value to be used in sorting.

This option accepts the name of the data source field that provides values to be used in sorting...

JavaScript
$(function() {
    $("#dataGridContainer").dxDataGrid({
        columns: [{
            dataField: "Position", // provides values for the column
            calculateSortValue: "isOnVacation" // provides values to be used in sorting 
        }]
    });
});

... or a function that returns such a value.

JavaScript
$(function() {
    var dataGrid = $("#dataGridContainer").dxDataGrid({
        columns: [{
            dataField: 'Position',
            calculateSortValue: function (rowData) {
                if (rowData.Position == "CEO")
                    return dataGrid.option('Position', 'sortOrder') == 'asc' ? 0 : data.length; // CEOs must go first
                else
                    return rowData.Position; // Others are sorted as usual
            }
        }]
    }).dxDataGrid("instance");
});

caption

Specifies a caption for the column.

Type: String
Default Value: undefined

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.

Show Example:
AngularJS
Knockout
jQuery

In this example, the caption option specifies a more friendly name for the column that holds values from the "author_of_the_book" data source field.


                                    

                                    

In this example, the caption option specifies a more friendly name for the column that holds values from the "author_of_the_book" data source field.


                                    

                                    

In this example, the caption option specifies a more friendly name for the column that holds values from the "author_of_the_book" data source field.


                                    

                                    

cellTemplate

Specifies a custom template for column cells.

Type: template
Function parameters:
cellElement: jQuery
The cell that you are customizing.
cellInfo: Object
The settings of the cell.

Use this option to specify completely custom markup for column cells. See template for information on what this option accepts.

Below is the list of fields passed as the cellInfo object.

  • data: Object
    The data of the row to which the cell belongs.
  • component: jQuery
    The widget instance.
  • value: Any
    The value of the cell as it is specified in the data source.
  • displayValue: Any
    The display value of the cell. Differs from the value field only when the column uses lookup or calculateDisplayValue.
  • text: String
    displayValue after applying format and customizeText.
  • columnIndex: Number
    The index of the column to which the cell belongs. For more information on how this index is calculated, refer to the Calculating the Column Index topic.
  • rowIndex: Number
    The index of the row to which the cell belongs. Begins with 0 on each page. Group rows are included. For details on row indexes, see the Grid Rows topic.
  • column: Object
    The settings of the column to which the cell belongs.
  • rowType: String
    The type of the row to which the cell belongs. Equals "data" for ordinary rows or "group" for group rows.

It is also possible to define the template using the following template engines. You can access the aforementioned cell settings inside the template in a similar manner.

When you use a template engine, the cellTemplate option should be given a jQuery object or a DOM node representing the template's container, or a function that returns either of them.

NOTE
If you implement two-way data binding in your template, make sure that you have switched off the built-in implementation of this feature by setting the twoWayBindingEnabled option to false.

View Function Template Demo View Underscore Template Demo

See Also

columns

Columns banded by the current column.

Type: Array
Default Value: undefined

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 purpose, 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.

JavaScript
var dataGridOptions = {
    // ...
    columns: [{
        caption: 'Address',
        columns: ['City', 'Street', 'Apartment']
    }, {
        // ...
    }]
};

A nested column has almost every property a regular column has. These properties are described in the columns section of the Reference.

NOTE
There is an exception though: nested columns cannot be fixed alone, therefore specifying the fixed and fixedPosition properties for them is useless. However, the whole band column can be fixed as usual.

For example, the following code specifies the width and sortOrder properties of the "Street" column nested within the fixed "Address" band column.

JavaScript
var dataGridOptions = {
    // ...
    columns: [{
        caption: 'Address',
        fixed: true,
        fixedPosition: 'right',
        columns: [ 'City',
            {
                dataField: 'Street',
                width: 100,
                sortOrder: 'asc'
            },
            'Apartment']
    }, {
        // ...
    }]
};

Band columns support hierarchies of any nesting level. It means that the following structure is acceptable.

JavaScript
var dataGridOptions = {
    // ...
    columns: [{
        caption: 'A',
        columns: [ 'A1', 'A2', {
            caption: 'A3',
            columns: ['A31', 'A32', {
                caption: 'A33',
                columns: ['A331', 'A332', 'A333']
            }]
        }]
    }, {
        caption: 'B',
        columns: // ...
    }]
};

Band columns have the isBand flag. Banded columns have the ownerBand property set. Use these properties to distinguish band and banded columns from regular ones in code.

Watch Video

cssClass

Specifies a CSS class to be applied to the column.

Type: String
Default Value: undefined

Show Example:
jQuery

In this example, a grid contains five columns each of which has an applied CSS style. The styles are applied using the cssClass option. You can change the CSS style of a column at runtime with controls located below the grid. Choose a required column using radio buttons and a CSS style using a drop-down menu. To apply the style to the column, click the "Apply Style" button. To remove a style, click the "Remove Style" button.


                                    

                                    

                                    

customizeText

Customizes the text displayed in column cells.

Type: function(cellInfo)
Function parameters:
cellInfo: Object
The settings of a cell.
Object structure:
The value of the cell as it is specified in the data source.
valueText: String
The value of the cell with applied format.
target: String
Indicates the type of the UI element where the customizeText function was called.
Possible values: "filterRow", "headerFilter" and "search".
groupInterval: String|Number
Indicates how header filter values were combined into groups. Available if target is "headerFilter".
For possible values, see the description of the headerFilter | groupInterval option.
Return Value: String
The text for the cell.
NOTE
The customizeText function may be called when data displayed in the column matches the search condition to properly highlight the matching text.
See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, the data source field providing data for the "Language" column contains truncated identifiers of languages, i.e., 'EN' for 'English', 'GER' for 'German', etc. To display the full names of languages instead of identifiers, a callback function is implemented and assigned to the customizeText option of the "Language" column.


                                    

                                    

In this example, the data source field providing data for the "Language" column contains truncated identifiers of languages, i.e., 'EN' for 'English', 'GER' for 'German', etc. To display the full names of languages instead of identifiers, a callback function is implemented and assigned to the customizeText option of the "Language" column.


                                    

                                    

In this example, the data source field providing data for the "Language" column contains truncated identifiers of languages, i.e., 'EN' for 'English', 'GER' for 'German', etc. To display the full names of languages instead of identifiers, a callback function is implemented and assigned to the customizeText option of the "Language" column.


                                    

                                    

dataField

Binds the column to a field of the dataSource.

Type: String
Default Value: undefined

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.

JavaScript
$(function() {
    $("#dataGridContainer").dxDataGrid({
        // ...
        columns: [
            'CustomerID',
            { dataField: 'EmployeeID', width: 200 },
            'OrderDate',
            { dataField: 'Freight', format: 'fixedPoint' },
            'ShipName',
            'ShipCity'
        ]
    });
});
See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, the dataField option is used to specify data source fields for the "Title", "Position", "Birth Date" and "Hire Date" columns. Data source fields for the other columns are specified without using this option, because these columns do not require any customizations.


                                    

                                    

In this example, the dataField option is used to specify data source fields for the "Title", "Position", "Birth Date" and "Hire Date" columns. Data source fields for the other columns are specified without using this option, because these columns do not require any customizations.


                                    

                                    

In this example, the dataField option is used to specify data source fields for the "Title", "Position", "Birth Date" and "Hire Date" columns. Data source fields for the other columns are specified without using this option, because these columns do not require any customizations.


                                    

                                    

dataType

Casts column values to a specific data type.

Type: String
Default Value: undefined
Accepted Values: 'string' | 'number' | 'date' | 'boolean' | 'object'

If your data source stores, for example, numbers as strings, specify the proper data type using the dataType option.

Date-time values have the following specifics.

  • If date-time values are stored as strings, they should have one of the following formats: "yyyy/MM/dd", "yyyy/MM/dd HH:mm:ss", "yyyy-MM-ddTHH:mm:ssx" or "yyyy-MM-ddTHH:mm:ss".
  • To show both date and time in a column editor, set the format option to a value that includes date and time parts, and assign "datetime" to the editorOptions | type option as shown in the following code.

    JavaScript
    $(function() {
        $("#dataGridContainer").dxDataGrid({
            // ...
            columns: [{
                dataField: "HireDate",
                dataType: "date",
                format: "shortDateShortTime",
                editorOptions: { type: "datetime" }
            }]
        });
    });

When using the widget as an ASP.NET MVC Control, specify this option using the GridColumnDataType enum. This enum accepts the following values: String, Number, Date, Boolean and Object.

Show Example:
AngularJS
Knockout
jQuery

In this example, the data source fields providing data for the "Order Date" and "Shipped Date" columns contain values in a string format. To convert them into correct dates, set the dataType option for these columns to 'date'.


                                    

                                    

In this example, the data source fields providing data for the "Order Date" and "Shipped Date" columns contain values in a string format. To convert them into correct dates, set the dataType option for these columns to 'date'.


                                    

                                    

In this example, the data source fields providing data for the "Order Date" and "Shipped Date" columns contain values in a string format. To convert them into correct dates, set the dataType option for these columns to 'date'.


                                    

                                    

editCellTemplate

Specifies a custom template for column cells in the editing state.

Type: template
Function parameters:
cellElement: jQuery
The cell that you are customizing.
cellInfo: Object
The settings of the cell.

By default, a user edits a string value contained within a cell. Using the editCellTemplate option, you can specify completely custom markup for the cell so that it contains, for example, a combo box or another widget instead of the string value. See template for information on what the editCellTemplate option accepts.

Below is the list of fields passed as the cellInfo object.

  • data: Object
    The data of the row to which the cell belongs.
  • component: jQuery
    The widget instance.
  • value: Any
    The value of the cell as it is specified in the data source.
  • displayValue: Any
    The display value of the cell. Differs from the value field only when the column uses lookup or calculateDisplayValue.
  • text: String
    displayValue after applying format and customizeText.
  • columnIndex: Number
    The index of the column to which the cell belongs. For more information on how this index is calculated, refer to the Calculating the Column Index topic.
  • rowIndex: Number
    The index of the row to which the cell belongs. Begins with 0 on each page. Group rows are included. For details on row indexes, see the Grid Rows topic.
  • column: Object
    The settings of the column to which the cell belongs.
  • rowType: String
    The type of the row to which the cell belongs. Equals "data" for ordinary rows or "group" for group rows.
  • setValue(newValue): Method
    Saves the edited value. After this method is called, the editing process ends.

    NOTE
    A call of this method tells the widget that the value has been changed. Because of this, in batch edit mode, an edited cell can be highlighted even if its value was not actually changed, for example, if a user switched this cell into the editing state and then immediately switched it back without changing the value. To prevent this behavior, check that the value has actually been changed before calling the setValue(newValue) method.

It is also possible to define the template using the following template engines. You can access the aforementioned cell settings inside the template in a similar manner.

When you use a template engine, the editCellTemplate option should be given a jQuery object or a DOM node representing the template's container, or a function that returns either of them.

NOTE
If you implement two-way data binding in your template, make sure that you have switched off the built-in implementation of this feature by setting the twoWayBindingEnabled option to false.
See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, the cell editing feature is implemented using a template. Click the 'Edit' link to the right of any row and the corresponding cell will be transformed into a drop-down menu with a list of options. Open this menu, choose an option and click 'Save' to modify the grid's data source.


                                    

                                    

In this example, the cell editing feature is implemented using a template. Click the 'Edit' link to the right of any row and the corresponding cell will be transformed into a drop-down menu with a list of options. Open this menu, choose an option and click 'Save' to modify the grid's data source.


                                    

                                    

In this example, the cell editing feature is implemented using a template. Click the 'Edit' link to the right of any row and the corresponding cell will be transformed into a drop-down menu with a list of options. Open this menu, choose an option and click 'Save' to modify the grid's data source.


                                    

                                    

editorOptions

Specifies options for the underlain editor.

Type: Object

Depending on the dataType, the column offers a user different widgets for editing: TextBox, DateBox, Lookup, etc. In the editorOptions object, you can specify options for the editing widget.

NOTE

Do not specify the onValueChanged option in this object. If you need to add custom logic to the standard value change handler, override the handler in the onEditorPreparing function in the following manner.

JavaScript
$(function() {
    $("#dataGridContainer").dxDataGrid({
        // ...
        onEditorPreparing: function(e) {
            if (e.dataField == "requiredDataField") {
                var standardHandler = e.editorOptions.onValueChanged;
                e.editorOptions.onValueChanged = function(e) { // Overriding the standard handler
                    // ...
                    // Custom commands go here
                    // ...
                    standardHandler(e); // Calling the standard handler to save the edited value
                }
            }
        }
    });
});

encodeHtml

Specifies whether HTML tags are displayed as plain text or applied to the values of the column.

Type: Boolean
Default Value: true

When true, HTML tags are displayed as plain text; when false, they are applied to the values of the column.

Show Example:
jQuery

In this example, the values of the data source field providing data for the "Title" column contain HTML tags. Initially, these values are displayed with applied HTML tags, since the encodeHtml property of the column is set to false. You can change the value of this property at runtime by clicking the check box below the grid.


                                    

                                    

falseText

In a boolean column, replaces all false items with a specified text. Applies only if showEditorAlways option is false.

Type: String
Default Value: 'false'
See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, the "Is Discounted" column contains values of a boolean data type. The true and false values of this column are replaced by Yes and No using the trueText and falseText options. Note that the showEditorAlways option is set to false. This setting prohibits check boxes from representing boolean values.


                                    

                                    

In this example, the "Is Discounted" column contains values of a boolean data type. The true and false values of this column are replaced by Yes and No using the trueText and falseText options. Note that the showEditorAlways option is set to false. This setting prohibits check boxes from representing boolean values.


                                    

                                    

In this example, the "Is Discounted" column contains values of a boolean data type. The true and false values of this column are replaced by Yes and No using the trueText and falseText options. Note that the showEditorAlways option is set to false. This setting prohibits check boxes from representing boolean values.


                                    

                                    

filterOperations

Specifies a set of available filter operations. Applies only if filterRow | visible and allowFiltering are true.

Type: Array
Default Value: undefined
Accepted Values: '=' | '<>' | '<' | '<=' | '>' | '>=' | 'notcontains' | 'contains' | 'startswith' | 'endswith' | 'between'

The following table lists available filters by data types. The same filters are assigned to columns of a specific data type by default.

dataType filterOperations
"string" [ "contains", "notcontains", "startswith", "endswith", "=", "<>" ]
"numeric" [ "=", "<>", "<", ">", "<=", ">=", "between" ]
"date" [ "=", "<>", "<", ">", "<=", ">=", "between" ]

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.

When using the widget as an ASP.NET MVC Control, specify this option using the FilterOperations enum. This enum accepts the following values: Equal, NotEqual, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, NotContains, Contains, StartsWith, EndsWith and Between.

See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, filtering is enabled in a grid. Each column has a default set of available filter operations, except for "Order ID", whose set is restricted to only one filter operation using the filterOperations option. Hover over the magnifying glass icon of a column to see the list of filters available for this column.


                                    

                                    

In this example, filtering is enabled in a grid. Each column has a default set of available filter operations, except for "Order ID", whose set is restricted to only one filter operation using the filterOperations option. Hover over the magnifying glass icon of a column to see the list of filters available for this column.


                                    

                                    

In this example, filtering is enabled in a grid. Each column has a default set of available filter operations, except for "Order ID", whose set is restricted to only one filter operation using the filterOperations option. Hover over the magnifying glass icon of a column to see the list of filters available for this column.


                                    

                                    

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.

Type: String
Default Value: 'include'
Accepted Values: 'include' | 'exclude'

This option accepts the following values.

  • include
    Values in the header filter are unselected initially, and the user changes the filter by selecting, that is, including the values.
  • exclude
    All values in the header filter are selected initially, and the user changes the filter by clearing the selection of certain values, that is, by excluding them.

When using the widget as an ASP.NET MVC Control, specify this option using the FilterType enum. This enum accepts the following values: Include and Exclude.

See Also

filterValue

Specifies a filter value for the column.

Type: any
Default Value: undefined

You can specify a filter value for the column using this option as if a user set this value with the filter row. This value is applied using the selectedFilterOperation.

Show Example:
AngularJS
Knockout
jQuery

In this example, grid records are initially filtered by the "Author" column using its filterValue property. Also, the grid filter row is made visible in order to enable you to change the filtering.


                                    

                                    

In this example, grid records are initially filtered by the "Author" column using its filterValue property. Also, the grid filter row is made visible in order to enable you to change the filtering.


                                    

                                    

In this example, grid records are initially filtered by the "Author" column using its filterValue property. Also, the grid filter row is made visible in order to enable you to change the filtering.


                                    

                                    

filterValues

Specifies filter values for the column's header filter.

Type: Array
Default Value: undefined

You can specify filter values for the column using this option as if a user set them with the header filter.

fixed

Fixes the column.

Type: Boolean
Default Value: false
See Also

fixedPosition

Specifies the widget's edge to which the column is fixed. Applies only if columns[] | fixed is true.

Type: String
Default Value: undefined
Accepted Values: 'left' | 'right'

When using the widget as an ASP.NET MVC Control, specify this option using the HorizontalEdge enum. This enum accepts the following values: Left and Right.

See Also

format

Specifies a format for the values displayed in the column.

Type: Format
Default Value: ''
NOTE
DevExtreme widgets provide a wide choice of predefined formats. If you are, however, going to use custom formats, link the Globalize library to your project. Learn how to do this from topics in the Installation section.
See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, the "Freight" column contains values in a 'fixedPoint' format with a precision of 2. These parameters are specified using the format option of this column.


                                    

                                    

In this example, the "Freight" column contains values in a 'fixedPoint' format with a precision of 2. These parameters are specified using the format option of this column.


                                    

                                    

In this example, the "Freight" column contains values in a 'fixedPoint' format with a precision of 2. These parameters are specified using the format option of this column.


                                    

                                    

formItem

Configures the form item produced by this column in the editing state. Used only if editing | mode is "form" or "popup".

The SimpleItem section describes the options that you can specify in this object.

See Also

groupCellTemplate

Specifies a custom template for the group cell of a grid column.

Type: template
Function parameters:
cellElement: jQuery
The cell under customization.
cellInfo: Object
The options of the current cell.

By default, a group cell displays the name of the column used for grouping combined with the value from this column by which grid records are grouped. If you need to represent custom data in a group cell, use the groupCellTemplate option. Implement a callback function customizing the content of a group cell and assign it to this option. This function will be invoked every time the column with the specified template is involved in grouping.

When implementing the groupCellTemplate function, you can access the group cell under customization using the function's first parameter. This parameter provides access to element-related jQuery operations. In addition, you can access the options of the cell using the fields of the function's second parameter. These fields are listed below.

  • data
    Contains a data object that represents data items matching a grouping key. For example, if you group grid records by country, the following object can be obtained from the data field.

    JavaScript
    {
        key: 'Spain', // The name of a country
        items: [      // Data source objects corresponding to the key
            { ... }, 
            { ... },
            // ...
        ]
    }
  • component
    Contains the DataGrid instance.
  • value
    Contains the value of the current group cell as it is specified in a data source.
  • text
    Contains the value of the current group cell in a string format. Use this field to get a value with applied format.
  • displayValue
    Contains the value displayed by the current group cell. Differs from the value field only when the column to which the current cell belongs uses lookup.
  • columnIndex
    Contains the index of the column to which the current group cell belongs. For more information on how this index is calculated, refer to the Calculating the Column Index topic.
  • rowIndex
    Contains the index of the row that the current group cell occupies. For further information about row indexes, see the Grid Rows topic.
  • column
    Contains the settings of the column to which the current group cell belongs.
  • summaryItems
    An array of group summary items that are defined to be displayed in a group row. The array objects have the structure of the group summary items with an addition of the value (the summary item value) and columnCaption (usually used to present a summary value) fields.
  • groupContinuesMessage
    If the current group continues on the next page, this field contains a corresponding message. The value of this field equals the value of the grouping | groupContinuesMessage property. If the current group does not continue on the next page, this field equals undefined.
  • groupContinuedMessage
    If the current group is continued from the previous page, this field contains a corresponding message. The value of this field equals the value of the grouping | groupContinuedMessage property. If the current group is not continued from the previous page, this field equals undefined.
NOTE
When utilizing the Knockout or AngularJS library in your application, you can specify the template using the dxTemplate markup component.
See Also

It is also possible to define a group cell template in markup. For this purpose, use one of the following template engines. The above-mentioned cell settings can be accessed in a similar manner inside the template.

Using a template engine, pass one of the following values to the groupCellTemplate option.

  • A jQuery object representing the template's container.
  • A DOM Node representing the template's container.
  • A function that returns a jQuery object or a DOM Node representing the template's container.
Show Example:
AngularJS
Knockout
jQuery

In this example, the font style of group cells is altered using the callback function assigned to the groupCellTemplate option of each column.


                                    

                                    

In this example, the font style of group cells is altered using the callback function assigned to the groupCellTemplate option of each column.


                                    

                                    

In this example, the font style of group cells is altered using the callback function assigned to the groupCellTemplate option of each column.


                                    

                                    

groupIndex

Specifies the index of a column when grid records are grouped by the values of this column.

Type: Number
Default Value: undefined

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.

JavaScript
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.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    columns: [
        { dataField: 'FirstName', groupIndex: 1 },
        { dataField: 'LastName', groupIndex: 0 },
        // ...
    ]
});

View Demo

Show Example:
AngularJS
Knockout
jQuery

In this example, grid records are grouped initially by the "Format" column using the groupIndex option of this column, which is set to 0. Note that the group panel is not visible, thus, initial grouping cannot be changed by a user.


                                    

                                    

In this example, grid records are grouped initially by the "Format" column using the groupIndex option of this column, which is set to 0. Note that the group panel is not visible, thus, initial grouping cannot be changed by a user.


                                    

                                    

In this example, grid records are grouped initially by the "Format" column using the groupIndex option of this column, which is set to 0. Note that the group panel is not visible, thus, initial grouping cannot be changed by a user.


                                    

                                    

headerCellTemplate

Specifies a custom template for the column header.

Type: template
Function parameters:
columnHeader: jQuery
The header that you are customizing.
headerInfo: Object
The settings of the header.

Below is the list of fields passed as the headerInfo object.

  • component: jQuery
    The widget instance.
  • columnIndex: Number
    The index of the column to which the header belongs. For details on how this index is calculated, refer to the Calculating the Column Index topic.
  • column: Object
    The settings of the column to which the header belongs.

It is also possible to define the template using the following template engines. You can access the aforementioned header settings inside the template in a similar manner.

When you use a template engine, the headerCellTemplate option should be given a jQuery object or a DOM node representing the template's container, or a function that returns either of them.

See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, the font size of column headers is changed using the headerCellTemplate property.


                                    

                                    

In this example, the font size of column headers is changed using the headerCellTemplate property.


                                    

                                    

In this example, the font size of column headers is changed using the headerCellTemplate property.


                                    

                                    

headerFilter

Specifies data settings for the header filter.

Type: Object
Default Value: undefined
See Also

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".

Type: Number
Default Value: undefined

The lower the index assigned to this option, the higher the probability that this column is hidden. Indexes ascend from right to left beginning with 0 by default, which means that the rightmost column is hidden first when the widget adapts.

NOTE
Specifying hidingPriority for at least one column enables the column hiding feature and cancels the default hiding priorities.
See Also

isBand

Specifies whether the column bands other columns or not.

Type: Boolean
Default Value: undefined

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.

JavaScript
$(function() {
    $("#dataGridContainer").dxDataGrid({
        // ...
        columns: [{
            caption: 'Address',
            columns: ['City', 'Street', 'Apartment']
        }, {
            // ...
        }]
    });
});

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.

JavaScript
$(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
            }
        }
    });
});
NOTE
Band columns must not have the dataField option set.

The column with the isBand flag set to true can have the following properties only.

See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, columns are configured using the customizeColumns function. To declare band columns, the isBand and ownerBand properties are used.


                                    

                                    

In this example, columns are configured using the customizeColumns function. To declare band columns, the isBand and ownerBand properties are used.


                                    

                                    

In this example, columns are configured using the customizeColumns function. To declare band columns, the isBand and ownerBand properties are used.


                                    

                                    

lookup

Specifies options of a lookup column.

Type: Object
Default Value: undefined

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.

JavaScript
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.

JavaScript
$(function() {
    $("#dataGridContainer").dxDataGrid({
        dataSource: drivers,
        // ...
        columns: [{
            dataField: 'busID',
            lookup: {
                dataSource: buses,
                valueExpr: 'busID',
                displayExpr: 'plates'
            }
        }]
    });
});

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.

View Demo

See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, the "Format" is declared as a lookup column. To filter grid records by this column, use the select box appearing in this column's filter row cell. Additionally, you can edit grid records. Note that when you edit values in the "Format" column, a select box similar to the filtering one does not let you enter any values other than those represented in the select box.


                                    

                                    

In this example, the "Format" is declared as a lookup column. To filter grid records by this column, use the select box appearing in this column's filter row cell. Additionally, you can edit grid records. Note that when you edit values in the "Format" column, a select box similar to the filtering one does not let you enter any values other than those represented in the select box.


                                    

                                    

In this example, the "Format" is declared as a lookup column. To filter grid records by this column, use the select box appearing in this column's filter row cell. Additionally, you can edit grid records. Note that when you edit values in the "Format" column, a select box similar to the filtering one does not let you enter any values other than those represented in the select box.


                                    

                                    

minWidth

Specifies the minimum width of the column.

Type: Number
Default Value: undefined

name

Specifies the identifier of the column.

Type: String
Default Value: undefined

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.

Type: Number
Default Value: undefined

Main article: isBand

Show Example:
AngularJS
Knockout
jQuery

In this example, columns are configured using the customizeColumns function. To declare band columns, the isBand and ownerBand properties are used.


                                    

                                    

In this example, columns are configured using the customizeColumns function. To declare band columns, the isBand and ownerBand properties are used.


                                    

                                    

In this example, columns are configured using the customizeColumns function. To declare band columns, the isBand and ownerBand properties are used.


                                    

                                    

precision

Deprecated

Use the format | precision option instead.

Specifies a precision for formatted values displayed in a column.

Type: Number
Default Value: undefined

selectedFilterOperation

Specifies the selected filter operation for the column.

Type: String
Default Value: undefined
Accepted Values: '=' | '<>' | '<' | '<=' | '>' | '>=' | 'notcontains' | 'contains' | 'startswith' | 'endswith' | 'between'

By default, the selected filter operation depends on the data type of the column as follows.

dataTypeDefault filter operation
"string""contains"
"number""="
"date""="

When using the widget as an ASP.NET MVC Control, specify this option using the FilterOperations enum. This enum accepts the following values: Equal, NotEqual, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, NotContains, Contains, StartsWith, EndsWith and Between.

Show Example:
AngularJS
Knockout
jQuery

In this example, a default filter operation is specified for the "Title" column using the selectedFilterOperation property of this column.


                                    

                                    

In this example, a default filter operation is specified for the "Title" column using the selectedFilterOperation property of this column.


                                    

                                    

In this example, a default filter operation is specified for the "Title" column using the selectedFilterOperation property of this column.


                                    

                                    

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.

Type: function(rowData, value)
Function parameters:
rowData: Object
The data object where new data should be set.
value: any
The input value.

Using this function, you can process user input before it will be saved in the data source. This function accepts the rowData and value parameters. value is the user input that you should assign to one of the fields of the rowData. Initially, rowData is an empty object. Fill it with fields whose values should be saved in the data object of the current row.

JavaScript
$(function() {
    $("#dataGridContainer").dxDataGrid({
        // ...
        columns: [
            "field1",
            {
                dataField: "field2",
                setCellValue: function(rowData, value) {
                    rowData.field2 = value;
                    rowData.field1 = null;
                }
            },
            // ...
        ]
    });
});
NOTE
To invoke the default behavior, call the this.defaultSetCellValue(rowData, value) function.

showEditorAlways

Specifies whether the column displays its values using editors.

Type: Boolean
Default Value: false

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.

NOTE

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
Show Example:
AngularJS
Knockout
jQuery

In this example, the Is Discounted column contains boolean values. These values can be represented either by text or by check boxes. To change the form of representation, toggle the check box under the grid.


                                    

                                    

In this example, the Is Discounted column contains boolean values. These values can be represented either by text or by check boxes. To change the form of representation, toggle the check box under the grid.


                                    

                                    

In this example, the Is Discounted column contains boolean values. These values can be represented either by text or by check boxes. To change the form of representation, toggle the check box under the grid.


                                    

                                    

showInColumnChooser

Specifies whether the column chooser can contain the column header.

Type: Boolean
Default Value: true
See Also

showWhenGrouped

Specifies whether or not to display the column when grid records are grouped by it.

Type: Boolean
Default Value: false

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

Specifies the index according to which columns participate in sorting.

Type: Number
Default Value: undefined

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.

JavaScript
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.

JavaScript
$(function() {
    $("#dataGridContainer").dxDataGrid({
        // ...
        columns: [
            { dataField: 'firstName', sortIndex: 1, sortOrder: 'asc' },
            { dataField: 'lastName', sortIndex: 0, sortOrder: 'asc' },
            // ...
        ]
    });
});

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.

Show Example:
AngularJS
Knockout
jQuery

In this example, grid records appear sorted first by the "Author" column and then by the "Year" column. This sequence of applying sorting to columns is specified using the sortIndex option.


                                    

                                    

In this example, grid records appear sorted first by the "Author" column and then by the "Year" column. This sequence of applying sorting to columns is specified using the sortIndex option.


                                    

                                    

In this example, grid records appear sorted first by the "Author" column and then by the "Year" column. This sequence of applying sorting to columns is specified using the sortIndex option.


                                    

                                    

sortOrder

Specifies the sort order of column values.

Type: String
Default Value: undefined
Accepted Values: undefined | 'asc' | 'desc'

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.

When using the widget as an ASP.NET MVC Control, specify this option using the SortOrder enum. This enum accepts the following values: Asc and Desc.

See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, grid records are sorted initially by the "Year" column descending using the sortOrder option of this column set to 'desc'.


                                    

                                    

In this example, grid records are sorted initially by the "Year" column descending using the sortOrder option of this column set to 'desc'.


                                    

                                    

In this example, grid records are sorted initially by the "Year" column descending using the sortOrder option of this column set to 'desc'.


                                    

                                    

trueText

In a boolean column, replaces all true items with a specified text. Applies only if showEditorAlways option is false.

Type: String
Default Value: 'true'
See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, the "Is Discounted" column contains values of a boolean data type. The true and false values of this column are replaced by Yes and No using the trueText and falseText options. Note that the showEditorAlways option is set to false. This setting prohibits check boxes from indicating boolean values.


                                    

                                    

In this example, the "Is Discounted" column contains values of a boolean data type. The true and false values of this column are replaced by Yes and No using the trueText and falseText options. Note that the showEditorAlways option is set to false. This setting prohibits check boxes from indicating boolean values.


                                    

                                    

In this example, the "Is Discounted" column contains values of a boolean data type. The true and false values of this column are replaced by Yes and No using the trueText and falseText options. Note that the showEditorAlways option is set to false. This setting prohibits check boxes from indicating boolean values.


                                    

                                    

validationRules

Specifies validation rules to be checked on updating cell values.

Type: Array

visible

Specifies whether the column is visible or not.

Type: Boolean
Default Value: true

Show Example:
AngularJS
Knockout
jQuery

In this example, the "format" column is made invisible by setting its visible option to false.


                                    

                                    

In this example, the "format" column is made invisible by setting its visible option to false.


                                    

                                    

In this example, the "format" column is made invisible by setting its visible option to false.


                                    

                                    

visibleIndex

Specifies the position of the column regarding other columns in the resulting widget.

Type: Number
Default Value: undefined

width

Specifies the width of the column in pixels or percentages.

Type: Number|String
Default Value: undefined

This option is ignored if its value is less than minWidth.

See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, the "Title" column has a large fixed width, so that long book titles can fit in a column cell.


                                    

                                    

In this example, the "Title" column has a large fixed width, so that long book titles can fit in a column cell.


                                    

                                    

In this example, the "Title" column has a large fixed width, so that long book titles can fit in a column cell.