JavaScript/jQuery TreeList - columns

Configures columns.

Default Value: undefined

This option accepts an array of objects, where each object configures a single column. If a column does not need to be customized, this array may include the name of the field that provides data for this column.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            dataField: "Title",
            caption: "Position"
        }, {
            dataField: "FullName",
            width: 300
        }, 
            "CompanyName",
            "City"
        ]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxi-column dataField="Title" caption="Position"></dxi-column>
    <dxi-column dataField="FullName" [width]="300"></dxi-column>
    <dxi-column dataField="CompanyName"></dxi-column>
    <dxi-column dataField="City"></dxi-column>
</dx-tree-list>
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
See Also

alignment

Aligns the content of the column.

Type:

String

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

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

dataType alignment
'number' 'right'
'boolean' 'center'
'string' 'left'
'date' 'left'
'datetime' '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.

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

allowFiltering

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

Type:

Boolean

Default Value: true

See Also

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

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

allowReordering

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

Type:

Boolean

Default Value: true

allowResizing

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

Type:

Boolean

Default Value: true

See Also

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

calculateCellValue

Calculates custom values for column cells.

Type:

Function

Function parameters:
rowData:

Object

The 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 will be 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.
Filtering Set the allowFiltering option to true.
Searching Set the allowSearch option to true.
NOTE

