JavaScript/jQuery TreeList Methods

|

The column's configuration or a data field for which the column should be created.

addRow()

Adds an empty data row to the highest hierarchical level.

addRow(parentId)

Adds an empty data row to a specified parent row.

Parameters:

parentId: any

The parent row's ID.

beginCustomLoading(messageText)

Shows the load panel.

Parameters:

messageText:

The text for the load panel to display.

Normally, the load panel is invoked automatically while the widget is busy rendering or loading data. Additionally, you can invoke it by calling this method. If you call it without the argument, the load panel displays text specified by the loadPanel.text option. To specify the appearance of the load panel, use the loadPanel object. Once invoked from code, the load panel will not hide until you call the endCustomLoading() method.

NOTE

The load panel invoked from code does not replace the automatically invoked load panel. This circumstance might lead to a situation where the load panel invoked from code suddenly changes its text because it was overridden by the automatically invoked load panel. Therefore, be mindful when invoking the load panel with different text.

beginUpdate()

Prevents the widget from refreshing until the endUpdate() method is called.

The beginUpdate() and endUpdate() methods prevent the widget from excessive updates when you are changing multiple widget settings at once. After the beginUpdate() method is called, the widget does not update its UI until the endUpdate() method is called.

byKey(key)

Gets a data object with a specific key.

Parameters:

key:

|

|

The data object's key.

Return Value:

Promise<Object> (jQuery or native)

A Promise that is resolved after the data object is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

The following code shows how to get a data object whose key is 15.

JavaScript

widgetInstance.byKey(15).done(function(dataObject) {
        // process "dataObject"
    }).fail(function(error) {
        // handle error
    });

cancelEditData()

Discards changes that a user made to data.

cellValue(rowIndex, dataField)

Gets the value of a cell with a specific row index and a data field, column caption or name.

Parameters:

rowIndex:

The index of the row to which the cell belongs. Refer to Column and Row Indexes for more information.

dataField:

The data field, caption, or unique name of the column to which the cell belongs.

Return Value: any

The cell's value.

cellValue(rowIndex, dataField, value)

Sets a new value to a cell with a specific row index and a data field, column caption or name.

Parameters:

rowIndex:

The index of the row to which the cell belongs. Refer to Column and Row Indexes for more information.

dataField:

The data field, caption, or unique name of the column to which the cell belongs.

value: any

The cell's new value.

Call saveEditData() after this method to save the changes:

jQuery

JavaScript

var treeList = $("#treeListContainer").dxTreeList("instance");
treeList.cellValue(0, "Position", "CEO");
treeList.saveEditData();

Angular

TypeScript

