JavaScript/jQuery TreeList Options

See Also

• Configure a Widget: Angular | Vue | React | jQuery | AngularJS | Knockout | ASP.NET MVC 5 | ASP.NET Core

The value of this option will be passed to the accesskey attribute of the HTML element that underlies the widget.

This option is used when the widget is displayed on a platform whose guidelines include the active state change for widgets.

Initially, columns appear in the order specified by the columns array. If you skip specifying this array, columns will mirror the order of fields in the first object from the dataSource. You can allow a user to reorder columns at runtime by setting the allowColumnReordering option to true.

See Also

• columns[].allowReordering

By default, the width of each column depends on the width of the widget and the total number of columns. You can allow a user to resize the columns at runtime by setting the allowColumnResizing option to true.

See Also

• columnResizingMode
• columns[].allowResizing
• columns[].width

When this option is set to true, data loaded once is saved in cache. Then, the widget takes data from this cache when performing such operations as sorting, grouping, paging, etc. Caching is helpful when the data source takes significant time to load, but consider disabling it for frequently changing data sources.

To update data in cache, call the refresh() method of the widget or the load() method of the DataSource.

See Also

• Data Caching
• getDataSource()

The cell's content may be truncated if the width of the cell's column becomes very small. In this case, when a user hovers the mouse pointer over such a cell, a hint containing the cell's value appears. To disable cell hints, assign false to the cellHintEnabled option.

When this option is set to true, all columns adjust their width to the content.

If the widget's overall content is narrower than the widget's width, the columns are stretched to fit the widget. To avoid this, set the columns.width option to "auto".

If the content is wider, the columnAutoWidth option set to true causes horizontal scrolling. You can set the allowHiding option to false for columns you want to be displayed continuously.

When the columnAutoWidth option is set to false, all columns have identical width, which in turn depends on the width of the widget.

See Also

• width
• columnFixing
• wordWrapEnabled

The column chooser allows a user to hide columns at runtime. To enable it, assign true to the columnChooser.enabled option.

See Also

• Column Chooser
• columns[].allowHiding

When the width of all columns exceeds the widget width, horizontal scrolling appears. If specific columns should be on screen constantly regardless of how far the widget is scrolled, allow a user to fix them at runtime using the context menu. For this, set the columnFixing.enabled option to true.

When you enable column fixing, command columns become fixed automatically.

DataGrid Demo TreeList Demo

See Also

• Column Fixing

This option set to true makes the widget hide certain columns automatically if all the columns do not fit the widget's width. Columns with low hidingPriority are hidden first. These are the rightmost (leftmost if rtlEnabled is true) columns by default. Information from hidden columns is available in an adaptive detail row.

See Also

• onAdaptiveDetailRowPreparing
• Adaptability

See Also

• columns[].minWidth
• allowColumnResizing
• columnResizingMode

The columnResizingMode option accepts one of the following values:

• nextColumn
  When a user resizes a column, the width of the next column changes.
• widget
  When a user resizes a column, the width of the widget changes.
  This mode is ignored if you specify the width of any column in percent.

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.

$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            dataField: "Title",
            caption: "Position"
        }, {
            dataField: "FullName",
            width: 300
        }, 
            "CompanyName",
            "City"
        ]
    });
});

<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

• Columns Overview
• columnOption(id, options)
• customizeColumns

See Also

• columnMinWidth

Use this function to make minor adjustments to automatically generated columns. You can access and modify column configurations using the function's parameter.

$(function(){
    $("#treeList").dxTreeList({
        // ...
        customizeColumns: function (columns) {
            columns[0].width = 100;
            columns[1].width = 210;
        }
    })
});

