Collection Container Widgets

This article describes common principles of working with such widgets as lists, menus, tile views, etc., which are intended to display data items specific to your needs.

Common Tasks

When working with a collection container widget, you can often encounter tasks common for all collection containers. This section describes the most important common tasks such as specifying a data source, handling item events and customizing the appearance of widget items.

Specify Data Source

All collection container widgets include the dataSource option, which takes on an array of items, or a DataSource instance. Using a DataSource instance gives you a great advantage, because it can access data whether it is stored in an in-memory array, local storage or remote data service. Whatever data source you use, you can always access data currently displayed by a collection container widget using the items option.

JavaScript
var myDataSource = new DevExpress.data.DataSource("http://www.example.com/dataservices/jsondata"),
var listOptions = { dataSource: myDataSource }

For detailed information on working with data, refer to the Data Layer and Data Source Examples documentation sections.

In MVVM approach, if you are using a collection widget to display several items, which are not bound to a data source, you may use the dxItem markup component. This approach enables you to define individual markup for each item.

AngularJS Approach
HTML
<div dx-list="{}" >
    <div data-options="dxItem: {}">
        <!--First item markup-->
    </div>
    <div data-options="dxItem: {}">
        <!--Second item markup-->
    </div>
    <div data-options="dxItem: { disabled: true }">
        <!--Third item markup-->
    </div>
    . . .
</div>
Knockout Approach
HTML
<div data-bind="dxList" >
    <div data-options="dxItem: {}">
        <!--First item markup-->
    </div>
    <div data-options="dxItem: {}">
        <!--Second item markup-->
    </div>
    <div data-options="dxItem: { disabled: true }">
        <!--Third item markup-->
    </div>
    . . .
</div>

Handle Item Events

Each collection container widget contains the following options, which allow you to specify handlers for events raised by a widget item.

  • onItemClick
    Specifies the function called on an item click.

  • onItemContextMenu
    Specifies the function called when the right mouse button is held or clicked when the pointer is over an item.

  • onItemDeleted
    Specifies the function called after an item is deleted.

  • onItemDeleting
    Specifies the function called before an item is deleted.

  • onItemHold
    Specifies the function called on an item held during a specified time span.

  • onSelectionChanged
    Specifies the function called when an item is selected.

  • onItemRendered
    Specifies the function called after an item is rendered.

  • onItemReordered
    Specifies the function called after an item is moved to another position.

JavaScript
var listOptions = { 
    onItemClick: function() {
        alert("List item is clicked");
    },
    onItemHold: function() {
        alert("List item is held");
    },
    onSelectionChanged: function() {
        alert("List item is selected");
    }
}

Note that you can use the onItemDeleting option to add a confirmation dialog displayed when a widget item is deleted. The function passed to this option should return a Promise of the jQuery Deferred object, which is resolved if item deletion is confirmed and rejected if deletion is canceled.

JavaScript
var widgetOptions = {
    onItemDeleting: function(e) {
        return DevExpress.ui.dialog.confirm("Do you really want to delete the item?");
    })
}
See Also

Customize an Item Appearance

In the most simple case, a collection container widget item has a simple textual presentation.

The information below shows how to use a default item template.

Note that in most cases, widget items require a more complex structure. For instance, it may consist of several text blocks with images. To customize the appearance of such items, specify a template for these items or a function that renders them. To learn common principles of customizing widget element appearance, refer to the Customize Widget Element Appearance article.

See Also

Use a Default Item Template

For each collection container widget, a default item template is defined out-of-the-box. Default templates are based on a predefined set of fields in the widget data source, requiring you to provide the required set of fields for your widget's data source, so that widget items are displayed using a default template. The following are the fields that are used in a default item template of any widget.

  • disabled
    Specifies whether or not the list item is disabled.
  • visible
    Specifies whether or not the list item is visible.
  • html
    Specifies the html code inserted into the item element.
  • template
    Specifies an item template that should be used to render this item only.
  • text
    Specifies the text inserted into the item element.

However, additional fields can be required for item templates of certain widgets. For instance, a default template for the dxList widget is based on the set of fields above. However, the key field is also required to specify the group to which an item is related. To learn what set of fields is required for a specific widget, refer to the Default Item Template reference section of this widget.

In certain scenarios, it is enough to specify a simple array as a widget data source. In this instance, in Knockout approach, a default item template contains text binding associated with the current array value.

Search Through Items

When working with collection widgets, it is often useful to filter displayed items by a specified text. DevExtreme enables you to easily implement a search in a collection widget using the DataSource search engine.

To implement a search, you need to associate a collection widget with a DataSource instance that supports search capabilities, add the dxTextBox widget used to type the search value, and update the DataSource search criterion each time the dxTextBox value is changed.

For detailed information on search implementation, refer to the Implement Search in a Collection Widgets tutorial.

List of Collection Container Widgets

The following DevExtreme UI widgets are related to the collection containers category.

dxAccordion

The dxAccordion widget displays items one under another and enables an end-user to collapse and expand these items. A displayed item consists of a body and a title. If an item is collapsed, the widget displays only its title.

View Demo

The widget supports common Collection Container widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common collection container functionality, the widget enables you to perform the following adjustments.

Specify the appearance of an item title

Customize item title appearance using one of the following ways.

  • Use a default item title template

    In this case, the item object should contain the title field, which specifies the text displayed by the item title.

    JavaScript
    var accordionData = [
        {
            title: "Personal Data",
            firstName: "John",
            lastName: "Smith",
            birthYear: 1986
        },
        {
            title: "Contacts",
            phone: "(555)555-5555",
            email: "John.Smith@example.com"
        },
        . . .
    ];
    var accordionOptions = {
        dataSource: accordionData
    }
  • Implement a custom template for an item title

    Assign a function that modifies the title element to the itemTitleTemplate option.

    JavaScript
    var accordionOptions = {
        dataSource: accordionData,
        itemTitleTemplate: function(itemData, itemIndex, itemElement){
            var titleContainer = $("<div>").css('text-align','center').append("<h2>" + itemData.title + "</h2>");
            titleContainer.appendTo(itemElement);
        }
    }

    In MVVM approach, you can assign a template name, a template DOM node or a jQuery object of the template to the itemTitleTemplate option.

    AngularJS Approach
    HTML
    <div dx-accordion = "{ dataSource: accordionData, itemTitleTemplate: 'myTitle' }">
        <div data-options="dxTemplate: {name: 'myTitle'}">
            <div style="text-align: center;">
                <h2>{{title}}</h2>
            </div>
        </div>
    </div>   
    Knockout Approach
    HTML
    <div data-bind="dxAccordion: { dataSource: accordionData, itemTitleTemplate: 'myTitle' }">
        <div data-options="dxTemplate: {name: 'myTitle'}">
            <div style="text-align: center;">
                <h2 data-bind="text: title"></h2>
            </div>
        </div>
    </div>
See Also

Adjust display modes

The widget contains the collapsible option, which enables you to specify whether all items can be collapsed at the same time or at least one item should be expanded.

JavaScript
var accordionOptions = {
    collapsible: true
}

The dxAccordion widget enables you to specify whether it can display several expanded items at once or only a single item. Use the multiple option to adjust this feature.

JavaScript
var accordionOptions = {
    multiple: true
}

Keyboard support

An end-user can use the following keys to interact with the widget.

  • Up/down arrow (page up/down) Set focus on the previous/next item.

  • Home/End Set focus on the first/last element.

  • Enter (Space) Expand/collapse the current element.

dxActionSheet

The dxActionSheet widget is a sheet containing a set of buttons located one under the other. These buttons usually represent several choices relating to a single task.

View Demo

The widget supports common Collection Container widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common collection container functionality, the widget enables you to perform the following adjustments.

Specify action sheet popup type

By default the widget displays the popup window as an overlay window floating from the bottom of the screen. You can assign true to the usePopover option to display the action sheet as a popover pointing at the specified target element. In this case, you should also specify the target element for the popover using the target option.

JavaScript
var actionSheetOptions = {
    dataSource: popoverData,
    usePopover: true,
    target: $("#actionSheetTarget")
}

Control the widget visibility

The action sheet is mostly hidden, and is only shown when an end-user should choose an action.

Use the show() and hide() methods, which show or hide the widget respectively.

JavaScript
showActionSheet = function() {
    var actionSheet = $("#actionSheetContainer").dxActionSheet("instance");
    actionSheet.show();
}
hideActionSheet = function() {
    var actionSheet = $("#actionSheetContainer").dxActionSheet("instance");
    actionSheet.hide();
}

You can also change widget visibility using the toggle(showing) method, which shows or hides the widget depending on the value of the showing parameter.

JavaScript
// Get the widget instance.
...
showActionSheet = function() {
    actionSheetInstance.toggle(true);
}
hideActionSheet = function() {
    actionSheetInstance.toggle(false);
}

Another way is to use the visible option. In MVVM approach, provide two-way binding to the option to show or hide the widget depending on the variable value. To show or hide the widget, assign true or false to the appropriate field respectively.

AngularJS Approach
JavaScript
function Controller($scope) {
    $scope.showActionSheet = function() {
        $scope.actionSheetVisible = true;
    }
    $scope.hideActionSheet = function() {
        $scope.actionSheetVisible = false;
    }
    $scope.actionSheetVisible = false;
}
HTML
<div ng-controller="Controller">
    <div dx-action-sheet="{ bindingOptions: { 'visible': 'actionSheetVisible' }}"></div>
</div>
Knockout Approach
HTML
<div id="actionSheetContainer" data-bind="dxActionSheet: {
     visible: actionSheetVisible
}"></div>
JavaScript
var actionSheetVisible = ko.observable(false);
var showActionSheet = function() {
    actionSheetVisible(true);
}
var hideActionSheet = function() {
    actionSheetVisible(false);
}

Show the action sheet title

To display the action sheet title, assign true to the showTitle option. The title text is specified using the title option.

JavaScript
var actionSheetOptions = {
    dataSource: popoverData,
    showTitle: true,
    title: 'Choose action'
}

Specify availability of additional UI elements

You can specify the availability of the Cancel button on the action sheet using the showCancelButton option. This button enables an end-user to close the widget without choosing any suggested action. If the widget is displayed as a popover, the Cancel button is always unavailable. In this case, the popover window is closed if a user clicks outside of this window.

The button text is specified using the cancelText option.

JavaScript
var actionSheetOptions = {
    dataSource: popoverData,
    showCancelButton: true,
    cancelText: 'Cancel'
}

dxContextMenu

A context menu is a set of options that are specific for the element for which this menu is displayed. The set of menu options can be multi-level. You can customize item appearance and behaviour at any level if your task requires it.

View Demo

The dxContextMenu widget is a menu widget supporting collection container functionality. For more information on this widget, refer to the Menu Widgets guide.

dxGallery

The dxGallery widget displays images in a horizontally scrolled view. Refer to the dxGallery guide for more information.

View Demo

dxList

The dxList widget displays selected items as a scrollable list. Refer to the dxList widget guide for more information.

View Demo

dxMenu

dxMultiView

The dxMultiView widget contains several views and allows an end-user to switch between them. These views are placed horizontally next to one another and navigated by panning to the left or right.

View Demo

The widget supports common Collection Container widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common collection container functionality, the widget enables you to perform the following adjustments.

Switch between views

By default, an end-user can switch between views by swiping. Assign false to the swipeEnabled option to disable this feature.

JavaScript
var multiViewOptions = {
    dataSource: multiViewData,
    swipeEnabled: false
}

You can also switch between views programmatically, using the selectedIndex option.

See Also

Display views in a loop

The dxMultiView widget can display views in a loop. If the widget loop mode is enabled, it scrolls back to the first item if an end-user navigates forward from the last item, or goes to the last item if an end-user navigates backward from the first item. The loop mode is disabled by default. To enable it, assign true to the loop configuration option.

JavaScript
var dxMultiViewOptions = {
    dataSource: multiViewData,
    loop: true
}

Animate switching between views

By default, the widget animates switching between views. You can disable animation by setting the animationEnabled option to false.

JavaScript
var dxMultiViewOptions = {
    dataSource: multiViewData,
    animationEnabled: false
}

dxNavBar

The dxNavBar widget contains items used to navigate through application views.

View Demo

The widget supports common Collection Container widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common collection container functionality, the widget enables you to perform the following adjustments.

Specify an item caption and icon

In most cases, a NavBar item includes an icon and a caption specified by the relevant properties of the corresponding data source item object. The item caption is specified by the text property. The item icon can be specified by the icon property.

If the icon library contains the required icon, assign the icon name to the icon property.

JavaScript
var navItems = [
    { text: "Home", icon: "home" },
    { text: "About", icon: "info" }
]

The icon property also accepts a path to a custom image file.

JavaScript
var navItems = [
    { text: "Home", icon: "images/icons/home.png" },
    { text: "About", icon: "images/icons/info.png" }
];

Display an item badge

You can also display a badge for a NavBar item. If the item object includes the badge property, the widget displays the text assigned to this property as a badge.

JavaScript
var navItems = [
    { text: "Home", icon: "home" },
    { text: "About", icon: "info" },
    { text: "favorites", icon: "favorites", badge: "new" }
];

Keyboard support

An end-user can use the Left/Right arrow key to move focus to the previous/next item.

dxPanorama

The dxPanorama widget is a full screen widget that allows you to locate widgets, display data and provide services by using a long horizontal canvas that extends beyond the frames of the screen. Content is divided into items that can be explored by panning and flicking. When viewing an item, you will be able to see a portion of the item next to it. This widget is often used as a navigation map on the first page of an application. Although dxPanorama was designed based on the native WindowsPhone8 Panorama widget, it can be used on any platform.

View Demo

The widget supports common Collection Container widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common collection container functionality, the widget enables you to perform the following adjustments.

Specify panorama title and background

All widget items are displayed against the same background and title. The title text is specified using the title option. If you want to use a background image, you should pass a configuration object containing the following properties to the backgroundImage option.

  • height
    Specifies the height of the background image.

  • width
    Specifies the width of the background image.

  • url
    Specifies the url of the background image file.

JavaScript
var panoramaOptions = {
    dataSource: panoramaData,
    title: "Online restaurant",
    backgroundImage: {
        width: 500,
        height: 300,
        url: "/images/panoramaBackground.png"
    }
}

dxPivot

A widget that is similar to a traditional tab control, but optimized for the phone with simplified end-user interaction.

View Demo

The widget supports common Collection Container widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

The dxPivot widget includes items placed horizontally next to one another and navigated by flicking or panning to the left or right, or by choosing the desired pivot header. While you always see the content of one item, the pivot header of the next item is visible so users can clearly see that more items are available. This widget is often used to present lists of data filtered by different criteria.

JavaScript
contacts = [
    { name: "Barbara J. Coggins", phone: "512-964-2757", email: "BarbaraJCoggins@rhyta.com", category: "Family" },
    { name: "Carol M. Das", phone: "360-684-1334", email: "CarolMDas@jourrapide.com", category: "Friends" },
    { name: "Janet R. Skinner", phone: "520-573-7903", email: "JanetRSkinner@jourrapide.com", category: "Work" },
    . . .
];
var pivotOptions = {
    dataSource: [
        {
            title: "All",
            listItems: new DevExpress.data.DataSource({
                store: contacts, sort: "name"
            })
        },
        {
            title: "Family",
            listItems: new DevExpress.data.DataSource({
                store: contacts, sort: "name", filter: ["category", "=", "Family"]
            })
        },
        {
            title: "Friends",
            listItems: new DevExpress.data.DataSource({
                store: contacts, sort: "name", filter: ["category", "=", "Friends"]
            })
        },
        {
            title: "Work",
            listItems: new DevExpress.data.DataSource({
                store: contacts, sort: "name", filter: ["category", "=", "Work"]
            })
        }
    ]
}

dxSlideOut

The dxSlideOut widget consists of the main view and the menu revealed when the main view slides out. The main view displays the currently selected item.

View Demo

The widget supports common Collection Container widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common collection container functionality, the widget enables you to perform the following adjustments.

Adjust an item and menu item appearance

NOTE
The itemTemplate option is used to specify the appearance of a selected item. Menu item appearance is specified in the same manner, but use the menuItemTemplate option to specify the menu item template.
JavaScript
var contacts = [
    { name: "Barbara J. Coggins", phone: "512-964-2757", email: "BarbaraJCoggins@rhyta.com", category: "Family" },
    { name: "Carol M. Das", phone: "360-684-1334", email: "CarolMDas@jourrapide.com", category: "Friends" },
    { name: "Janet R. Skinner", phone: "520-573-7903", email: "JanetRSkinner@jourrapide.com", category: "Work" },
    . . .
];
$("#mySlideOut").dxSlideOut({
    dataSource: contacts,
    itemTemplate: function(itemData, itemIndex, itemElement){
        itemElement.append("<h1>" + itemData.category + "</h1>");
        itemElement.append("<p><b>Name:</b> " + itemData.name + "</p>");
        itemElement.append("<p><b>Phone:</b> " + itemData.phone + "</p>");
        itemElement.append("<p><b>e-mail:</b> " + itemData.email + "</p>");
    },
    menuItemTemplate: function(itemData, itemIndex, itemElement){
        itemElement.append("<b>" + itemData.name + "</b>");
    }
});
HTML
<div id="mySlideOut"></div>
AngularJS Approach
JavaScript
var contacts = [
    { name: "Barbara J. Coggins", phone: "512-964-2757", email: "BarbaraJCoggins@rhyta.com", category: "Family" },
    { name: "Carol M. Das", phone: "360-684-1334", email: "CarolMDas@jourrapide.com", category: "Friends" },
    { name: "Janet R. Skinner", phone: "520-573-7903", email: "JanetRSkinner@jourrapide.com", category: "Work" },
    . . .
];
var slideOutOptions = {
    dataSource: contacts,
    itemTemplate: 'item',
    menuItemTemlate: 'menuItem'
}
HTML
<div dx-slide-out="slideOutOptions" dx-item-alias="itemObj">
    <div data-options="dxTemplate: { name: 'item' }">
        <h1>{{itemObj.category}}</h1>
        <p><b>Name:</b> {{itemObj.name}}</p>
        <p><b>Phone:</b> {{itemObj.phone}}</p>
        <p><b>e-mail:</b> {{itemObj.email}}</p>
    </div>
    <div data-options="dxTemplate: { name: 'menuItem' }">
        <b>{{itemObj.name}}</b>
    </div>
</div>
Knockout Approach
JavaScript
var contacts = [
    { name: "Barbara J. Coggins", phone: "512-964-2757", email: "BarbaraJCoggins@rhyta.com", category: "Family" },
    { name: "Carol M. Das", phone: "360-684-1334", email: "CarolMDas@jourrapide.com", category: "Friends" },
    { name: "Janet R. Skinner", phone: "520-573-7903", email: "JanetRSkinner@jourrapide.com", category: "Work" },
    . . .
];
var slideOutOptions = {
    dataSource: contacts,
    itemTemplate: 'item',
    menuItemTemlate: 'menuItem'
}
HTML
<div data-bind="dxSlideOut: slideOutOptions">
    <div data-options="dxTemplate: { name: 'item' }">
        <h1 data-bind="text: category"></h1>
        <p><b>Name:</b> <span data-bind="text: name"></span></p>
        <p><b>Phone:</b> <span data-bind="text: phone"></span></p>
        <p><b>e-mail:</b> <span data-bind="text: email"></span></p>
    </div>
    <div data-options="dxTemplate: { name: 'menuItem' }">
        <b data-bind="text: name"></b>
    </div>
</div>

Display grouped menu

The widget enables you to display menu items in groups. Set the menuGrouped option to true to enable the feature. In this case, the data source should contain a grouped array. A grouped array item should contain a property that specifies the group name and the items property containing items belonging to the group. If you use a default template, the group name should be specified by the key property.

JavaScript
var groupedData = [
    {
        key: 'group 1',
        items: [ 'item11', 'item12', 'item13', 'item14']
    },
    {
        key: 'group 2',
        items: [ 'item21', 'item22', 'item23', 'item24']
    },
    {
        key: 'group 3',
        items: [ 'item31', 'item32', 'item33', 'item34']
    }
]
var slideOutOptions = {
    dataSource: groupedData,
    menuGrouped: true
}

dxTabPanel

The dxTabPanel widget consists of the dxTabs and dxMultiView widgets. It automatically synchronizes the selected tab and the currently displayed view. If a user switches a tab, the widget displays the appropriate view and when a user switches a view by swiping, the widget selects the appropriate tab.

View Demo

The widget supports common Collection Container widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common collection container functionality, the widget enables you to perform the following adjustments.

The set of items displayed by the widget is specified by the dataSource option. The widget creates a tab and a view for each item.

The widget includes the itemTemplate and titleTemplate options, which enable you to customize the appearance of an item view and item tab respectively.

See Also

You can specify whether or not the widget enables a user to switch items by swiping a view. Assign true to the swipeEnabled option to enable this feature, otherwise assign false.

JavaScript
var tabPanelOptions = {
    swipeEnabled: true
}

The widget can display views in a loop. If this mode is enabled, it scrolls back to the first item if an end-user navigates forward from the last item, or goes to the last item if an end-user navigates backward from the first item. The loop mode is enabled by default. To disable it, assign false to the loop configuration option.

JavaScript
var tabPanelOptions = {
    loop: false
}

To specify whether or not to animate switching between items, use the animationEnabled option.

JavaScript
var tabPanelOptions = {
    animationEnabled: true
}

Keyboard support

An end-user can use the Left/Right arrow key to display the previous/next view.

dxTabs

The dxTabs widget is a tab strip used to switch between pages. This widget is used as a part of the TabPanel widget, which includes also the MultiView widget used to display the selected tab contents. However, you can use the dxTabs widget separately.

View Demo

The widget supports common Collection Container widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common collection container functionality, the widget enables you to perform the following adjustments.

Specify the icon and caption of a tab

In most cases, a tab item includes an icon and a caption specified by the appropriate properties of the corresponding data source item object. The item caption is specified by the text property. The item icon can be specified by the icon property.

If the icon library contains the required icon, assign the icon name to the icon property.

JavaScript
var tabItems = [
    { text: "Home", icon: "home" },
    { text: "About", icon: "info" }
]

The icon property also accepts a path to a custom image file.

JavaScript
var tabItems = [
    { text: "Home", icon: "images/icons/home.png" },
    { text: "About", icon: "images/icons/info.png" }
];

Keyboard support

An end-user can use the Left/Right arrow key to move focus to the previous/next tab.

dxTagBox

The dxTagBox widget is an editor widget that supports a collection container functionality. For more information on this widget, refer to the Editor widgets guide.

View Demo

dxTileView

The dxTileView widget displays data items as tiles.

View Demo

The widget supports common Collection Container widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common collection container functionality, the widget enables you to perform the following adjustments.

Specify the size of a tile

The base size of a tile is determined by the baseItemHeight and baseItemWidth options. The actual tile size depends on values of the widthRatio and heightRatio properties of an item object. The actual size of a tile is the base size multiplied by ratio.

JavaScript
var states = [
    . . .
    { name: "Maine", capital: "Augusta" },
    { name: "Maryland", capital: "Annapolis" },
    { name: "Massachusetts", capital: "Boston", widthRatio:2 }
    . . .
]
var tileViewOptions = {
    dataSource: states,
    baseItemHeight: 130,
    baseItemWidth: 180
}

Specify the margin of a tile

The distance between tiles is specified by the itemMargin option.

JavaScript
var tileViewOptions = {
    dataSource: states,
    itemMargin: 20
}

Display the scrollbar

You can specify whether or not the widget displays the scrollbar. Assign true to the showScrollbar option to display the scrollbar.

JavaScript
var tileViewOptions = {
    dataSource: states,
    showScrollbar: true
}

Specify scrolling direction

The widget size is specified using the width and height options. If the specified size is not enough to display all tiles, the widget enables scrolling. Scrolling direction is specified using the direction option, which accepts "horizontal" and "vertical" values. By default, the widget places tiles horizontally.

Keyboard support

An end-user can use the following keys to interact with the widget.

  • Up/down/left/right arrow
    Move focus to a neighboring item.

  • Home/End Move focus to the first/last item.

  • Enter (Space) Select the focused item.

dxToolBar

The dxToolbar widget displays a set of UI elements usually used to manage screen content. The toolbar can contain plain text items and items representing a widget.

The widget supports common Collection Container widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common collection container functionality, the widget enables you to perform the following adjustments.

Specify an item type

To create a toolbar item containing a widget, add an item that includes the widget property to the array of toolbar items. You can assign one of the following values to this field.

  • 'button'
    A dxButton widget

  • 'tabs'
    A dxTabs widget

  • 'dropDownMenu'
    A drop-down menu

To configure the widget representing a toolbar item, use the options property of the data source item object. Set the options that are exposed by the specified widget.

Specify an item location

To set a location of toolbar items, use the location option of the data source item object. You can assign one of the following values: 'before', 'after' or 'center'. To add the toolbar item to the toolbar's overflow menu, specify the locateInMenu option. This menu is displayed by a drop-down menu, or the dxPopover, dxActionSheet, application bar widget based on the device on which the application is running. You can introduce a custom template for menu items using the menuItemTemplate option.

See Also
JavaScript
var buttonClickHandler = function () {
    //Process a button click
};
var menuItemClickHandler = function (e) {
    //Process a menu item click
};
var toolbarItems = [
    {
        location: 'before',
        widget: 'button',
        options: {
            type: 'back',
            text: 'Back',
            onClick: buttonClickHandler
        } 
    },
    {
        location: 'after', widget: 'dropDownMenu', options: {
            items: ["Add", "Change", "Remove"],
            onItemClick: menuItemClickHandler
        }
    },
    { location: 'center', text: 'Products' }
];
var toolbarOptions = {
    dataSource: toolbarItems
}

Use top/bottom toolbar appearance

When configuring the dxToolbar widget, use the renderAs option to specify the location of this widget in an HTML template of a view. Depending on the value that you set for this option, the widget's appearance will be adjusted accordingly.

JavaScript
var toolbarOptions = {
    dataSource: toolbarItems
    renderAs: 'bottomToolbar'
}

Keyboard support

An end-user can move focus to the next or previous item using the Tab or Shift+Tab shortcuts respectively.

dxTreeView

The dxTreeView widget displays specified data using a tree structure.

NOTE
The dxTreeView widget requires each data source item to contain at least a key field. Thus, the widget does not support data sources consisting of value items.

View Demo

The widget supports common Collection Container widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common collection container functionality, the widget enables you to perform the following adjustments.

Adjust data item structure

The widget requires each data item to have a key field whose value is unique within the entire array. By default, the widget uses the id field as a key. If you need to use another field as a key, pass the required field name to the keyExpr option.

JavaScript
var treeViewOptions = {
    keyExpr: 'id'
}

Tree View Nodes

The widget holds the displayed items as a node tree. Each tree item is associated with the appropriate node. A tree view node is an object containing the following fields.

  • children
    An array of references to child nodes.

  • disabled
    A boolean value indicating whether or not the node is disabled.

  • expanded
    A boolean value indicating whether or not the node is expanded.

  • itemData
    A reference to the tree view data source item associated with the current node.

  • key
    The key value of the current node. This field holds a value obtained from the data source item associated with the current node according to the keyExpr option value. If the keyExpr value is not specified, the key field holds the auto generated key value.

  • parent
    A reference to the parent node.

  • selected
    A boolean value indicating whether or not the node is selected.

  • text
    The text displayed by the node. This field holds a value obtained from the data source item associated with the current node according to the displayExpr option value.

You can access a node object using the node field of an argument object passed to a handler for a tree item event.

JavaScript
var treeViewOptions = {
    . . .
    onItemClick: function(e){
        //Access the node associated with the clicked item using the 'e.node' field
    }
}

The widget also enables you to get the list of all nodes using the getNodes() method.

JavaScript
// Get the widget instance
...
var treeViewNodes = treeViewInstance.getNodes();

Use the data source with tree structure

By default, the widget repeats the data array structure when displaying items. In this case, each item should include the items field, which holds the nested array.

JavaScript
var treeViewData = [
    {
        id: 1,
        text: "Animals",
        items:[
            { 
                id: 2,
                text: "Cat",
                items: [
                    { id: 5, text: "Abyssinian" },
                    { id: 6, text: "Aegean cat" },
                    { id: 7, text: "Australian Mist" }
                ]
            },
            { 
                id: 3,
                text: "Dog",
                items: [
                    { id: 8, text: "Affenpinscher" },
                    { id: 9, text: "Afghan Hound" },
                    { id: 10, text: "Airedale Terrier" },
                    { id: 11, text: "Akita Inu" }
                ]
            },
            { 
                id: 4,
                text: "Cow"
            }
        ]
    },
    { 
        id: 12,
        parentId: 0,
        text: "Birds",
        items: [
            { id: 13, text: "Akekee" },
            { id: 14, text: "Arizona Woodpecker" },
            { id: 15, text: "Black-chinned Sparrow" }
        ]
    }
];
var treeViewOptions = {
    dataSource: treeViewData
}

You can assign the required field name to the itemsExpr option to specify another field used to hold nested items.

JavaScript
var treeViewOptions = {
    itemsExpr: 'children',
    dataSource: [
    {
        id: 1,
        text: "Animals",
        children:[
            . . .
        ]
    }
}

Use the data source with plain structure

The dxTreeView widget can also use an array that has a plain structure. Assign 'plane' to the dataStructure option to use a plain array as the data source. In this case, each item should contain the parentId field, which holds the key value of the parent item.

JavaScript
var treeViewData = [
    { id: 0, parentId: -1, text: "Animals" },
    { id: 1, parentId: 0, text: "Cat" },
    { id: 2, parentId: 0, text: "Dog" },
    { id: 3, parentId: 0, text: "Cow" },
    { id: 4, parentId: 1, text: "Abyssinian" },
    { id: 5, parentId: 1, text: "Aegean cat" },
    { id: 6, parentId: 1, text: "Australian Mist" },
    { id: 7, parentId: 2, text: "Affenpinscher" },
    { id: 8, parentId: 2, text: "Afghan Hound" },
    { id: 9, parentId: 2, text: "Airedale Terrier" },
    { id: 10, parentId: 2, text: "Akita Inu" },
    { id: 11, parentId: -1, text: "Birds" },
    { id: 12, parentId: 11, text: "Akekee" },
    { id: 13, parentId: 11, text: "Arizona Woodpecker" },
    { id: 14, parentId: 11, text: "Black-chinned Sparrow" }
];
var treeViewOptions = {
    dataSource: treeViewData,
    dataStructure: 'plain'
}

You can use the parentIdExpr option to specify another field for holding the parent key.

JavaScript
var treeViewOptions = {
    parentIdExpr: 'parent',
    dataSource: [
        { id: 1, parent: 0, text: "Animals"},
        { id: 2, parent: 1, text: "Cat" },
        { id: 3, parent: 1, text: "Dog" },
        . . .
    ]
}

Use the widget in Virtual mode

If the data source associated with the widget has a plain structure, you can enable the Virtual mode, which can significantly increase performance when working with a large data source. If Virtual mode is enabled, the widget initially loads only root items, while child items are loaded when their parent is being expanded. To enable Virtual mode, set the virtualModeEnabled option to true.

If Virtual mode is enabled, the widget requires you to specify the parentId value of root items using the rootValue option. The default value of the option is 0.

JavaScript
var treeViewOptions: {
    dataSource: new DevExpress.data.DataSource(treeViewData),
    dataStructure: 'plain',
    rootValue: -1,
    virtualModeEnabled: true
}
NOTE
Virtual mode also requires the widget to access data using a DataSource instance able to filter data by the parentId value.

Specify whether or not an item is expanded

Widget items can contain the expanded field, which specifies whether an item is displayed expanded (true) or collapsed (false).

JavaScript
var treeViewData = [
    { id: 1, parentId: 0, text: "Animals", expanded: false },
    { id: 2, parentId: 1, text: "Cat" },
    { id: 3, parentId: 1, text: "Dog" },
    { id: 4, parentId: 1, text: "Cow" },
    . . .
]

You can assign the required field name to the expandedExpr option to specify another field used to determine the expansion state of an item.

JavaScript
var treeViewOptions = {
    expandedExpr: 'showExpanded',
    dataSource: [
        { id: 1, parentId: 0, text: "Animals", showExpanded: false },
        { id: 2, parentId: 1, text: "Cat" },
        { id: 3, parentId: 1, text: "Dog" },
        . . .
    ]
}

Use the expandedItems option to access the list of expanded items.

You can also expand and collapse items at runtime using the expandItem(itemElement) and collapseItem(itemElement) methods respectively.

Select widget items

If the showCheckBoxes option is set to true, the widget displays a check box for each tree item. In this case, the selected field of a data item specifies whether the item is displayed selected or not.

JavaScript
var treeViewOptions = {
    showCheckBoxes: true,
    dataSource: [
        { id: 1, parentId: 0, text: "Animals" },
        { id: 2, parentId: 1, text: "Cat", selected: true },
        { id: 3, parentId: 1, text: "Dog" },
        { id: 4, parentId: 1, text: "Cow" },
        . . .
    ]
}

To specify another field determining the selection state of an item, use the selectedExpr option.

JavaScript
var treeViewOptions = {
    showCheckBoxes: true,
    selectedExpr: 'showSelected',
    dataSource: [
        { id: 1, parentId: 0, text: "Animals" },
        { id: 2, parentId: 1, text: "Cat", showSelected: true },
        { id: 3, parentId: 1, text: "Dog" },
        . . .
    ]
}

You can assign true to the selectAllEnabled option to display a check box that selects or unselects all tree items. The check box text is specified by the selectAllText option.

JavaScript
var treeViewOptions = {
    selectAllEnabled: true,
    selectAllText: 'Select all items'
}

Use the selectedItems option to access the list of selected items.

Filter Items

The dxTreeView widget includes the searchValue option, which enables you to filter its items. If this option holds a non-empty string, the widget displays only items containing the specified string and their parents.

To implement a search box for the tree view, create the dxTextBox widget and pass its value to the searchValue option of the tree view each time the text box value has changed.

HTML
<div id="searchBox"></div>
<div id="myTreeView"></div>
JavaScript
$("#searchBox").dxTextBox({
    onValueChanged: function(e){
        $("#myTreeView").dxTreeView("instance").option("searchValue", e.value);
    }
})
$("#myTextBox").dxTextBox({
    dataSource: [. . .]
});
AngularJS Approach
HTML
<div ng-controller="demoController">
    <div dx-text-box="{
         bindingOptions: {
            value: 'searchText'
         }
    }"></div>
    <div dx-tree-view="{
        dataSource: treeViewData,
        bindingOptions: {
            searchValue: 'searchText'
        }
    }"></div>
</div>
JavaScript
myApp.controller("demoController", function ($scope) {
    $scope.searchText = "";
    $scope.treeViewData = [. . .];
});
Knockout Approach
HTML
<div data-bind="dxTextBox: {
    value: searchText
}"></div>
<div dataBind="dxTreeView: {
    dataSource: treeViewData,
    searchValue: searchText
}"></div>
JavaScript
var viewModel = {
    searchText: ko.observable(""),
    treeViewData: [. . .]
}
ko.applyBindings(viewModel);

Keyboard support

An end-user can use the following keys to interact with the widget.

  • Left arrow
    Collapses the parent item.

  • Right arrow
    Expands the current item.

  • Up/down arrow
    Highlights the previous/next visible item.

  • Home/End Highlights the first/last item.

  • Shift + Up/Down arrow
    Extends selection up/down by one node.

  • Shift + Home
    Extends selection up to the first node.

  • Shift + Home
    Extends selection down to the last node.

  • *(asterisk)
    Expands all nodes.

  • -(minus)
    Collapses all nodes.

  • Enter (Space) Selects the focused item.