To invoke the default behavior, call the this.defaultCalculateCellValue(rowData) function and return its result.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        columns: [{
            calculateCellValue: function (rowData) {
                // ...
                return this.defaultCalculateCellValue(rowData);
            }
        }]
    });
});
Angular
TypeScript
HTML
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    calculateCellValue (rowData) {
        // ...
        return this.defaultCalculateCellValue(rowData);
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
<dx-tree-list ... >
    <dxi-column [calculateCellValue]="calculateCellValue" ... ></dxi-column>
</dx-tree-list>
NOTE
The this keyword refers to the column's configuration.
See Also

calculateDisplayValue

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

Type:

String

|

Function

Function parameters:
rowData:

Object

The data of the row to which the cell belongs.

Return Value: any

The value for the cell to display.

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

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        columns: [{
            dataField: "countryID", // provides values for editing
            calculateDisplayValue: "country" // provides display values
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxi-column
        dataField="countryID" <!-- provides values for editing -->
        calculateDisplayValue="country"> <!-- provides display values -->
    </dxi-column>
</dx-tree-list>
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
ASP.NET MVC Controls
Razor C#
Razor VB
@(Html.DevExtreme().TreeList()
    .Columns(columns => columns.Add()
        .DataField("CountryID")
        .CalculateDisplayValue("Country")
    )
)
@(Html.DevExtreme().TreeList() _
    .Columns(Sub(columns)
        columns.Add() _
            .DataField("CountryID") _
            .CalculateDisplayValue("Country")
    End Sub)        
)

... or a function that combines display values.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        columns: [{
            dataField: "countryID", // provides values for editing
            calculateDisplayValue: function (rowData) { // combines display values
                return rowData.capital + " (" + rowData.country + ")";
            }
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxi-column
        dataField="countryID" <!-- provides values for editing -->
        [calculateDisplayValue]="getCountryWithCapital"> <!-- combines display values -->
    </dxi-column>
</dx-tree-list>
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    getCountryWithCapital(rowData) {
        return rowData.capital + " (" + rowData.country + ")";
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
ASP.NET MVC Controls
Razor C#
Razor VB
@(Html.DevExtreme().TreeList()
    .Columns(columns => columns.Add()
        .DataField("CountryID")
        .CalculateDisplayValue(new JS("getCountryWithCapital"))
    )
)

<script>
    function getCountryWithCapital(rowData) {
        return rowData.capital + " (" + rowData.country + ")";
    }        
</script>
@(Html.DevExtreme().TreeList() _
    .Columns(Sub(columns)
        columns.Add() _
            .DataField("CountryID") _
            .CalculateDisplayValue(New JS("getCountryWithCapital"))
    End Sub)        
)

<script>
    function getCountryWithCapital(rowData) {
        return rowData.capital + " (" + rowData.country + ")";
    }        
</script>    
NOTE
The this keyword refers to the column's configuration.

Do not use this option to format text in cells. Use customizeText for this.

See Also

calculateFilterExpression

Specifies the column's custom filtering rules.

Type:

Function

Function parameters:
filterValue: any

A user input value.

selectedFilterOperation:

String

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

    NOTE
    For 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.

The following code shows the default calculateFilterExpression function implementation. You can change it as required.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        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
TypeScript
HTML
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    calculateFilterExpression (filterValue, selectedFilterOperation) {
        // Implementation for the "between" comparison operator
        if (selectedFilterOperation === "between" && Array.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);
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
<dx-tree-list ... >
    <dxi-column [calculateFilterExpression]="calculateFilterExpression" ... ></dxi-column>
</dx-tree-list>

In the previous code, the defaultCalculateFilterExpression function invokes the default behavior. You can omit the function call if you do not need it.

NOTE
The this keyword refers to the column's configuration.

calculateSortValue

Calculates custom values to be used in sorting.

Type:

String

|

Function

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

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        columns: [{
            dataField: "Position", // provides values for the column
            calculateSortValue: "isOnVacation" // provides values to be used in sorting 
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxi-column
        dataField="Position" <!--provides values for the column -->
        calculateSortValue="isOnVacation"> <!-- provides values to be used in sorting -->
    </dxi-column>
</dx-tree-list>
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

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

jQuery
JavaScript
$(function() {
    var treeList = $("#treeListContainer").dxTreeList({
        columns: [{
            dataField: 'Position',
            sortOrder: "asc",
            calculateSortValue: function (rowData) {
                if (rowData.Position == "CEO")
                    return treeList.columnOption('Position', 'sortOrder') == 'asc' ? "aaa" : "zzz"; // CEOs are always displayed at the top
                else
                    return rowData.Position; // Others are sorted as usual
            }
        }]
    }).dxTreeList("instance");
});
Angular
TypeScript
HTML
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    customSortingFunction (rowData) {
        if (rowData.Position == "CEO")
            return this.sortOrder == 'asc' ? "aaa" : "zzz"; // CEOs are always displayed at the top
        else
            return rowData.Position; // Others are sorted as usual
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
<dx-tree-list ... >
    <dxi-column
        dataField="Position"
        sortOrder="asc"
        [calculateSortValue]="customSortingFunction">
    </dxi-column>
</dx-tree-list>
NOTE
The this keyword refers to the column's configuration.

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.

cellTemplate

Specifies a custom template for column cells.

Type:

template

Template Data:

HTMLElement | jQuery

The current cell's container. It is an HTML Element or a jQuery Element when you use jQuery.

The cellInfo object has the following fields:

  • data: Object
    Data of the row to which the cell belongs.
  • component: Object
    The widget's 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.
  • rowIndex: Number
    The index of the row to which the cell belongs. Begins with 0 on each page.
  • column: Object
    The settings of the column to which the cell belongs.
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

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, 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
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            caption: 'Address',
            columns: ['City', 'Street', 'Apartment']
        }, {
            // ...
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <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-tree-list>
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

A nested column has almost every option a regular column has. These options 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 options for them is useless. However, the whole band column can be fixed as usual.

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

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            caption: 'Address',
            fixed: true,
            fixedPosition: 'right',
            columns: [
                'City', {
                    dataField: 'Street',
                    width: 100,
                    sortOrder: 'asc'
                },
                'Apartment'
            ]
        }, {
            // ...
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <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-tree-list>
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

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

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            caption: 'A',
            columns: [ 'A1', 'A2', {
                caption: 'A3',
                columns: ['A31', 'A32', {
                    caption: 'A33',
                    columns: ['A331', 'A332', 'A333']
                }]
            }]
        }, {
            caption: 'B',
            columns: // ...
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <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-tree-list>
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

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.

Type:

String

Default Value: undefined

customizeText

Customizes the text displayed in column cells.

Type:

Function

Function parameters:
cellInfo:

Object

Information on the current cell.

Object structure:
Name Type Description
value

String

|

Number

|

Date

The cell's raw value.

valueText

String

The fomatted value converted to a string.

target

String

The UI element where the customizeText function was called: "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 to display.

The customizeText function may be called when data displayed in the column matches the search condition to properly highlight the matching text.

NOTE
The this keyword refers to the column's configuration.
See Also

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.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [
            'CustomerID',
            { dataField: 'EmployeeID', width: 200 },
            'OrderDate',
            { dataField: 'Freight', format: 'fixedPoint' },
            'ShipName',
            'ShipCity'
        ]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <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-tree-list>
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
See Also

dataType

Casts column values to a specific data type.

Type:

String

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

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

NOTE
Date-time values stored as strings 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".

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, DateTime, Boolean and Object.

See Also

editCellTemplate

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

Type:

template

Template Data:

HTMLElement | jQuery

The current cell's container. It is an HTML Element or a jQuery Element when you use jQuery.

The cellInfo object has the following fields:

  • setValue(newValue, newText): Method
    A method that 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 changed before calling this method. This ensures the cells are highlighted correctly.
  • data: Object
    The data of the row the cell belongs to.

  • component: Object
    The widget's instance.
  • value: Any
    The cell value as it is specified in the data source.
  • displayValue: Any
    The displayed cell value. 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 the cell belongs to.
  • rowIndex: Number
    The index of the row the cell belongs to. Begins with 0 on each page.
  • column: Object
    The settings of the column the cell belongs to.
NOTE
If you implement two-way data binding in your template, make sure that you have switched off this feature's built-in implementation by setting the twoWayBindingEnabled option to false.
See Also

editorOptions

Specifies options for the underlain editor.

Type:

Object

Depending on the dataType, the column offers a user different widgets for editing and filtering (using the filter row): TextBox, DateBox, Lookup, etc. In the editorOptions object, you can specify options for the 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.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        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
                }
            }
        }
    });
});
Angular
TypeScript
HTML
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    onEditorPreparing (e) {
        if (e.dataField == "requiredDataField") {
            let 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
            }
        }
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
<dx-data-grid ... 
    (onEditorPreparing)="onEditorPreparing($event)">
</dx-data-grid>

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.

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

filterOperations

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

Type:

Array<String>

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

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: 'exclude' | 'include'

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.

filterValues

Specifies filter values for the column's header filter.

Type:

Array<any>

Default Value: undefined

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

See Also

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

Formats a value before it is displayed in a column cell.

Type:

Format

Default Value: ''

This option also controls the user input in cells that use the DateBox widget for editing. For cells that use other widgets, you can specify the editorOptions.format option.

jQuery
JavaScript
$(function(){
    $("#treeListContainer").dxTreeList({
        dataSource: orders,
        editing: {
            allowUpdating: true
        },
        columns: [{
            dataField: "SaleAmount",
            format: "currency",
            editorOptions: {
                format: "$ #,##0.##"
            }
        }, 
        // ...
        ]
    });
});
Angular
HTML
<dx-tree-list
    [dataSource]="orders">
    <dxo-editing [allowUpdating]="true"></dxo-editing>
    <dxi-column
        dataField="SaleAmount"
        format="currency"
        [editorOptions]="{ format: '$ #,##0.##' }">
    </dxi-column>
</dx-tree-list>
See Also

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

headerCellTemplate

Specifies a custom template for column headers.

Type:

template

Template Data:

HTMLElement | jQuery

The current header's container. It is an HTML Element or a jQuery Element when you use jQuery.

The headerInfo object has the following fields:

  • component: Object
    The widget's instance.
  • columnIndex: Number
    The index of the column to which the header belongs.
  • column: Object
    The settings of the column to which the header belongs.
See Also

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 hidingPriority is a unique positive integer that ascends from right to left beginning with 0 by default. Columns with low hidingPriority are hidden first.

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.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            caption: 'Address',
            columns: ['City', 'Street', 'Apartment']
        }, {
            // ...
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <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-tree-list>
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

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
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        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
TypeScript
HTML
import { DxTreeListModule } 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: [
        // ...
        DxTreeListModule
    ],
    // ...
})
<dx-tree-list ...
    [customizeColumns]="customizeColumns">
</dx-tree-list>
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

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.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        dataSource: drivers,
        // ...
        columns: [{
            dataField: 'busID',
            lookup: {
                dataSource: buses,
                valueExpr: 'busID',
                displayExpr: 'plates'
            }
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list [dataSource]="drivers">
    <dxi-column dataField="busID">
        <dxo-lookup
            [dataSource]="buses"
            valueExpr="busID"
            displayExpr="plates">
        </dxo-lookup>
    </dxi-column>
</dx-tree-list>
import { DxTreeListModule } 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: [
        // ...
        DxTreeListModule
    ],
    // ...
})

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

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

selectedFilterOperation

Specifies the selected filter operation for the column.

Type:

String

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

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.

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.

Type:

Function

Function parameters:
newData:

Object

The data object where new data should be set.

value: any

The input value.

currentRowData:

Object

A read-only parameter providing access to the current row data.

Using this function, you can process user input before it is saved to the data source. This function accepts the newData, value and currentRowData parameters. value is the user input that you should assign to one of the fields of the newData. Initially, newData is an empty object. Fill it with fields whose values should be saved in the data object of the current row. currentRowData is a read-only parameter used to access the current row data.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [
            "Price",
            {
                dataField: "Count",
                dataType: "number",
                setCellValue: function(newData, value, currentRowData) {
                    newData.Count = value;
                    newData.TotalPrice = currentRowData.Price * value;
                }
            },
            "TotalPrice",
            // ...
        ]
    });
});
Angular
TypeScript
HTML
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    setCellValue (newData, value, currentRowData) {
        newData.Count = value;
        newData.TotalPrice = currentRowData.Price * value;
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
<dx-tree-list ... >
    <dxi-column dataField="Price"></dxi-column>
    <dxi-column
        dataField="Count"
        dataType="number"
        [setCellValue]="setCellValue">
    </dxi-column>
    <dxi-column dataField="TotalPrice"></dxi-column>
</dx-tree-list>

To invoke the default behavior, call the this.defaultSetCellValue(newData, value) function.

NOTE
The this keyword refers to the column's configuration.

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

showInColumnChooser

Specifies whether the column chooser can contain the column header.

Type:

Boolean

Default Value: true

See Also

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.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [
            { dataField: 'firstName', sortIndex: 1, sortOrder: 'asc' },
            { dataField: 'lastName', sortIndex: 0, sortOrder: 'asc' },
            // ...
        ]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxi-column dataField="firstName" [sortIndex]="1" sortOrder="asc"></dxi-column>
    <dxi-column dataField="lastName" [sortIndex]="0" sortOrder="asc"></dxi-column>
</dx-tree-list>
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

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.

Type:

Function

Function parameters:
value1: any

A value to be compared.

value2: any

A value to be compared.

Return Value:

Number

Specifies whether value1 goes before value2.

Default Value: undefined

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
JavaScript
$(function () {
    $("#treeListContainer").dxTreeList({
        // ...
        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
TypeScript
HTML
import { DxTreeListModule } 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: [
        // ...
        DxTreeListModule
    ],
    // ...
})
<dx-tree-list ... >
    <dxi-column
        dataField="fieldName"
        [sortingMethod]="sortStringsConsideringCulture">
    </dxi-column>
</dx-tree-list>
NOTE
The sortingMethod's value1 and value2 are the values returned from the calculateSortValue function if the latter is specified.
NOTE
The this keyword refers to the column's configuration.

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

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

validationRules

Specifies validation rules to be checked on updating cell values.

visible

Specifies whether the column is visible, that is, occupies space in the table.

Type:

Boolean

Default Value: true

visibleIndex

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

Type:

Number

Default Value: undefined

NOTE
This index is used in column reordering only. Do not confuse it with the visible column index, which is used to manipulate cells by calling methods, such as getCellElement(rowIndex, visibleColumnIndex), editCell(rowIndex, visibleColumnIndex), etc.
See Also

width

Specifies the column's width in pixels or as a percentage. Ignored if it is less than minWidth.

Type:

Number

|

String

Default Value: undefined

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

    NOTE
    Fixed columns ignore widths specified as a percentage.
See Also