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 myViewModel = {
    myDataSource: new DevExpress.data.DataSource("http://www.example.com/dataservices/jsondata"),
};
ko.applyBindings(myViewModel);
HTML
<div data-bind="dxList: { dataSource: myDataSource }"></div>

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

Handle Item Events

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

  • itemClickAction - specifies the function called on an item click
  • itemHoldAction - specifies the function called on an item held during a specified time span
  • itemSelectAction - specifies the function called when an item is selected
JavaScript
var myViewModel = {
    itemClickHandler: function() {
        alert("List item is clicked");
    }
    itemHoldHandler: function() {
        alert("List item is held");
    }
    itemSelectHandler: function() {
        alert("List item is selected");
    }
};
ko.applyBindings(myViewModel);
HTML
<div data-bind="dxList: { 
    itemClickAction: itemClickHandler,
    itemHoldAction: itemHoldHandler,
    itemSelectAction: itemSelectHandler
}"></div>

Customize Widget Item Appearance

In addition, collection container widgets provide you with a wide array of item appearance customization capabilities. In the most simple case, a collection container widget item has a simple textual presentation. But 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 an HTML template for them. In this topic, you will learn how to provide an item template for a widget.

Use one of the following techniques.

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.
  • 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, a default item template contains the text binding associated with the current array value.

Customize a Default Template

You can customize an item element after it has been rendered. For this purpose, assign a function to the itemRenderedAction option. In this function, use the itemData field of the object passed as a parameter to access an object representing the widget item being rendered. To access the HTML element representing the rendered item, use the itemElement field of the parameter object.

Implement a Custom Template

If a default item template is not appropriate for your task and customization of a default render result is not enough, implement a custom item template based on custom data source fields. Use the jQuery or Knockout approach to specify the structure of the HTML element representing a widget item.

The examples below imply that the array passed to the dataSource option of the widget has the following structure.

