JavaScript/jQuery TreeView Options
accessKey
The value of this property will be passed to the accesskey
attribute of the HTML element that underlies the UI component.
createChildren
createChildren is called at the beginning of the UI component's lifetime and each time a user expands a node whose child nodes have not been loaded yet. It allows you to load the entire tree in portions: load root nodes first (when the function's parentNode parameter is null) and the child nodes of each expanded node later.
This function has the following restrictions:
Neither the dataSource, nor the items property should be specified.
The dataStructure property should be set to "plain".
Since the search will be performed on loaded nodes only and thus produce incorrect results, it is not recommended that you enable this functionality.
The following code shows how to use this function with a remote service:
jQuery
$(function() { $("#treeViewContainer").dxTreeView({ dataStructure: "plain", rootValue: 0, createChildren: function (parentNode) { var d = $.Deferred(); $.get("http://url/to/the/service", { // Here, 0 is the "rootValue" property's value. parentId: parentNode ? JSON.stringify(parentNode.key) : "0" }) .done(function (result) { d.resolve(result); }); return d.promise(); } }); });
Angular
<dx-tree-view [rootValue]="0" dataStructure="plain" [createChildren]="createChildren"> </dx-tree-view>
import { ..., Inject } from "@angular/core"; import { HttpClient, HttpClientModule, HttpParams } from "@angular/common/http"; import "rxjs/add/operator/toPromise"; import { DxTreeViewModule } from "devextreme-angular"; // ... export class AppComponent { constructor(@Inject(HttpClient) httpClient: HttpClient) { } createChildren = (parentNode) => { let params: HttpParams = new HttpParams() // Here, 0 is the "rootValue" property's value. .set("parentId", parentNode ? JSON.stringify(parentNode.key) : "0"); return httpClient.get("http://url/to/the/service", { params: params }) .toPromise(); } } @NgModule({ imports: [ // ... DxTreeViewModule, HttpClientModule ], // ... })
Vue
<template> <DxTreeView :create-children="createChildren" :root-value="''" data-structure="plain" /> </template> <script> import DxTreeView from 'devextreme-vue/tree-view'; import 'whatwg-fetch'; export default { components: { DxTreeView }, methods: { createChildren: function(parent) { let parentId = parent ? parent.itemData.id : ''; return fetch(`http://url/to/the/service?parentId=${parentId}`) .then(response => response.json()) .catch(() => { throw 'Data Loading Error'; }); } } }; </script>
React
import React from 'react'; import TreeView from 'devextreme-react/tree-view'; import 'whatwg-fetch'; const App = () => { return ( <TreeView dataStructure="plain" rootValue="''" createChildren={createChildren} /> ); } const createChildren = (parent) => { let parentId = parent ? parent.itemData.id : ''; return fetch(`http://url/to/the/service?parentId=${parentId}`) .then(response => response.json()) .catch(() => { throw 'Data Loading Error'; }); } export default App;
See Also
dataSource
The TreeView 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 property to notify the TreeView of the used structure and refer to the property's description for information on the required fields.
Depending on your data source, bind the TreeView to data as follows.
Data Array
Assign the array to the dataSource option.Read-Only Data in JSON Format
Set the dataSource property 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 UI components use: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"; $("#treeViewContainer").dxTreeView({ // ... dataSource: DevExpress.data.AspNet.createStore({ key: "ID", loadUrl: serviceUrl + "/GetAction", insertUrl: serviceUrl + "/InsertAction", updateUrl: serviceUrl + "/UpdateAction", deleteUrl: serviceUrl + "/DeleteAction" }) }) });
Angular
app.component.tsapp.component.htmlapp.module.tsimport { 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-view ... [dataSource]="store"> </dx-tree-view>
import { BrowserModule } from '@angular/platform-browser'; import { NgModule } from '@angular/core'; import { AppComponent } from './app.component'; import { DxTreeViewModule } from 'devextreme-angular'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, DxTreeViewModule ], providers: [], bootstrap: [AppComponent] }) export class AppModule { }
Vue
App.vue<template> <DxTreeView ... :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 { DxTreeView } from 'devextreme-vue/tree-view'; export default { components: { DxTreeView }, 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.jsimport 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 TreeView from 'devextreme-react/tree-view'; 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 ( <TreeView ... dataSource={store} /> ); } } export default App;
Any other data source
Implement a CustomStore.
Regardless of the data source on the input, the TreeView always wraps it in the DataSource object. This object allows you to sort, filter, group, and perform other data shaping operations. To get its instance, call the getDataSource() method.
Review the following notes about data binding:
Do not specify the items property if you specified the dataSource, and vice versa.
Data field names cannot be equal to
this
and should not contain the following characters:.
,:
,[
, and]
.The stores and DataSource have methods to process and update data. However, the methods do not allow you to perform particular tasks (for example, replace the entire dataset, reconfigure data access at runtime). For such tasks, create a new array, store, or DataSource and assign it to the dataSource property as shown in the articles about changing properties in jQuery, Angular, React, and Vue.
See Also
dataStructure
The UI component expects that data has a hierarchical structure where each data item contains a text
, a unique id
, and an items
array if the data item nests other data items:
var hierarchicalData = [{ id: '1', text: 'Fruits', items: [ { id: '1_1', text: 'Apples' }, { id: '1_2', text: 'Oranges' } ] }, { id: '2', text: 'Vegetables', items: [ { id: '2_1', text: 'Cucumbers' }, { id: '2_2', text: 'Tomatoes' } ] }];
If data has a plain structure, set the dataStructure property to "plain". In this case, each data item should have a text
, a unique id
, and a parentId
. For root items, parentId
should be equal to 0 or undefined:
var plainData = [ { id: '1', text: 'Fruits' }, // A root item { id: '1_1', text: 'Apples', parentId: '1' }, { id: '1_2', text: 'Oranges', parentId: '1' }, { id: '2', text: 'Vegetables' }, // Also a root item { id: '2_1', text: 'Cucumbers', parentId: '2' }, { id: '2_2', text: 'Tomatoes', parentId: '2' } ];
id
, text
, items
, and parentId
are conventional field names. To use other names, change the keyExpr, displayExpr, itemsExpr, and parentIdExpr properties, respectively. You can also specify the rootValue property to change the parentId
value that root items should have.
See Also
disabledExpr
Specifies the name of the data source item field whose value defines whether or not the corresponding UI component item is disabled.
displayExpr
Set this property to the name of a data field that provides displayed values...
displayExpr: "name"
... or to a function that returns the displayed value:
displayExpr: function(item) { // "item" can be null return item && 'ID: ' + item.id + ', Name: ' + item.name; }
See Also
elementAttr
Specifies the global attributes to be attached to the UI component's container element.
jQuery
$(function(){ $("#treeViewContainer").dxTreeView({ // ... elementAttr: { id: "elementId", class: "class-name" } }); });
Angular
<dx-tree-view ... [elementAttr]="{ id: 'elementId', class: 'class-name' }"> </dx-tree-view>
import { DxTreeViewModule } from "devextreme-angular"; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxTreeViewModule ], // ... })
Vue
<template> <DxTreeView ... :element-attr="treeViewAttributes"> </DxTreeView> </template> <script> import DxTreeView from 'devextreme-vue/tree-view'; export default { components: { DxTreeView }, data() { return { treeViewAttributes: { id: 'elementId', class: 'class-name' } } } } </script>
React
import React from 'react'; import TreeView from 'devextreme-react/tree-view'; class App extends React.Component { treeViewAttributes = { id: 'elementId', class: 'class-name' } render() { return ( <TreeView ... elementAttr={this.treeViewAttributes}> </TreeView> ); } } export default App;
hasItemsExpr
Specifies the name of the data source item field whose value defines whether or not the corresponding node includes child nodes.
height
This property 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:JavaScriptheight: function() { return window.innerHeight / 1.5; }
itemComponent
An alias for the itemTemplate property specified in React. Accepts a custom component. Refer to Using a Custom Component for more information.
itemRender
An alias for the itemTemplate property specified in React. Accepts a rendering function. Refer to Using a Rendering Function for more information.
items[]
The TreeView 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 property to notify the TreeView of the used structure and refer to the property's description for information on the required fields.
If you need to update the UI component items, reassign the entire items array as shown in the following example:
treeViewInstance.option('items', newItems);
As an alternative to items, you can use the dataSource property. It accepts the DataSource object, whose underlying stores provide an API that allows you to update individual items without reassigning the entire item collection.
itemsExpr
Specifies which data field contains nested items. Applies only if the dataStructure property is "tree".
noDataText
The TreeView component evaluates the noDataText property's value. This evaluation, however, makes the TreeView potentially vulnerable to XSS attacks. To guard against these attacks, encode the HTML markup before you assign it to the noDataText property. Refer to the following help topic for more information: Potentially Vulnerable API - noDataText.
onContentReady
A function that is executed when the UI component's content is ready and each time the content is changed.
Name | Type | Description |
---|---|---|
component |
The UI component's instance. |
|
element |
The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
model |
Model data. Available only when using Knockout. |
onDisposing
A function that is executed before the UI component is disposed of.
Name | Type | Description |
---|---|---|
component |
The UI component's instance. |
|
element |
The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
model |
Model data. Available only if you use Knockout. |
onInitialized
Name | Type | Description |
---|---|---|
component |
The UI component's instance. |
|
element |
The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery. |
onItemClick
Name | Type | Description |
---|---|---|
model |
Model data. Available only if Knockout is used. |
|
itemIndex | | |
The clicked item's index. |
itemElement |
The clicked item's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
itemData |
The clicked item's data object. |
|
event | Event (jQuery or EventObject) |
The event that caused the function to execute. It is a dxEvent or a jQuery.Event when you use jQuery. |
element |
The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
component |
The UI component's instance. |
|
node |
The clicked item's node. |
onItemCollapsed
Name | Type | Description |
---|---|---|
component |
The UI component's instance. |
|
element |
The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
event | Event (jQuery or EventObject) |
The event that caused the function to execute. It is a dxEvent or a jQuery.Event when you use jQuery. |
itemData |
The collapsed item's data. |
|
itemElement |
The item's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
itemIndex |
The item's index. |
|
model |
Model data. Available only if Knockout is used. |
|
node |
The item's node. |
onItemContextMenu
Name | Type | Description |
---|---|---|
model |
Model data. Available only if Knockout is used. |
|
itemIndex | | |
The target item's index. |
itemElement |
The target item's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
itemData |
The target item's data object. |
|
event | Event (jQuery or EventObject) |
The event that caused the function to execute. It is a dxEvent or a jQuery.Event when you use jQuery. |
element |
The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
component |
The UI component's instance. |
|
node |
The target item's node. |
onItemExpanded
Name | Type | Description |
---|---|---|
component |
The UI component's instance. |
|
element |
The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
event | Event (jQuery or EventObject) |
The event that caused the function to execute. It is a dxEvent or a jQuery.Event when you use jQuery. |
itemData |
The expanded item's data. |
|
itemElement |
The item's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
itemIndex |
The item's index. |
|
model |
Model data. Available only if Knockout is used. |
|
node |
The item's node. |
onItemHold
A function that is executed when a collection item has been held for a specified period.
Name | Type | Description |
---|---|---|
model |
Model data. Available only if Knockout is used. |
|
itemIndex |
The item's index. |
|
itemElement |
The item's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
itemData |
The data object of the item being held. |
|
event | Event (jQuery or EventObject) |
The event that caused the function to execute. It is a dxEvent or a jQuery.Event when you use jQuery. |
element |
The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
component |
The UI component's instance. |
|
node |
The node of the item being held. |
onItemRendered
Name | Type | Description |
---|---|---|
model |
Model data. Available only if Knockout is used. |
|
itemIndex |
The rendered item's index. |
|
itemElement |
The rendered item's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
itemData |
The rendered item's data object. |
|
element |
The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
component |
The UI component's instance. |
|
node |
The rendered item's node. |
onItemSelectionChanged
Name | Type | Description |
---|---|---|
component |
The UI component's instance. |
|
element |
The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
itemData |
The selected item's data. |
|
itemElement |
The item's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
itemIndex |
The item's index. |
|
model |
Model data. Available only if Knockout is used. |
|
node |
The item's node. |
This function is executed when:
Users select an item by click or using its checkbox.
The selectItem() or unselectItem() method is called.
Alternatively, you can use the onSelectionChanged function, which is executed in all the cases above, and when all items are selected simultaneously.
onOptionChanged
Name | Type | Description |
---|---|---|
model |
Model data. Available only if you use Knockout. |
|
fullName |
The path to the modified property that includes all parent properties. |
|
element |
The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
component |
The UI component's instance. |
|
name |
The modified property if it belongs to the first level. Otherwise, the first-level property it is nested into. |
|
value | any |
The modified property's new value. |
The following example shows how to subscribe to component property changes:
jQuery
$(function() { $("#treeViewContainer").dxTreeView({ // ... onOptionChanged: function(e) { if(e.name === "changedProperty") { // handle the property change here } } }); });
Angular
<dx-tree-view ... (onOptionChanged)="handlePropertyChange($event)"> </dx-tree-view>
import { Component } from '@angular/core'; @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { // ... handlePropertyChange(e) { if(e.name === "changedProperty") { // handle the property change here } } }
import { BrowserModule } from '@angular/platform-browser'; import { NgModule } from '@angular/core'; import { AppComponent } from './app.component'; import { DxTreeViewModule } from 'devextreme-angular'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, DxTreeViewModule ], providers: [ ], bootstrap: [AppComponent] }) export class AppModule { }
Vue
<template> <DxTreeView ... @option-changed="handlePropertyChange" /> </template> <script> import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import DxTreeView from 'devextreme-vue/tree-view'; export default { components: { DxTreeView }, // ... methods: { handlePropertyChange: function(e) { if(e.name === "changedProperty") { // handle the property change here } } } } </script>
React
import React from 'react'; import 'devextreme/dist/css/dx.common.css'; import 'devextreme/dist/css/dx.light.css'; import TreeView from 'devextreme-react/tree-view'; const handlePropertyChange = (e) => { if(e.name === "changedProperty") { // handle the property change here } } export default function App() { return ( <TreeView ... onOptionChanged={handlePropertyChange} /> ); }
onSelectAllValueChanged
A function that is executed when the "Select All" check box value is changed. Applies only if showCheckBoxesMode is "selectAll" and selectionMode is "multiple".
Name | Type | Description |
---|---|---|
component |
The UI component's instance. |
|
element |
The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
model |
Model data. Available only if Knockout is used. |
|
value | | undefined |
The "Select All" check box's new state. |
onSelectionChanged
Name | Type | Description |
---|---|---|
component |
The UI component's instance. |
|
element |
The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery. |
|
model |
Model data. Available only if Knockout is used. |
This function is executed when:
Users select an item by click or using a checkbox.
One of the following methods is called: selectAll(), unselectAll(), selectItem(), unselectItem().
parentIdExpr
Specifies the name of the data source item field for holding the parent key of the corresponding node.
rtlEnabled
When this property is set to true, the UI component text flows from right to left, and the layout of elements is reversed. To switch the entire application/site to the right-to-left representation, assign true to the rtlEnabled field of the object passed to the DevExpress.config(config) method.
DevExpress.config({ rtlEnabled: true });
searchEditorOptions
See the TextBox Configuration for properties you can specify in this object.
searchEnabled
See Also
selectedExpr
Specifies the name of the data source item field whose value defines whether or not the corresponding UI component items is selected.
selectionMode
To enable selection, set selectByClick to true or showCheckBoxesMode to "normal" or "selectAll".
selectNodesRecursive
Specifies whether all child nodes should be selected when their parent node is selected. Applies only if the selectionMode is "multiple".
showCheckBoxesMode
The property accepts the following values:
"none"
The UI component does not display checkboxes."normal"
The UI component displays one checkbox per item."selectAll"
The UI component displays one checkbox per item and one "Select All" checkbox at the top of the UI component. The selectionMode should be "multiple".
See Also
tabIndex
The value of this property will be passed to the tabindex
attribute of the HTML element that underlies the UI component.
virtualModeEnabled
Enables the virtual mode in which nodes are loaded on demand. Use it to enhance the performance on large datasets.
If this property is true, the UI component initially loads only the root nodes. Child nodes are loaded when their parent is being expanded.
The virtual mode has the following restrictions:
The dataSource property should be set to a DataSource instance able to filter items by parent ID.
The dataStructure property should be set to "plain".
Since the search will be performed on loaded nodes only and thus produce incorrect results, it is not recommended that you enable this functionality.
See Also
width
This property accepts a value of one of the following types:
Number
The width in pixels.String
A CSS-accepted measurement of width. For example,"55px"
,"80%"
,"auto"
,"inherit"
.Function
A function returning either of the above. For example:JavaScriptwidth: function() { return window.innerWidth / 1.5; }