import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    customizeColumns (columns) {
        columns[0].width = 100;
        columns[1].width = 210;
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

<dx-tree-list ...
    [customizeColumns]="customizeColumns">
</dx-tree-list>

For a more profound column customization, declare the columns array.

If you use DevExtreme ASP.NET MVC Controls, refer to the Bind Controls to Data article.

The TreeList works with object collections that can have a plain or hierarchical structure. Depending on the structure, the objects should provide different data fields. Specify the dataStructure option to notify the TreeList of the used structure and refer to the option's description for information on the required fields.

Depending on your data source, bind the TreeList to data as follows.

• Data Array
  Assign the array to the dataSource option. View Demo

• Read-Only Data in JSON Format
  Set the dataSource option to the URL of a JSON file or service that returns JSON data.

• OData
  Implement an ODataStore.

• Web API, PHP, MongoDB
  Use one of the following extensions to enable the server to process data according to the protocol DevExtreme widgets use:

  • DevExtreme.AspNet.Data
  • DevExtreme-PHP-Data
  • devextreme-query-mongodb

  Then, use the createStore method to configure access to the server on the client as shown below. This method is part of DevExtreme.AspNet.Data.

  jQuery

  JavaScript

  $(function() {
      let serviceUrl = "https://url/to/my/service";
      $("#treeListContainer").dxTreeList({
          // ...
          dataSource: DevExpress.data.AspNet.createStore({
              key: "ID",
              loadUrl: serviceUrl + "/GetAction",
              insertUrl: serviceUrl + "/InsertAction",
              updateUrl: serviceUrl + "/UpdateAction",
              deleteUrl: serviceUrl + "/DeleteAction"
          })
      })
  });

  Angular

  app.component.ts

  app.component.html

  app.module.ts

  import { Component } from '@angular/core';
  import CustomStore from 'devextreme/data/custom_store';
  import { createStore } from 'devextreme-aspnet-data-nojquery';
  
  @Component({
      selector: 'app-root',
      templateUrl: './app.component.html',
      styleUrls: ['./app.component.css']
  })
  export class AppComponent {
      store: CustomStore;
      constructor() {
          let serviceUrl = "https://url/to/my/service";
          this.store = createStore({
              key: "ID",
              loadUrl: serviceUrl + "/GetAction",
              insertUrl: serviceUrl + "/InsertAction",
              updateUrl: serviceUrl + "/UpdateAction",
              deleteUrl: serviceUrl + "/DeleteAction"
          })
      }
  }

  <dx-tree-list ...
      [dataSource]="store">
  </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 ...
          :data-source="store" />
  </template>
  
  <script>
  import 'devextreme/dist/css/dx.common.css';
  import 'devextreme/dist/css/dx.light.css';
  
  import CustomStore from 'devextreme/data/custom_store';
  import { createStore } from 'devextreme-aspnet-data-nojquery';
  import { DxTreeList } from 'devextreme-vue/tree-list';
  
  export default {
      components: {
          DxTreeList
      },
      data() {
          const serviceUrl = "https://url/to/my/service";
          const store = createStore({
              key: "ID",
              loadUrl: serviceUrl + "/GetAction",
              insertUrl: serviceUrl + "/InsertAction",
              updateUrl: serviceUrl + "/UpdateAction",
              deleteUrl: serviceUrl + "/DeleteAction"
          });
          return {
              store
          }
      }
  }
  </script>

  React

  App.js

  import React from 'react';
  import 'devextreme/dist/css/dx.common.css';
  import 'devextreme/dist/css/dx.light.css';
  
  import CustomStore from 'devextreme/data/custom_store';
  import { createStore } from 'devextreme-aspnet-data-nojquery';
  import TreeList from 'devextreme-react/tree-list';
  
  const serviceUrl = "https://url/to/my/service";
  const store = createStore({
      key: "ID",
      loadUrl: serviceUrl + "/GetAction",
      insertUrl: serviceUrl + "/InsertAction",
      updateUrl: serviceUrl + "/UpdateAction",
      deleteUrl: serviceUrl + "/DeleteAction"
  });
  
  class App extends React.Component {
      render() {
          return (
              <TreeList ...
                  dataSource={store} />
          );
      }
  }
  export default App;

  View Demo

• Any other data source
  Implement a CustomStore.

Regardless of the data source on the input, the TreeList always wraps it in the DataSource object. This object allows you to sort, filter, group, and otherwise shape data. To get its instance, call the getDataSource() method.

The widget expects that data has a plain structure where:

• each data item contains a parentId and a unique id;
• data items of the highest hierarchical level have parentId equal to 0, null or undefined. It indicates that these data items descend from the root node. The root node does not have a visual representation.

var treeListData = [
    { id: 1, parentId: 0 },
    { id: 11, parentId: 1 },
    { id: 12, parentId: 1 },
    { id: 13, parentId: 1 },
    { id: 131, parentId: 13 },
    { id: 132, parentId: 13 },
    { id: 133, parentId: 13 },
    { id: 2, parentId: 0 }
];

Specify the keyExpr and parentIdExpr if parentId and id are called differently in your dataset. You can also change the root node's ID from 0 via the rootValue option.

View Demo

If data has a hierarchical structure, set the dataStructure option to "tree". Parent and item IDs will be generated automatically. Data items that nest other data items should have an items field:

var treeListData = [{
    text: "item1",
    items: [{ 
        text: "item11" 
    }, { 
        text: "item12",
        items: [
            { text: "item121" }, 
            { text: "item122" }
        ]
    }]
}, { 
    text: "item2" 
}];

If the items field is called differently in your dataset, specify the itemsExpr option.

View Demo

If each data item has a Boolean field that specifies whether this data item nests other items, assign the field's name to the hasItemsExpr option. The widget uses this information to render the expand button. This is required only if the widget is bound to a remote data source.

See Also

• Use Plain Data
• Use Hierarchical Data

Without a data source, the widget cannot detect the date-time values' format. In this case, specify the dateSerializationFormat option that supports the following formats:

• "yyyy-MM-dd" - a local date

• "yyyy-MM-ddTHH:mm:ss" - local date and time

• "yyyy-MM-ddTHH:mm:ssZ" - the UTC date and time

• "yyyy-MM-ddTHH:mm:ssx" - date and time with a timezone

This option applies only if the forceIsoDateParsing field is set to true in the global configuration object.

See Also

• format

The widget allows a user to edit data in several modes, which are detailed in the mode option. To define what editing operations a user can perform, specify the allowAdding, allowUpdating and allowDeleting options. Before enabling an operation, make sure that your data source supports it.

See Also

• Editing

The error row displays data-related errors that may occur on the server during the widget's runtime. Setting this option to false hides the error row, but the errors can still be viewed in the browser's console.

See Also

• onDataErrorOccured

Setting this option expands only the specified rows, but not their parents. If a to-be-expanded row lies deep in the hierarchy, make sure to include keys of all rows that nest it.

See Also

• Expand and Collapse Rows

See the FilterBuilder configuration for options that you can specify in this object.

See Also

• Filter Panel with Filter Builder

See the Popup configuration for options that you can specify in this object.

See Also

• Filter Panel with Filter Builder

View Demo

Use the TreeListFilterMode enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: FullBranch and WithAncestors.

The filter panel displays the applied filter expression.

Clicking on the filter expression opens the filter builder.

If you change the filter expression in the filter panel or filter builder, the changes are reflected in the filter row and header filter, and vice versa. You can disable this synchronization by setting the filterSyncEnabled option to false. In this case, the filter panel remains synchronized with the filter builder.

See Also

• Filter Panel with Filter Builder
• filterBuilderPopup

The filter row allows a user to filter data by values of individual columns.

Each cell in the filter row contains a magnifying glass icon, pausing on which opens a drop-down list with filters available for the column.

To make the filter row visible, assign true to the filterRow.visible option.

View Demo

See Also

• Filter Row
• expandNodesOnFiltering
• filter(filterExpr)
• clearFilter(filterName)

Synchronization is enabled if the filter panel is visible. When it is enabled, check that each column that allows filtering has the dataField or name option specified.

If filterSyncEnabled is true, the filter expression includes a combination of the filter row, header filter, and filter builder filters. Otherwise, it contains only the filter builder filter.

The filter expression can contain the following operations: "=", "<>", "<", ">", "<=", ">=", "between", "contains", "notcontains", "startswith", "endswith", "anyof", "noneof", and the filter builder's custom operations. Use "anyof" and "noneof" to select and clear the selection of items in the header filter's popup menu. In the following code, "anyof" is used to select items with IDs 500 and 700:

$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        filterSyncEnabled: true,
        headerFilter: { visible: true },
        filterValue: ["ID", "anyof", [500, 700]], 
    })
});