import { ..., ViewChild } from "@angular/core";
import { DxTreeListModule, DxTreeListComponent } from "devextreme-angular";
// ...
export class AppComponent {
    @ViewChild(DxTreeListComponent, { static: false }) treeList: DxTreeListComponent;
    // Prior to Angular 8
    // @ViewChild(DxTreeListComponent) treeList: DxTreeListComponent;
    updateCell(rowIndex, dataField, value) {
        this.treeList.instance.cellValue(rowIndex, dataField, value);
        this.treeList.instance.saveEditData();
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

cellValue(rowIndex, visibleColumnIndex)

Gets the value of a cell with specific row and column indexes.

Parameters:

rowIndex:

The index of the row to which the cell belongs. Refer to Column and Row Indexes for more information.

visibleColumnIndex:

The visible index of the column to which the cell belongs.

Return Value: any

The cell's value.

cellValue(rowIndex, visibleColumnIndex, value)

Sets a new value to a cell with specific row and column indexes.

Parameters:

rowIndex:

The index of the row to which the cell belongs. Refer to Column and Row Indexes for more information.

visibleColumnIndex:

The visible index of the column to which the cell belongs.

value: any

The cell's new value.

Call saveEditData() after this method to save the changes:

jQuery

JavaScript

var treeList = $("#treeListContainer").dxTreeList("instance");
treeList.cellValue(0, 1, "newValue");
treeList.saveEditData();

Angular

TypeScript

import { ..., ViewChild } from "@angular/core";
import { DxTreeListModule, DxTreeListComponent } from "devextreme-angular";
// ...
export class AppComponent {
    @ViewChild(DxTreeListComponent, { static: false }) treeList: DxTreeListComponent;
    // Prior to Angular 8
    // @ViewChild(DxTreeListComponent) treeList: DxTreeListComponent;
    updateCell(rowIndex, columnIndex, value) {
        this.treeList.instance.cellValue(rowIndex, columnIndex, value);
        this.treeList.instance.saveEditData();
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

clearFilter()

Clears all filters applied to widget rows.

clearFilter(filterName)

Clears all row filters of a specific type.

Parameters:

filterName:

The filter type.

The method's parameter specifies what type of filter should be cleared. This parameter can have one of the following values:

"row"
Clears the filter row.
"header"
Clears the header filter.
"filterValue"
Clears the filter builder and the synchronized filtering UI elements.
"search"
Clears the search panel.
"dataSource"
Clears the data source filter defined in the configuration or applied by the filter(filterExpr) method.

clearSelection()

Clears selection of all rows on all pages.

clearSorting()

Clears sorting settings of all columns at once.

closeEditCell()

Switches the cell being edited back to the normal state. Takes effect only if editing.mode is batch and showEditorAlways is false.

collapseAdaptiveDetailRow()

Collapses the currently expanded adaptive detail row (if there is one).

collapseRow(key)

Collapses a row with a specific key.

Parameters:

key: any

The row's key.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after the row is collapsed. It is a native Promise or a jQuery.Promise when you use jQuery.

columnCount()

Gets the data column count. Includes visible and hidden columns, excludes command columns.

Return Value:

The data column count.

columnOption(id)

Gets all options of a column with a specific identifier.

Parameters:

id:

|

The column's index, data field, caption, type, or unique name.

Return Value:

The column's options.

This method gets the options of the first column found by either of the below:

Name
The unique name of the column.
Column Index
The index of the column in the columns array.
Data Field
The name of the data source field assigned to the column.
Caption
The text displayed in the column header.
Type (command columns only)
The type of the command column.
Service String
Any string matching the following format: "optionName:value", where optionName is one of the column options.

columnOption(id, optionName)

Gets the value of a single column option.

Parameters:

id:

|

The column's index, data field, caption, type, or unique name. Refer to columnOption(id) for details.

optionName:

The option's name.

Return Value: any

The option's value.

columnOption(id, optionName, optionValue)

Updates the value of a single column option.

Parameters:

id:

|

The column's index, data field, caption, type, or unique name. Refer to columnOption(id) for details.

optionName:

The option's name.

optionValue: any

The option's new value.

columnOption(id, options)

Updates the values of several column options.

Parameters:

id:

|

The column's index, data field, caption, type, or unique name. Refer to columnOption(id) for details.

options:

The options with their new values.

defaultOptions(rule)

Specifies the device-dependent default configuration options for this component.

Parameters:

rule:

The component's default device options.

Object structure:

Name	Type	Description
device	Device \| Array<Device> \| Function	Device parameters. When specifying a function, get information about the current device from the argument. Return true if the options should be applied to the device.
options	Object	Options to be applied.

Name

Type

Description

device

Device

|

Array<Device>

|

Device parameters.
When specifying a function, get information about the current device from the argument. Return true if the options should be applied to the device.

options

Options to be applied.

defaultOptions is a static method that the widget class supports. The following code demonstrates how to specify default options for all instances of the TreeList widget in an application executed on the desktop.

jQuery

JavaScript

DevExpress.ui.dxTreeList.defaultOptions({ 
    device: { deviceType: "desktop" },
    options: {
        // Here go the TreeList options
    }
});

Angular

TypeScript

import TreeList from "devextreme/ui/tree_list";
// ...
export class AppComponent {
    constructor () {
        TreeList.defaultOptions({
            device: { deviceType: "desktop" },
            options: {
                // Here go the TreeList options
            }
        });
    }
}

Vue

<template>
    <div>
        <DxTreeList id="treeList1" />
        <DxTreeList id="treeList2" />
    </div>
</template>
<script>
import DxTreeList from "devextreme-vue/tree-list";
import TreeList from "devextreme/ui/tree_list";

TreeList.defaultOptions({
    device: { deviceType: "desktop" },
    options: {
        // Here go the TreeList options
    }
});

export default {
    components: {
        DxTreeList
    }
}
</script>

React

import React from "react";
import dxTreeList from "devextreme/ui/tree_list";
import TreeList from "devextreme-react/tree-list";

class App extends React.Component {
    render () {
        dxTreeList.defaultOptions({
            device: { deviceType: "desktop" },
            options: {
                // Here go the TreeList options
            }
        })
        return (
            <div>
                <TreeList id="treeList1" />
                <TreeList id="treeList2" />
            </div>
        )
    }
}

export default App;

deleteColumn(id)

Removes a column.

Parameters:

id:

|

The column's index, data field, caption or unique name.

This method removes the first column found by either of the below:

Name
The unique name of the column.
Column Index
The index of the column in the columns array.
Data Field
The name of the data source field assigned to the column.
Caption
The text displayed in the column header.

deleteRow(rowIndex)

Removes a row with a specific index.

Parameters:

rowIndex:

The row's index. Refer to Column and Row Indexes for more information.

NOTE

You cannot call this method to delete a row if this row is being edited in row or form editing mode. In these modes, you can modify only one row at a time and you should finish the row edit to call this method.

deselectAll()

Clears the selection of all rows on all pages or the currently rendered page only.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after the selection is cleared. It is a native Promise or a jQuery.Promise when you use jQuery.

deselectRows(keys)

Cancels the selection of rows with specific keys.

Parameters:

keys:

Array<any>

The row keys.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after selection is cleared. It is a native Promise or a jQuery.Promise when you use jQuery.

dispose()

Disposes of all the resources allocated to the TreeList instance.

After calling this method, remove the DOM element associated with the widget:

jQuery

JavaScript

$("#myTreeList").dxTreeList("dispose");
$("#myTreeList").remove();

Angular

HTML

<dx-tree-list #treeListVar id="myTreeList"></dx-tree-list>

TypeScript

import { ..., ViewChild } from "@angular/core";
import { DxTreeListComponent } from "devextreme-angular";
// ...
export class AppComponent {
    @ViewChild("treeListVar", { static: false }) treeList: DxTreeListComponent;
    // Prior to Angular 8
    // @ViewChild("treeListVar") treeList: DxTreeListComponent;

    removeTreeList (e) {
        this.treeList.instance.dispose();
        document.getElementById("myTreeList").remove();
    }
}

editCell(rowIndex, dataField)

Switches a cell with a specific row index and a data field to the editing state. Takes effect only if the editing mode is "batch" or "cell".

Parameters:

rowIndex:

The index of the row to which the cell belongs. Refer to Column and Row Indexes for more information.

dataField:

The name of the data field in the data source.

editCell(rowIndex, visibleColumnIndex)

Switches a cell with specific row and column indexes to the editing state. Takes effect only if the editing mode is "batch" or "cell".

Parameters:

rowIndex:

A Promise that is resolved after the row is expanded. It is a native Promise or a jQuery.Promise when you use jQuery.

filter()

Gets a filter expression applied to the widget's data source using the filter(filterExpr) method and the DataSource's filter option.

Return Value: any

filter(filterExpr)

Applies a filter to the widget's data source.

Parameters:

filterExpr: any

Pass an array with the following members to this method:

The data source field by which data items are filtered.
The comparison operator. The following operators are available: "=", "<>", ">", ">=", "<", "<=", "startswith", "endswith", "contains", "notcontains".
The value with which data source field values should be compared.

A function to be executed; return false to stop traversing deeper.

getCellElement(rowIndex, dataField)

Gets a cell with a specific row index and a data field, column caption or name.

Parameters:

rowIndex:

The index of the row to which the cell belongs. Refer to Column and Row Indexes for more information.

dataField:

The data field, caption, or unique name of the column to which the cell belongs.

Return Value:

HTMLElement | jQuery

| undefined

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

If the specified row or data field does not exist, the method returns undefined.

getCellElement(rowIndex, visibleColumnIndex)

Gets a cell with specific row and column indexes.

Parameters:

rowIndex:

The index of the row to which the cell belongs. Refer to Column and Row Indexes for more information.

visibleColumnIndex:

The visible index of the column to which the cell belongs.

Return Value:

HTMLElement | jQuery

| undefined

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

If the specified row or column does not exist, the method returns undefined.

getCombinedFilter()

Gets the total filter that combines all the filters applied.

Return Value: any

Use this method to get the total filter. This filter combines filters applied using filtering UI elements and the filter(filterExpr) method. Note that the total filter contains getters. To get the total filter containing data fields, call the getCombinedFilter(returnDataField) method.

getCombinedFilter(returnDataField)

Gets the total filter that combines all the filters applied.

Parameters:

returnDataField:

Specifies whether the total filter should contain data fields instead of getters.

Return Value: any

Use this method to get the total filter. This filter combines filters applied using filtering UI elements and the filter(filterExpr) method.

getDataSource()

Gets the DataSource instance.

Return Value:

DataSource

The DataSource instance.

NOTE

This method returns the DataSource instance even if the widget's dataSource option was given a simple array.

getInstance(element)

Gets the instance of a widget found using its DOM node.

Parameters:

element:

DOM Node

|

jQuery

The widget's container.

Return Value:

The widget's instance.

getInstance is a static method that the widget class supports. The following code demonstrates how to get the TreeList instance found in an element with the myTreeList ID:

// Modular approach
import TreeList from "devextreme/ui/tree_list";
...
let element = document.getElementById("myTreeList");
let instance = TreeList.getInstance(element) as TreeList;

// Non-modular approach
let element = document.getElementById("myTreeList");
let instance = DevExpress.ui.dxTreeList.getInstance(element);

getScrollable()

Gets the instance of the widget's scrollable part.

Return Value:

Scrollable

The scrollable part's instance.

For information on API members of the scrollable part, refer to the ScrollView section, but bear in mind that several members described there are unavailable. Those are the following.

Options:

pullingDownText
pulledDownText
refreshingText
reachBottomText
onPullDown
onReachBottom

Methods:

release(preventScrollBottom)
refresh()

getSelectedRowKeys()

Gets the keys of the rows selected explicitly via the API or via a click or tap.

Return Value:

Array<any>

Keys of selected rows. The keys are stored in the order the user selects rows.

getSelectedRowKeys(leavesOnly)

Use the getSelectedRowKeys(mode) method instead.

Gets the selected rows' keys.

Parameters:

leavesOnly:

Specifies whether this method returns only leaves' keys.

Return Value:

Array<any>

Keys of selected rows. The keys are stored in the order the user selects rows.

getSelectedRowKeys(mode)

Gets the selected rows' keys.

Parameters:

mode:

"all", "excludeRecursive", or "leavesOnly".

Return Value:

Array<any>

Keys of selected rows. The keys are stored in the order the user selects rows.

Below is an example of a TreeList with several selected rows:

Selection in the DevExtreme TreeList widget

The getSelectedRowKeys(mode) method called for this TreeList returns different results depending on the mode argument:

"all"
Returns all the selected rows' keys.

getSelectedRowKeys("all") // returns [2, 5, 8, 9, 6, 10, 4]

"excludeRecursive"
Excludes recursively selected rows' keys.

getSelectedRowKeys("excludeRecursive") // returns [2, 6, 10, 4]

"leavesOnly"
Returns only leaves' keys.

getSelectedRowKeys("leavesOnly") // returns [8, 9, 6, 10, 4]

getSelectedRowsData()

Gets the data objects of the rows selected explicitly via the API or via a click or tap.

Return Value:

Array<any>

The selected rows' data objects.
The objects are not processed by the DataSource and have the same order in which the rows were selected.

jQuery

index.js

var treeList = $("#treeListContainer").dxTreeList("instance");

var selectedRowsData = treeList.getSelectedRowsData();

Angular

app.component.ts

app.component.html

app.module.ts

import { Component, ViewChild } from '@angular/core';
import { DxTreeListComponent } from 'devextreme-angular';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    @ViewChild('treeListRef', { static: false }) treeList: DxTreeListComponent;
    // Prior to Angular 8
    // @ViewChild('treeListRef') treeList: DxTreeListComponent;

    selectedRowsData = [];

    getSelectedData() {
        this.selectedRowsData = this.treeList.instance.getSelectedRowsData();
    }
}

<dx-tree-list ...
    #treeListRef
></dx-tree-list>

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxTreeListModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxTreeListModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }

Vue

App.vue

<template>
    <DxTreeList ...
        :ref="treeListRef">
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import DxTreeList from 'devextreme-vue/tree-list';

const treeListRef = 'treeList';

export default {
    components: {
        DxTreeList
    },
    data() {
        return {
            treeListRef,
            selectedRowsData: []
        }
    },
    computed: {
        treeList: function() {
            return this.$refs[treeListRef].instance;
        }
    },
    methods: {
        getSelectedData() {
            this.selectedRowsData = this.treeList.getSelectedRowsData();
        }
    }
}
</script>

React

App.js

import React from 'react';

import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import TreeList from 'devextreme-react/tree-list';

class App extends React.Component {
    constructor(props) {
        super(props);

        this.treeListRef = React.createRef();

        this.selectedRowsData = [];

        this.getSelectedData = () => {
            this.selectedRowsData = this.treeList.getSelectedRowsData();
        }
    }

    get treeList() {
        return this.treeListRef.current.instance;
    }

    render() {
        return (
            <TreeList ...
                ref={this.treeListRef}>
            </TreeList>
        );
    }
}
export default App;

ASP.NET MVC Controls

Razor C#

@(Html.DevExtreme().TreeList()
    .ID("treeList")
    @* ... *@
)

<script type="text/javascript">
    function getSelectedData() {
        var treeList = $("#treeList").dxTreeList("instance");
        var selectedRowsData = treeList.getSelectedRowsData();
        // ...
    }
</script>

NOTE

Calculated values cannot be obtained because this method gets data objects from the data source.

getSelectedRowsData(mode)

Gets the selected rows' data objects.

Parameters:

mode:

"all", "excludeRecursive", or "leavesOnly".

Return Value:

Array<any>

The selected rows' data objects.
The objects are not processed by the DataSource and have the same order in which the rows were selected.

Below is an example of a TreeList with several selected rows:

Selection in the DevExtreme TreeList widget

The getSelectedRowsData(mode) method called for this TreeList returns different results depending on the mode argument:

"all"
Returns all the selected rows' data objects.

getSelectedRowsData("all") // returns data objects with the following keys: 2, 5, 8, 9, 6, 10, and 4

"excludeRecursive"
Excludes recursively selected rows' data objects.

getSelectedRowsData("excludeRecursive") // returns data objects with the following keys: 2, 6, 10, and 4

"leavesOnly"
Returns only leaves' data objects.

getSelectedRowsData("leavesOnly") // returns data objects with the following keys: 8, 9, 6, 10, and 4

jQuery

index.js

var treeList = $("#treeListContainer").dxTreeList("instance");

var selectedRowsData = treeList.getSelectedRowsData("leavesOnly");

Angular

app.component.ts

app.component.html

app.module.ts

import { Component, ViewChild } from '@angular/core';
import { DxTreeListComponent } from 'devextreme-angular';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    @ViewChild('treeListRef', { static: false }) treeList: DxTreeListComponent;
    // Prior to Angular 8
    // @ViewChild('treeListRef') treeList: DxTreeListComponent;

    selectedRowsData = [];

    getSelectedData() {
        this.selectedRowsData = this.treeList.instance.getSelectedRowsData('leavesOnly');
    }
}

<dx-tree-list ...
    #treeListRef
></dx-tree-list>

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxTreeListModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxTreeListModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }

Vue

App.vue

<template>
    <DxTreeList ...
        :ref="treeListRef">
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import DxTreeList from 'devextreme-vue/tree-list';

const treeListRef = 'treeList';

export default {
    components: {
        DxTreeList
    },
    data() {
        return {
            treeListRef,
            selectedRowsData: []
        }
    },
    computed: {
        treeList: function() {
            return this.$refs[treeListRef].instance;
        }
    },
    methods: {
        getSelectedData() {
            this.selectedRowsData = this.treeList.getSelectedRowsData('leavesOnly');
        }
    }
}
</script>

React

App.js

import React from 'react';

import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import TreeList from 'devextreme-react/tree-list';

class App extends React.Component {
    constructor(props) {
        super(props);

        this.treeListRef = React.createRef();

        this.selectedRowsData = [];

        this.getSelectedData = () => {
            this.selectedRowsData = this.treeList.getSelectedRowsData('leavesOnly');
        }
    }

    get treeList() {
        return this.treeListRef.current.instance;
    }

    render() {
        return (
            <TreeList ...
                ref={this.treeListRef}>
            </TreeList>
        );
    }
}
export default App;

ASP.NET MVC Controls

Razor C#

@(Html.DevExtreme().TreeList()
    .ID("treeList")
    @* ... *@
)