JavaScript
tileViewData = [
    {
        name: 'Alabama',
        area: 135765,
        population: 4822023,
        capital: 'Montgomery'
    },
    {
        name: 'Alaska',
        area: 1717854,
        population: 731449,
        capital: 'Juneau'
    },
    ...
];
  • jQuery Approach

    To specify the structure of a rendered item element using jQuery, widgets with item collections contain the itemRender configuration option. The function assigned to this option is called each time a widget item is rendered. It should have the following input parameters.

    • itemData - an object representing the rendered item. (If you assigned an array of objects to the widget's dataSource configuration option, this parameter will contain the array element representing the rendered item.)
    • itemIndex - an index of the rendered item.
    • itemElement - a container element containing the rendered item.

    The following example illustrates a function for rendering items of a dxTileView widget.

    JavaScript
    itemRenderer = new function(itemData, itemIndex, itemElement){
    var result = "<h1>" + itemData.name + "</h1>";
        result += "<p>Area: <i>" + itemData.area + "</i> km2</p>";
        result += "<p>Population: <i>" + itemData.population + "</i></p>";
        result += "<p>Capital: <i>" + itemData.capital + "</i></p>";
        return result;
    };

    Assign the function to the widget's itemRender configuration option.

    JavaScript
    $(function(){
    $("#tileViewContainer").dxTileView({ 
            dataSource: tileViewData, 
            itemRender: itemRenderer
        });
    });

    In addition to the itemRender option, some widgets expose additional configuration options that are similar to the itemRender option but return a template for another part of the widget. For instance, if you use the dxList widget to display a grouped list, you can specify the structure of elements representing group header items in the same way as described above. In this case, the function rendering group header items should be assigned to the groupRender option of the widget. For more information, see the dxList widget description.

  • Knockout Approach

    To specify the widget item structure using the Knockout approach, create an HTML container element within the widget and apply the data-options attribute set to dxTemplate.

    HTML
    <div data-bind="dxTileView:{dataSource: tileViewData}">
        <div data-options="dxTemplate:{name:'item'}">
        </div>
    </div>

    Insert the required structure in the newly added dxTemplate element.

    HTML
    <div data-bind="dxTileView:{dataSource: tileViewData}">
        <div data-options="dxTemplate:{name:'item'}">
            <h1 data-bind="text:name"></h1>
            <p>Area: <i data-bind="text:area"></i> km2</p>
            <p>Population: <i data-bind="text:population"></i></p>
            <p>Capital: <i data-bind="text:capital"></i></p>
        </div>
    </div>

    The default name of the template element is "item". If you use a different template name, assign it to the itemTemplate configuration option of the widget.

    HTML
    <div data-bind="dxTileView:{ dataSource: tileViewData, itemTemplate:'myItem' }">
        <div data-options="dxTemplate:{ name:'myItem' }">
            ...
        </div>
    </div>
  • Angular Approach

    The angular approach to specifying the widget item structure is similar to the Knockout approach. Create an HTML container element within the widget and apply the data-options attribute set to dxTemplate.

    HTML
    <div dx-tile-view="{ dataSource: tileViewData }">
        <div data-options="dxTemplate:{ name:'item' }">
        </div>
    </div>

    Insert the required structure in the newly added dxTemplate element.

    HTML
    <div dx-tile-view="{ dataSource: tileViewData }">
        <div data-options="dxTemplate:{ name:'item' }">
            <h1>{{name}}</h1>
            <p>Area: <i>{{area}}</i> km2</p>
            <p>Population: <i>{{population}}</i></p>
            <p>Capital: <i>{{capital}}></i></p>
        </div>
    </div>

    The default name of the template element is "item". If you use a different template name, assign it to the itemTemplate configuration option of the widget.

    HTML
    <div dx-tile-view="{ dataSource: tileViewData, itemTemplate:'myItem' }">
        <div data-options="dxTemplate:{ name:'myItem' }">
            ...
        </div>
    </div>

    In addition to the itemTemplate option, some widgets expose additional configuration options that are similar to the itemTemplate option but specify a template for another part of the widget. For instance, you can specify a template for group header items of the dxList widget that displays a grouped list. Create a template element as shown above. The default name of the group header item template is "group". If you specified a different name, assign it to the widget's groupTemplate configuration option. For more information, see the widget description.

Provide Several Custom Templates

You may have several templates defined within a widget. To apply the required one in a specific context, assign a function to the widget's itemTemplate option. The return value of this function must be a string representing the name of the required template.

Provide a Common Item Template

When you have several widgets with item collections, you may need to define a common custom item template for them. For this purpose, factor out a template into a separate element, as demonstrated below.

HTML
<script id="person-template">
    <h3 data-bind="text: name"></h3>
    <p>Address: <span data-bind="text: address"></span></p>
</script>

To set the common template as an item template for a widget, assign one of the following values to the widget's itemTemplate option.

  • Assign a jQuery object representing the template's container.
  • Assign a DOM Node representing the template's container.
  • Assign a function that returns the jQuery object or a DOM Node representing the template's container.

Provide a Custom Item Template

You can provide a custom template for a certain item(s) specifically. For this purpose, introduce a template within the widget element or factor out the template into a separate element. To set the required template for a widget item, specify the template field within the data source object that represents this item.

JavaScript
tileViewData = [
    {
        name: 'Alabama',
        area: 135765,
        population: 4822023,
        capital: 'Montgomery',
        //template to this certain item
        template: 'specific'
    },
    {
        name: 'Alaska',
        area: 1717854,
        population: 731449,
        capital: 'Juneau'
    },
    ...
];
HTML
<div data-bind="dxTileView:{dataSource: tileViewData, itemTemplate:'myItem'}">
    <div data-options="dxTemplate:{name:'myItem'}">
        ...
    </div>
    <div data-options="dxTemplate:{name:'specific'}">
        ...
    </div>
</div>

List of Collection Container Widgets

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

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.

The widget is a set of vertically arranged buttons displayed within a panel at the bottom of the view by default. The set of buttons is specified by the dataSource option. To display the widget as a popover window, assign true to the usePopover option. In this case, you should also specify the target element for the popover using the target option.

The action sheet is mostly hidden, and is only shown when an end-user should choose an action. To control widget visibility, use its 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
showActionSheet = function() {
    var actionSheet = $("#actionSheetContainer").dxActionSheet("instance");
    actionSheet.toggle(true);
}
hideActionSheet = function() {
    var actionSheet = $("#actionSheetContainer").dxActionSheet("instance");
    actionSheet.toggle(false);
}

If you use the Knockout approach, you can pass an observable variable to the visible option to show or hide the widget depending on the variable value.

JavaScript
var actionSheetVisible = ko.observable(false);
var showActionSheet = function() {
    actionSheetVisible(true);
}
var hideActionSheet = function() {
    actionSheetVisible(false);
}

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 action sheet title is specified using the title option.

dxAutocomplete

The dxAutocomplete widget is an editor widget supporting collection container functionality. For more information on this widget, refer to the Editor widgets guide.

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.

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

dxDropDownMenu

The dxDropDownMenu widget is UI element that displays a drop-down menu when clicked. The menu items are specified using the dataSource option.

JavaScript
var dropDownMenuItems = [
    { text: "Copy" },
    { text: "Cut" },
    { text: "Clear" }
];
var dropDownMenuOptions = {
    dataSource: dropDownMenuItems
}

The widget can be used separately or as an item of the dxToolbar widget. If you use the dxDropDownMenu widget separately, it looks like a button. The following options enable you to specify button appearance. Each of these options maps the corresponding option of the underlying dxButton widget. The mapped button options are shown in parentheses.

JavaScript
var dropDownMenuOptions = {
    dataSource: dropDownMenuItems,
    buttonText: "Show menu",
    buttonIcon: "menu",
    buttonClickAction: function() {
        alert("The button is clicked");
    }
}

The drop-down menu can be displayed as a popover. Assign true to the usePopover option to enable this feature.

JavaScript
var dropDownMenuOptions = {
    dataSource: dropDownMenuItems,
    usePopover: true
}

If you need to use the dxDropDownMenu widget as a toolbar item, you should add the appropriate item to the dxToolbar data source. This item should contain the widget property set to "dropDownMenu". The options property accepts the dxDropDownMenu configuration object.

JavaScript
var toolbarData = [
    . . . ,
    {
        widget: 'dropDownMenu',
        options: {
            items: [ "Copy", "Cut", "Clear" ],
            itemClickAction: menuItemClicked
        }
    },
    . . .
]

For more information on using the dxDropDownMenu widget as a toolbar item, refer to the dxToolbar widget guide.

dxGallery

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

dxList

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

dxLookup

The dxLookup widget allows an end-user to select predefined values from a lookup window. Refer to the dxLookup guide for more information.

dxMenu

The dxMenu widget displays a single-level or multi-level menu that performs an action when an item is clicked.

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

dxMultiView

A widget used to display a view and to switch between several views.

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. The widget is often used together with the dxTabs widget to display tab contents.

In this case, the dxTabs and dxMultiView widgets use a common data source. A data source item should include the text property whose value is displayed on a tab. You can use the map option of the DataSource object to add this property to all the items of the initial array.

JavaScript
var multiViewData = new DevExpress.data.DataSource({
    store: [
        {
            title: "Personal Data",
            data: {
                firstName: "John",
                lastName: "Smith",
                birthYear: 1986,
            }
        },
        {
            title: "Contacts",
            data: {
                phone: "(555)555-5555",
                email: "John.Smith@example.com",
            }
        },
        {
            title: "Address",
            data: {
                state: "CA",
                city: "San Francisco",
                street: "Stanford Ave",
            }
        }
    ],
    //Adds the 'text' property to each data item
    map: function(itemData) {
        itemData.text = itemData.title;
        return itemData;
    }
});
var dxTabsOptions = {
    dataSource: multiViewData
}
var dxMultiViewOptions = {
    dataSource: multiViewData
}

To switch views when an end-user clicks a tab, synchronize the selected item indexes of the dxTabs and dxMultiView widgets. You can use one of the following approaches.

  • jQuery Approach

    Handle the itemSelectAction event of the dxTabs widget and update the selectedItem option of the dxMultiView widget according to the current selectedItem option value of the dxTabs widget.

    JavaScript
    var dxTabsOptions = {
        dataSource: multiViewData,
        itemSelectAction: function(itemData) {
            var selectedIndex = $("#tabsContainer").dxTabs("instance").option("selectedIndex");
            $("#multiViewContainer").dxMultiView("instance").option("selectedIndex", selectedIndex);
        }
    }
    var dxMultiViewOptions = {
        dataSource: multiViewData
    }
  • Knockout Approach

    Declare an observable variable and pass it to the selectedIndex option of both widgets.

    JavaScript
    var index = ko.observable(0);
    var dxTabsOptions = {
        dataSource: multiViewData,
        selectedIndex: index
    }
    var dxMultiViewOptions = {
        dataSource: multiViewData,
        selectedIndex: index
    }
    HTML
    <div data-bind="dxTabs: dxTabsOptions"></div>
    <div data-bind="dxMultiView: dxMultiViewOptions"></div>
  • Angular Approach

    Declare the index property within the $scope object and associate the selectedIndex option of both widgets with this property. To associate a $scope object property with the selectedIndex option of a widget, provide two-way binding between them as illustrated in the following example.

    JavaScript
    function Controller($scope) {
        $scope.overlayVisible = false;
    }
    var dxTabsOptions = {
        dataSource: multiViewData,
        bindingOptions: {
            'selectedIndex': 'index'
        }
    }
    var dxMultiViewOptions = {
        dataSource: multiViewData,
        bindingOptions: {
            'selectedIndex': 'index'
        }
    }
    HTML
    <div ng-controller="Controller">
        <div dx-tabs="dxTabsOptions"></div>
        <div dx-multi-view="dxMultiViewOptions"></div>
    </div>

You can also switch between views by swiping. This feature is enabled by default. To disable it, assign false to the swipeEnabled option.

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

The dxMultiView widget can display the specified 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
}

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.

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 one of the following properties.

  • icon
    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" }
    ]
  • iconSrc
    The iconSrc property enables you to use a custom image as a NavBar icon.

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

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" }
];

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.

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.

    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.

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. Although dxPivot was created based on the native WindowsPhone8 Pivot widget, it can be used on any platform.