<dx-tree-list ...
    [filterSyncEnabled]="true"
    [filterValue]="['ID', 'anyof', [500, 700]]"> 
    <dxo-header-filter 
        [visible]="true">
    </dxo-header-filter>
</dx-tree-list>

import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

<template>
    <DxTreeList ...
        :filter-sync-enabled="true"
        :filter-value="filterValue"> 
        <DxHeaderFilter :visible="true" />
    </DxTreeList>
</template>

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

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

export default {
    components: {
        DxTreeList,
        DxHeaderFilter,
        // ...
    },
    data() {
        return {
            filterValue: ['ID', 'anyof', [500, 700]]
        }
    }
}
</script>

import React from 'react';

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

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

const filterValue = ['ID', 'anyof', [500, 700]];

class App extends React.Component {
    render() {
        return (
            <TreeList ...
                filterSyncEnabled={true}
                defaultFilterValue={filterValue}>
                <HeaderFilter visible={true} />
            </TreeList>
        );
    }
}
export default App;

@(Html.DevExtreme().DataGrid()
    // ...
    .FilterSyncEnabled(true)
    .HeaderFilter(hf => hf.Visible(true))
    .FilterValue("['ID', 'anyof', [500, 700]]")
)

If a column's groupInterval option is set, the "anyof" and "noneof" operations for this column accept the beginning of intervals instead of exact values:

$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        headerFilter: { visible: true },
        filterValue: ["ID", "anyof", [500, 700]], // Filter intervals are 500-600 and 700-800
        columns: [{
            dataField: "ID",
            dataType: "number",
            headerFilter: { groupInterval: 100 }
        },
        // ...
        ]
    })
});

<dx-tree-list ...
    <!-- Filter intervals are 500-600 and 700-800 -->
    [(filterValue)]="['ID', 'anyof', [500, 700]]">
        <dxo-header-filter 
            [visible]="true">
        </dxo-header-filter>
        <dxi-column
            dataField="ID"
            dataType="number">
                <dxo-header-filter 
                    [groupInterval]="100">
                </dxo-header-filter>
        </dxi-column>
</dx-tree-list>

import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

<template>
    <DxTreeList ...
        <!-- Filter intervals are 500-600 and 700-800 -->
        :filter-value="filterValue">
        <DxHeaderFilter :visible="true" />
        <DxColumn
            data-field="ID"
            data-type="number">
            <DxColumnHeaderFilter :group-interval="100" />
        </DxColumn>
    </DxTreeList>
</template>

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

import DxTreeList, {
    DxColumn,
    DxHeaderFilter,
    DxColumnHeaderFilter,
    // ...
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn,
        DxHeaderFilter,
        DxColumnHeaderFilter,
        // ...
    },
    data() {
        return {
            filterValue: ['ID', 'anyof', [500, 700]]
        }
    }
}
</script>

import React from 'react';

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

import TreeList, {
    Column,
    HeaderFilter,
    ColumnHeaderFilter,
    // ...
} from 'devextreme-react/tree-list';

const filterValue = ['ID', 'anyof', [500, 700]];

class App extends React.Component {
    render() {
        return (
            <TreeList ...
                {/* Filter intervals are 500-600 and 700-800 */}
                defaultFilterValue={filterValue}>
                <HeaderFilter visible={true} />
                <Column
                    dataField={'ID'}
                    dataType={'number'}>
                    <ColumnHeaderFilter groupInterval={100} />
                </Column>
            </TreeList>
        );
    }
}
export default App;

@(Html.DevExtreme().DataGrid()
    // ...
    // Filter intervals are 500-600 and 700-800
    .HeaderFilter(headerFilter => headerFilter.Visible(true))
    .FilterValue("['ID', 'anyof', [500, 700]]")
    .Columns(columns => {
        columns.AddFor(m => m.ID)
            .DataType(GridColumnDataType.Number)
            .HeaderFilter(hf => hf.GroupInterval(100));
        // ...
    })
)

See Also

• Filter Panel with Filter Builder

This index depends on the column's location and can change dynamically (for example, when columns are reordered). The following image illustrates the indexing system. Note that command columns have indexes but cannot be focused.

The default index, -1, means that no column is focused.

See Also

• onFocusedCellChanging | onFocusedCellChanged
• focusedRowIndex | focusedRowKey

When this option is set to true, the following applies:

• Rows are initially sorted by keys if any field of remoteOperations is true.
• The row with focusedRowIndex or focusedRowKey is highlighted.
• When the data row area is focused, this row is focused and the area is scrolled down to it.
• The onFocusedRowChanging and onFocusedRowChanged functions become active.

View Demo

See Also

• navigateToRow(key)
• focusedColumnIndex
• key in ArrayStore | CustomStore | LocalStore | ODataStore

The focused row has a key and index on a page. When the pager is used for navigation, the focused row's index persists from page to page but corresponds to a different row with a different key on each page.

The default index, -1, means that no row is focused.

The focusedRowKey takes precedence over the focusedRowIndex when both are specified.

See Also

• onFocusedRowChanging | onFocusedRowChanged
• focusedColumnIndex

The focused row has a key and index on a page. When the pager is used for navigation, the focused row's index persists from page to page but corresponds to a different row with a different key on each page.

In the DataGrid, group rows can also be focused. See the Group Index and Key topic for more information on how group keys are formed.

View Demo

See Also

• focusedRowIndex
• onFocusedRowChanging | onFocusedRowChanged
• focusedColumnIndex

If you load data from the server, you need to set this option so that the widget does not render the expand button for nodes without children.

A header filter allows a user to filter values in an individual column by including or excluding them from the applied filter. A click on a header filter icon invokes a popup menu with all unique values in the column. By selecting or clearing the selection of values in this menu, the user includes or excludes them from the filter.

To make header filter icons visible, assign true to the headerFilter.visible option. Data in the popup menu can be customized using the headerFilter option of a specific column.

View Demo

See Also

• Header Filter
• columns[].allowHeaderFiltering
• filter(filterExpr)
• clearFilter(filterName)

This option accepts a value of one of the following types:

• Number
  The height in pixels.

• String
  A CSS-accepted measurement of height. For example, "55px", "80%", "inherit".

• Function
  A function returning either of the above. For example:

  JavaScript

  height: function() {
      return window.innerHeight / 1.5;
  }

You can change the following CSS rules and classes that control highlighting:

@keyframes dx-treelist-highlight-change {
    from {
        background-color: #efefef;
    }
    50% {
        background-color: #efefef;
    }
}
.dx-treelist-cell-updated-animation {
    animation: dx-treelist-highlight-change 1s;
}
.dx-treelist-row-inserted-animation {
    animation: dx-treelist-highlight-change 1s;
}

See Also

• Use Hierarchical Data

See Also

• Use Plain Data

The load panel is displayed while the widget loads data. It consists of a loading indicator and text, both placed on a pane.

Since the load panel is, in fact, the DevExtreme LoadPanel widget, the loadPanel object can contain any options of this widget along with options described here.

See Also

• Load Panel
• beginCustomLoading(messageText)
• endCustomLoading()

Adaptive detail rows display information from columns that were hidden when the widget adapted to the screen or container size. Each adaptive detail row contains the Form widget that you can customize within the onAdaptiveDetailRowPreparing function using the formOptions object. Refer to the Form Configuration section for details on options of the Form widget.

See Also

• columnHidingEnabled
• columns[].hidingPriority
• Adaptability

To identify whether the pointer has entered or left the cell, check the eventType field's value.

In the following code, the onCellPrepared function is used to change a ProductName's color depending on the Amount of sold products:

$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        repaintChangesOnly: true,
        onCellPrepared: function(e) {
            if(e.rowType === "data" && e.column.dataField === "ProductName") {
                e.cellElement.css("color", e.data.Amount >= 10000 ? "green" : "red");
                // Tracks the `Amount` data field
                e.watch(function() {
                    return e.data.Amount
                }, function() {
                    e.cellElement.css("color", e.data.Amount >= 10000 ? "green" : "red");
                })
            }
        }
    })
})

import { dxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    onCellPrepared(e) {
        if(e.rowType === "data" && e.column.dataField === "ProductName") {
            e.cellElement.style.color = e.data.Amount >= 10000 ? "green" : "red";
            // Tracks the `Amount` data field
            e.watch(function() {
                return e.data.Amount
            }, function() {
                e.cellElement.style.color = e.data.Amount >= 10000 ? "green" : "red";
            })
        }
    }
}
@NgModule({
    imports: [
        // ...
        dxTreeListModule
    ],
    // ...
})

<dx-tree-list
    [repaintChangesOnly]="true"
    (onCellPrepared)="onCellPrepared($event)">
</dx-tree-list>

@(Html.DevExtreme().TreeList()
    .ID("treeListContainer")
    // ...
    .RepaintChangesOnly(true)
    .OnCellPrepared("treeList_cellPrepared_handler")
)
<script>
    function treeList_cellPrepared_handler(e) {
        if (e.rowType === "data" && e.column.dataField === "ProductName") {
            e.cellElement.css("color", e.data.Amount >= 10000 ? "green" : "red");
            // Tracks the `Amount` data field
            e.watch(function() {
                return e.data.Amount
            }, function() {
                e.cellElement.css("color", e.data.Amount >= 10000 ? "green" : "red");
            })
        }
    }
</script>

See Also

• Customize Cells

In the following code, the onContextMenuPreparing function adds a custom item to the context menu invoked when a user right-clicks any column header:

$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        onContextMenuPreparing: function(e) { 
            if (e.target == "header") {
                // e.items can be undefined
                if (!e.items) e.items = [];

                // Add a custom menu item
                e.items.push({
                    text: "Log Column Caption",
                    onItemClick: function() {
                        console.log(e.column.caption);
                    }
                });
            } 
        }
    });
});

<dx-tree-list ...
    (onContextMenuPreparing)="addMenuItems($event)">
</dx-tree-list>

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

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    addMenuItems(e) { 
        if (e.target == 'header') {
            // e.items can be undefined
            if (!e.items) e.items = [];

            // Add a custom menu item
            e.items.push({
                text: 'Log Column Caption',
                onItemClick: () => {
                    console.log(e.column.caption);
                }
            });
        } 
    }
}

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 { }