<script type="text/javascript">
    function getSelectedData() {
        var treeList = $("#treeList").dxTreeList("instance");
        var selectedRowsData = treeList.getSelectedRowsData();
        // ...
    }
</script>

NOTE

Calculated values cannot be obtained because this method gets data objects from the data source.

getVisibleColumns()

Gets all visible columns.

Return Value:

Array<TreeList Column>

Visible columns; may include command columns.

getVisibleColumns(headerLevel)

Gets all visible columns at a specific hierarchical level of column headers. Use it to access banded columns.

Parameters:

headerLevel:

The column headers' level.

Return Value:

Array<TreeList Column>

Visible columns; may include command columns.

getVisibleRows()

Gets currently rendered rows.

Return Value:

Array<TreeList Row>

Currently rendered rows.

hasEditData()

Checks whether the widget has unsaved changes.

Return Value:

true if the widget has unsaved changes; otherwise - false.

hideColumnChooser()

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after data is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

loadDescendants(keys)

Loads a specific node's descendants. Takes effect only if data has the plain structure and remoteOperations | filtering is true.

Parameters:

keys:

Array<any>

Node keys.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after data is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

loadDescendants(keys, childrenOnly)

Loads all or only direct descendants of specific nodes. Takes effect only if data has the plain structure and remoteOperations | filtering is true.