The pivot header is specified by the title property of the corresponding item object.

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"]
            })
        }
    ]
}

dxRadioGroup

The dxRadioGroup widget contains a set of radio buttons and enables an end-user to select one of them. The widget creates a radio button for each item of the data source specified using the dataSource option. An item object should contain the text property that specifies the text displayed by the corresponding radio button.

JavaScript
var colors = [
    { text: "red", value: "#FF0000" },
    { text: "green", value: "#00FF00" },
    { text: "blue", value: "#0000FF" }
]
var radioGroupOptions = {
    dataSource: colors
}

You can access the selected value using the value option. The valueExpr option specifies the item object property whose value is accessed using the value option. You can pass "this" to the valueExpr option to access the entire item object.

var radioGroupOptions = {
    dataSource: colors,
    valueExpr: 'value'
}

The layout option enables you to specify whether the widget arranges radio buttons vertically or horizontally.

var radioGroupOptions = {
    dataSource: colors,
    layout: 'horizontal'
}

dxSelectBox

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

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. You can specify the appearance of the currently selected item using the itemTemplate(Knockout and Angular approaches) or itemRender(jQuery approach) option.

A menu item's appearance is specified in the same manner as a selected item's appearance, but you should use the menuItemTemplate and menuItemRender options to specify the menu item template name (Knockout and Angular approaches) or a function rendering a menu item (jQuery approach) respectively.

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>

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.

dxTabs

The dxTabs widget is a tab strip used to switch between pages.

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 one of the following properties.

  • icon
    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" }
    ]
  • iconSrc
    The iconSrc property enables you to use a custom image as a tab icon.

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

The widget is often used together with the dxMultiView widget used to display current tab contents.

In this case, the dxTabs and dxMultiView widgets use a common data source. A data source item should include the text property whose value is displayed on a tab. You can use the map option of the DataSource object to add this property to all items of the initial array.

JavaScript
var multiViewData = new DevExpress.data.DataSource({
    store: [
        {
            title: "Personal Data",
            data: {
                firstName: "John",
                lastName: "Smith",
                birthYear: 1986,
            }
        },
        {
            title: "Contacts",
            data: {
                phone: "(555)555-5555",
                email: "John.Smith@example.com",
            }
        },
        {
            title: "Address",
            data: {
                state: "CA",
                city: "San Francisco",
                street: "Stanford Ave",
            }
        }
    ],
    //Adds the 'text' property to each data item
    map: function(itemData) {
        itemData.text = itemData.title;
        return itemData;
    }
});
var dxTabsOptions = {
    dataSource: multiViewData
}
var dxMultiViewOptions = {
    dataSource: multiViewData
}

To switch views when an end-user clicks a tab, synchronize the selected item indexes of the dxTabs and dxMultiView widgets. You can use one of the following approaches.

  • jQuery Approach

    Handle the itemSelectAction event of the dxTabs widget and update the selectedItem option of the dxMultiView widget according to the current selectedItem option value of the dxTabs widget.

    JavaScript
    var dxTabsOptions = {
        dataSource: multiViewData,
        itemSelectAction: function(itemData) {
            var selectedIndex = $("#tabsContainer").dxTabs("instance").option("selectedIndex");
            $("#multiViewContainer").dxMultiView("instance").option("selectedIndex", selectedIndex);
        }
    }
    var dxMultiViewOptions = {
        dataSource: multiViewData
    }
  • Knockout Approach

    Declare an observable variable and pass it to the selectedIndex option of both widgets.

    JavaScript
    var index = ko.observable(0);
    var dxTabsOptions = {
        dataSource: multiViewData,
        selectedIndex: index
    }
    var dxMultiViewOptions = {
        dataSource: multiViewData,
        selectedIndex: index
    }
    HTML
    <div data-bind="dxTabs: dxTabsOptions"></div>
    <div data-bind="dxMultiView: dxMultiViewOptions"></div>
  • Angular Approach

    Declare the index property within the $scope object and associate the selectedIndex option of both widgets with this property. To associate a $scope object property with the selectedIndex option of a widget, provide two-way binding between them as illustrated in the following example.

    JavaScript
    function Controller($scope) {
        $scope.overlayVisible = false;
    }
    var dxTabsOptions = {
        dataSource: multiViewData,
        bindingOptions: {
            'selectedIndex': 'index'
        }
    }
    var dxMultiViewOptions = {
        dataSource: multiViewData,
        bindingOptions: {
            'selectedIndex': 'index'
        }
    }
    HTML
    <div ng-controller="Controller">
        <div dx-tabs="dxTabsOptions"></div>
        <div dx-multi-view="dxMultiViewOptions"></div>
    </div>

dxTileView

The dxTileView widget displays data items as tiles.

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
}

The distance between tiles is specified by the itemMargin option.

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

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
}

The height of the scrollable area is fixed and specified by the height option. The width of the scrollable area is automatically calculated depending on the item count.

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.

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

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.

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', 'center' or 'menu'. When 'menu' is set, the toolbar item is added to the toolbar's overflow menu. This menu is displayed by the dxDropDownMenu, dxPopover, dxActionSheet or 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 or menuItemRender option.

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',
            clickAction: buttonClickHandler
        } 
    },
    {
        location: 'after', widget: 'dropDownMenu', options: {
            items: ["Add", "Change", "Remove"],
            itemClickAction: menuItemClickHandler
        }
    },
    { location: 'center', text: 'Products' }
];
var toolbarOptions = {
    dataSource: toolbarItems
}

When configuring the dxToolbar widget, use the renderAs option to specify the location of this widget in a view HTML template. 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'
}