<template>
    <DxTreeList ...
        @context-menu-preparing="addMenuItems">
    </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 {
            // ...
        }
    },
    methods: {
        addMenuItems(e) {
            if (e.target == 'header') {
                // e.items can be undefined
                if (!e.items) e.items = [];

                // Add a custom menu item
                e.items.push({
                    text: 'Log Column Caption',
                    onItemClick: () => {
                        console.log(e.column.caption);
                    }
                });
            } 
        }
    }
}
</script>

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 {
    addMenuItems(e) {
        if (e.target == 'header') {
            // e.items can be undefined
            if (!e.items) e.items = [];

            // Add a custom menu item
            e.items.push({
                text: 'Log Column Caption',
                onItemClick: () => {
                    console.log(e.column.caption);
                }
            });
        }
    }

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

Handles errors that might occur in the data source. To obtain a human-readable description of the error in the function, use the error.message field.

If the editing.mode is "batch" or "cell", this function is executed while the widget renders columns of boolean dataType and other columns whose showEditorAlways option is true.

Use this function to:

• Override the default editor's onValueChanged handler. For other default editor customizations, use editorOptions.

  jQuery

  index.js

  $(function() {
      $("#treeListContainer").dxTreeList({
          // ...
          onEditorPreparing: function(e) {
              if (e.dataField === "requiredDataField" && e.parentType === "dataRow") {
                  var standardHandler = e.editorOptions.onValueChanged;
                  e.editorOptions.onValueChanged = function(e) { // Overrides the standard handler
                      // ...
                      // Custom commands go here
                      // ...
                      standardHandler(e); // Calls the standard handler to save the edited value
                  }
              }
          }
      });
  });

  Angular

  app.component.html

  app.component.ts

  app.module.ts

  <dx-tree-list ...
      (onEditorPreparing)="overrideOnValueChanged($event)">
  </dx-tree-list>

  import { Component } from '@angular/core';
  
  @Component({
      selector: 'app-root',
      templateUrl: './app.component.html',
      styleUrls: ['./app.component.css']
  })
  export class AppComponent {
      overrideOnValueChanged(e) {
          if (e.dataField === 'requiredDataField' && e.parentType === 'dataRow') {
              let standardHandler = e.editorOptions.onValueChanged;
              e.editorOptions.onValueChanged = function (e) { // Overrides the standard handler
                  // ...
                  // Custom commands go here
                  // ...
                  standardHandler(e); // Calls the standard handler to save the edited value
              }
          }
      }
  }

  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 ...
          @editor-preparing="overrideOnValueChanged">
      </DxTreeList>
  </template>
  
  <script>
  import 'devextreme/dist/css/dx.common.css';
  import 'devextreme/dist/css/dx.light.css';
  
  import DxTreeList from 'devextreme-vue/data-grid';
  
  export default {
      components: {
          DxTreeList
      },
      // ...
      methods: {
          overrideOnValueChanged(e) {
              if (e.dataField === 'requiredDataField' && e.parentType === 'dataRow') {
                  let standardHandler = e.editorOptions.onValueChanged;
                  e.editorOptions.onValueChanged = function (e) { // Overrides the standard handler
                      // ...
                      // Custom commands go here
                      // ...
                      standardHandler(e); // Calls the standard handler to save the edited value
                  }
              }
          }
      }
  }
  </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/data-grid';
  
  class App extends React.Component {
      overrideOnValueChanged(e) {
          if (e.dataField === 'requiredDataField' && e.parentType === 'dataRow') {
              let standardHandler = e.editorOptions.onValueChanged;
              e.editorOptions.onValueChanged = function (e) { // Overrides the standard handler
                  // ...
                  // Custom commands go here
                  // ...
                  standardHandler(e); // Calls the standard handler to save the edited value
              }
          }
      }
      render() {
          return (
              <TreeList ...
                  onEditorPreparing={this.overrideOnValueChanged}>
              </TreeList>
          );
      }
  }
  export default App;

  ASP.NET MVC Controls

  Razor C#

  @(Html.DevExtreme().TreeList()
      // ...
      .OnEditorPreparing("overrideOnValueChanged")
  )
  
  <script type="text/javascript">
      function overrideOnValueChanged(e) {
          if (e.dataField === "requiredDataField" && e.parentType === "dataRow") {
              var standardHandler = e.editorOptions.onValueChanged;
              e.editorOptions.onValueChanged = function(e) { // Overrides the standard handler
                  // ...
                  // Custom commands go here
                  // ...
                  standardHandler(e); // Calls the standard handler to save the edited value
              }
          }
      }
  </script>

• Replace the default editor. The old editor's configuration applies to the replacement editor. If you want to define the configuration from scratch, use an editCellTemplate.

  In the following code, the replacement editor is the DevExtreme TextArea widget:

  jQuery

  index.js

  $(function() {
      $("#treeListContainer").dxTreeList({
          // ...
          onEditorPreparing: function(e) {
              if (e.dataField === "description" && e.parentType === "dataRow") {
                  e.editorName = "dxTextArea";
              }
          }
      });
  });

  Angular

  app.component.html

  app.component.ts

  app.module.ts

  <dx-tree-list ...
      (onEditorPreparing)="replaceEditor($event)">
  </dx-tree-list>

  import { Component } from '@angular/core';
  import 'devextreme/ui/text_area';
  
  @Component({
      selector: 'app-root',
      templateUrl: './app.component.html',
      styleUrls: ['./app.component.css']
  })
  export class AppComponent {
      replaceEditor(e) { 
          if (e.dataField === 'description' && e.parentType === 'dataRow') {
              e.editorName = 'dxTextArea';
          }
      }
  }

  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 ...
          @editor-preparing="replaceEditor">
      </DxTreeList>
  </template>
  
  <script>
  import 'devextreme/dist/css/dx.common.css';
  import 'devextreme/dist/css/dx.light.css';
  
  import DxTreeList from 'devextreme-vue/data-grid';
  import 'devextreme/ui/text_area';
  
  export default {
      components: {
          DxTreeList
      },
      // ...
      methods: {
          replaceEditor(e) { 
              if (e.dataField === 'description' && e.parentType === 'dataRow') {
                  e.editorName = 'dxTextArea';
              }
          }
      }
  }
  </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/data-grid';
  import 'devextreme/ui/text_area';
  
  class App extends React.Component {
      replaceEditor(e) { 
          if (e.dataField === 'description' && e.parentType === 'dataRow') {
              e.editorName = 'dxTextArea';
          }
      }
      render() {
          return (
              <TreeList ...
                  onEditorPreparing={this.replaceEditor}>
              </TreeList>
          );
      }
  }
  export default App;

  ASP.NET MVC Controls

  Razor C#

  @(Html.DevExtreme().TreeList()
      // ...
      .OnEditorPreparing("replaceEditor")
  )
  
  <script type="text/javascript">
      function replaceEditor(e) {
          if (e.dataField === "description" && e.parentType === "dataRow") {
              e.editorName = "dxTextArea";
          }
      }
  </script>

• Customize editors used in the search panel, filter row, and selection column.
  Use the parentType function parameter to check if the editor being customized belongs to one of these UI elements.

• Dynamically change editor options in the editing state.

• Implement other customization cases.

View Demo

See Also

• columns[].showEditorAlways

See Also

• focusedRowIndex | focusedRowKey
• focusedColumnIndex

In the following code, the onFocusedCellChanging function is used to customize keyboard navigation within a row. The cell navigation is looped in a single row because focus moves to the row's first cell after reaching the last cell and vice versa:

$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        onFocusedCellChanging: function (e) {
            if (e.newColumnIndex == e.prevColumnIndex) {
                e.newColumnIndex = (e.newColumnIndex == 0 ? e.columns.length - 1 : 0)
            }
        }
    });
});