Parameters:

keys:

Array<any>

Node keys.

childrenOnly:

Pass true to load only children, false to load all the specified node's descendants.
false by default.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after data is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

navigateToRow(key)

Navigates the grid to the data page that contains the row with the specified key and scrolls the grid to display the row if it is not in the viewport.

Parameters:

key: any

The row's key.

The following requirements apply when you use this method:

The widget's keyExpr or the store's key option should be specified.
Rows should be initially sorted by keys. They can be sorted on the client using a column's sortOrder or the DataSource's sort option, or come already sorted from the server.

off(eventName)

Detaches all event handlers from a single event.

Parameters:

eventName:

The event's name.

Return Value:

The object for which this method is called.

off(eventName, eventHandler)

Detaches a particular event handler from a single event.

Parameters:

eventName:

The event's name.

eventHandler:

The event's handler.

Return Value:

The object for which this method is called.

on(eventName, eventHandler)

Subscribes to an event.

Parameters:

eventName:

The event's name.

eventHandler:

The event's handler.

Return Value:

The object for which this method is called.

Use this method to subscribe to one of the events listed in the Events section.

on(events)

Subscribes to events.

Parameters:

events:

Events with their handlers: { "eventName1": handler1, "eventName2": handler2, ...}

Return Value:

The object for which this method is called.