import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    onFocusedCellChanging (e) { 
        if (e.newColumnIndex == e.prevColumnIndex) {
            e.newColumnIndex = (e.newColumnIndex == 0 ? e.columns.length - 1 : 0)
        }
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

<dx-tree-list ...
    (onFocusedCellChanging)="onFocusedCellChanging($event)">
</dx-tree-list>

See Also

• focusedRowIndex | focusedRowKey
• focusedColumnIndex

See Also

• focusedRowIndex | focusedRowKey
• focusedColumnIndex

See Also

• focusedRowIndex | focusedRowKey
• focusedColumnIndex

See Also

• Get a Widget Instance in Angular | AngularJS | Knockout | Vue | React

Using this function, you can populate a newly added row with data by default. Add fields to the data object so that they correspond to fields of a data source object. Note that the data object may omit some fields present in the data source object. Add only those fields that must initialize specific cells of a new row.

In the following code, the onInitNewRow function is used to provide default values for the hireDate and position cells of a new row:

$(function() {
    $("#treeListContainer").dxTreeList({
        dataSource: [{
            ID: 1,
            hireDate: 1491821760000,
            position: "CTO"
        }, // ...
        ],
        columns: [ "ID", {
            dataField: "hireDate",
            dataType: "date"
        }, "position" ],
        onInitNewRow: function(e) {
            e.data.hireDate = new Date();
            e.data.position = "Programmer";
        }
    });
})

<dx-tree-list ...
    [dataSource]="employees"
    (onInitNewRow)="onInitNewRow($event)">
    <dxi-column dataField="ID"></dxi-column>
    <dxi-column dataField="hireDate" dataType="date"></dxi-column>
    <dxi-column dataField="position"></dxi-column>
</dx-tree-list>

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

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    employees = [{
        ID: 1,
        hireDate: 1491821760000,
        position: "CTO"
    }, // ...
    ];
    onInitNewRow(e) {
        e.data.hireDate = new Date();
        e.data.position = "Programmer";
    }
}

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 { }

<template>
    <DxTreeList ...
        :data-source="employees"
        @init-new-row="initNewRow($event)">
        <DxColumn data-field="ID" />
        <DxColumn data-field="hireDate" data-type="date" />
        <DxColumn data-field="position" />
    </DxTreeList>
</template>
<script>
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

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

const employees = [{
    ID: 1,
    hireDate: 1491821760000,
    position: "CTO"
}, // ...
];

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    data() {
        employees
    },
    methods: {
        initNewRow(e) {
            e.data.hireDate = new Date();
            e.data.position = "Programmer";
        }
    }
};
</script>

import React from 'react';

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

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

const employees = [{
    ID: 1,
    hireDate: 1491821760000,
    position: "CTO"
}, // ...
];

class App extends React.Component {
    constructor(props) {
        super(props);
        this.onInitNewRow = this.onInitNewRow.bind(this);
    }

    onInitNewRow(e) {
        e.data.hireDate = new Date();
        e.data.position = "Programmer";
    }

    render() {
        return (
            <TreeList ...
                dataSource={employees}
                onInitNewRow={this.onInitNewRow}>
                <Column dataField="ID" />
                <Column dataField="hireDate" dataType="date" />
                <Column dataField="position" />
            </TreeList>
        );
    }
}
export default App;

@(Html.DevExtreme().TreeList()
    .DataSource(new JS("employees"))
    .Columns(c => {
        c.Add().DataField("ID");
        c.Add().DataField("hireDate")
            .DataType(GridColumnDataType.Date);
        c.Add().DataField("position");
    })
    .OnInitNewRow("onInitNewRow")
)
<script type="text/javascript">
    var employees = [{
        ID: 1,
        hireDate: 1491821760000,
        position: "CTO"
    }, // ...
    ];
    function onInitNewRow(e) {
        e.data.hireDate = new Date();
        e.data.position = "Programmer";
    }
</script>

Use this function to modify the node fields. You can traverse the tree using the forEachNode(callback) method or implement your custom algorithm. Within this algorithm, start traversing from the root node, which is available via the function parameter's root field. Every node, including the root one, provides access to its child nodes in the children field, which allows traversing the whole tree.

Prior to this function, the widget executes the onCellClick function and sometimes internal functions. You can use the handled field to check whether internal functions were executed.

To cancel row collapsing, assign true to the cancel field of the function parameter.

To cancel row expansion, assign true to the cancel field of the function parameter.

The following code shows how to use the function parameter's cancel field to prevent or continue row insertion. In this code, a Promise is assigned to this field. Row insertion continues if row data validation on the server succeeds (the Promise is resolved); otherwise, row insertion is prevented (the Promise is rejected).

$(function(){
    $("#treeListContainer").dxTreeList({
        // ...
        onRowInserting: function(e) {
            var d = $.Deferred();
            $.getJSON("https://url/to/your/validation/service", JSON.stringify(e.data))
                .then(function(result) {
                    return !result.errorText ? d.resolve() : d.reject(result.errorText);
                })
                .fail(function() { 
                    return.reject(); 
                })
            e.cancel = d.promise();
        }
    })
})

import { DxTreeListModule } from "devextreme-angular";
import { HttpClient, HttpClientModule, HttpParams } from "@angular/common/http";
import "rxjs/add/operator/toPromise";
// ...
export class AppComponent {
    constructor(private httpClient: HttpClient) { /*...*/}
    onRowInserting(e) {
        let params = new HttpParams({ fromString: JSON.stringify(e.data) });
        let result = this.httpClient.get("https://url/to/your/validation/service", { params: params })
            .toPromise();
        e.cancel = new Promise((resolve, reject) => {
            result.then((validationResult) => {
                !validationResult.errorText ? resolve() : reject(validationResult.errorText)
            })
            .catch(() => reject());
        })    
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule,
        HttpClientModule
    ],
    // ...
})

<dx-tree-list ... 
    (onRowInserting)="onRowInserting($event)">
</dx-tree-list>