Use this method to subscribe to several events with one method call. Available events are listed in the Events section.

option()

Gets all widget options.

Return Value:

The widget's options.

option(optionName)

Gets the value of a single option.

Parameters:

optionName:

The option's name or full path.

Return Value: any

This option's value.

option(optionName, optionValue)

Updates the value of a single option.

Parameters:

optionName:

The option's name or full path.

optionValue: any

This option's new value.

option(options)

Updates the values of several options.

Parameters:

options:

Options with their new values.

pageCount()

Gets the total page count.

Return Value:

The total page count.

pageIndex()

Gets the current page index.

Return Value:

The current page index.

When the scrolling mode is "virtual", this method returns the index of the page whose row is shown first in the widget.

pageIndex(newIndex)

Switches the widget to a specific page using a zero-based index.

Parameters:

newIndex:

The zero-based page index.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after the page is shown. It is a native Promise or a jQuery.Promise when you use jQuery.

pageSize()

Gets the current page size.

Return Value:

The current page size.

pageSize(value)

Sets the page size.

Parameters:

value:

The page size.

refresh()

Reloads data and repaints the widget.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after data is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

The widget cannot track changes a third party makes in the data source. To update data in the widget in this case, call the refresh() method. Data sources of lookup columns are updated with the main data source.

The following code shows how to call this method:

jQuery

index.js

var treeList = $("#treeListContainer").dxTreeList("instance");
treeList.refresh()
    .done(function() {
        // ...
    })
    .fail(function(error) {
        // ...
    });

Angular

app.component.html

<dx-tree-list #treeListVar ... >
    <!-- ... -->
</dx-tree-list>

app.component.ts

import { Component, ViewChild } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    @ViewChild('treeListVar', { static: false }) treeList: DxTreeListComponent;
    // Prior to Angular 8
    // @ViewChild('treeListVar') treeList: DxTreeListComponent;

    refreshTreeList() {
        this.treeList.instance.refresh()
            .then(function() {
                // ...
            })
            .catch(function(error) {
                // ...
            });
    }
}

Vue

App.vue

<template>
    <DxTreeList ...
        :ref="treeListRefKey">
        <!-- ... -->
    </DxTreeList>
</template>
<script>
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { DxTreeList, /* ... */ } from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        // ...
    },
    data() {
        return {
            treeListRefKey: 'treeList'
        };
    },
    computed: {
        treeList: function() {
            return this.$refs[treeListRefKey].instance;
        }
    },
    methods: {
        refreshTreeList() {
            this.treeList.refresh()
                .then(function() {
                    // ...
                })
                .catch(function(error) {
                    // ...
                });
        }
    }
};
</script>

React

App.js

import React from 'react';

import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { TreeList, /* ... */ } from 'devextreme-react/tree-list';

class App extends React.Component {
    render() {
        return (
            <TreeList ...
                ref={ref => this.treeList = ref}>
                {/* ... */}
            </TreeList>
        );
    }
    refreshTreeList() {
        this.treeList.instance.refresh()
            .then(function() {
                // ...
            })
            .catch(function(error) {
                // ...
            });
    }
}
export default App;

ASP.NET MVC Controls

Razor C#

@(Html.DevExtreme().TreeList()
    .ID("treeListContainer")
    // ...
)
<script type="text/javascript">
    function refreshTreeList() {
        var treeList = $("#treeListContainer").dxTreeList("instance");
        treeList.refresh()
            .done(function() {
                // ...
            })
            .fail(function(error) {
                // ...
            });
    }
</script>

NOTE

Calling the refresh() method ends the editing process. In batch editing mode, changes are saved in a buffer before they are saved to the data source. In other modes, all unsaved changes are discarded.

refresh(changesOnly)

Reloads data and repaints the widget or elements whose data changed.

Parameters:

changesOnly:

Pass true to repaint elements whose data changed; false to repaint the entire widget.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after data is loaded. It is a native Promise or a jQuery.Promise when you use jQuery.

Main article: refresh()

repaint()

Repaints the widget without reloading data. Call it to update the widget's markup.

repaintRows(rowIndexes)

Repaints specific rows.

Parameters:

rowIndexes:

Array<Number>

Row indexes. Refer to Column and Row Indexes for more information.

This method updates the row objects and their visual representation.

saveEditData()

Saves changes that a user made to data.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after changes are saved in the data source. It is a native Promise or a jQuery.Promise when you use jQuery.

searchByText(text)

Seeks a search string in the columns whose allowSearch option is true.

Parameters:

text:

A search string. Pass an empty string to clear search results.

selectAll()

Selects all rows.

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after all rows are selected. It is a native Promise or a jQuery.Promise when you use jQuery.

If a filter is applied, this method selects only those rows that meet the filtering conditions.

selectRows(keys, preserve)

Selects rows with specific keys.

Parameters:

keys:

Array<any>

The row keys.

preserve:

Specifies whether previously selected rows should stay selected.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after the rows are selected. It is a native Promise or a jQuery.Promise when you use jQuery.

By default, this method call clears selection of previously selected rows. To keep these rows selected, call this method with true as the second argument.

JavaScript

widgetInstance.selectRows([5, 10, 12], true);

selectRowsByIndexes(indexes)

Selects rows with specific indexes.

Parameters:

indexes:

Array<Number>

The row indexes.

Return Value:

Promise<any> (jQuery or native)

A Promise that is resolved after the rows are selected. It is a native Promise or a jQuery.Promise when you use jQuery.

This method has the following specifics:

A call of this method clears selection of all previously selected rows.
When calculating row indexes, the widget ignores the hierarchy of rows.

showColumnChooser()

Shows the column chooser.

state()

Gets the current widget state.

Return Value:

The current widget state.

The following example shows how to save the widget state in the local storage and load it from there:

jQuery

JavaScript

$(function () {
    var treeList = $("#treeListContainer").dxTreeList({ 
        // ...
    }).dxTreeList;
    $("#save").dxButton({
        text: "Save State",
        onClick: function() {
            var state = treeList.state();
            // Saves the state in the local storage
            localStorage.setItem("treeListState", JSON.stringify(state));
        }
    });
    $("#load").dxButton({
        text: "Load State",
        onClick: function() {
            let state = JSON.parse(localStorage.getItem("treeListState"));
            treeList.state(state);
        }
    });
});

Angular

TypeScript

HTML

import { Component, ViewChild } from "@angular/core";
import { 
    DxTreeListModule, 
    DxButtonModule, 
    DxTreeListComponent 
} from "devextreme-angular";
// ...
export class AppComponent {
    @ViewChild(DxTreeListComponent, { static: false }) treeList: DxTreeListComponent
    // Prior to Angular 8
    // @ViewChild(DxTreeListComponent) treeList: DxTreeListComponent
    saveState() {
        let state = this.treeList.instance.state();
        // Saves the state in the local storage
        localStorage.setItem("treeListState", JSON.stringify(state));
    }
    loadState() {
        let state = JSON.parse(localStorage.getItem("treeListState"));
        this.treeList.instance.state(state);
    }
}
@NgModule({
    imports: [
        DxTreeListModule,
        DxButtonModule,
        // ...
    ],
    // ...
})

<dx-tree-list ...>
</dx-tree-list>
<dx-button
    text="Save State"
    (onClick)="saveState()">
</dx-button>
<dx-button
    text="Load State"
    (onClick)="loadState()">
</dx-button>

state(state)

Sets the widget state.

Parameters:

state:

The widget state to be set.

After the state is set, the TreeList reloads data to apply sorting, filtering, and other data processing settings.

Refer to the state() method description for an example of how to work with the widget state.

undeleteRow(rowIndex)

Recovers a row deleted in batch editing mode.

Parameters:

rowIndex: