dxList

The dxList widget displays specified data source items as a scrollable list.

Default Item Template

The dxList widget displays items stored in a data source specified using the dataSource configuration option. In a simple case, the widget uses the default template to render items. This template represents a list item as a <div> element containing the text associated with the corresponding data item. The default item template can be used if a data source item is a string value, or an object containing the text field, which contains the text associated with this item.

JavaScript
var listData=[
    { text: "item1" },
    { text: "item2" },
    "item3",
    "item4"
];

If data item objects have another structure, you should specify the custom template used to render items.

Data Shaping

Usually the DataSource instance used by the dxList widget to access data supports data shaping (sorting, filtering, grouping, etc.). The dxList widget includes special features for the following kinds of data shaping.

Grouping

The dxList widget can display data source items as a grouped list. In this case, items of each group are displayed under the group caption. Set the grouped option to true to display a grouped list.

The default group template supports the following array structure.

JavaScript
var listData = [
    {
        key: "group1 caption",
        items: [
            { text: "item1" },
            { text: "item2" },
            { text: "item3" }
        ]
    },
    {
        key: "group2 caption",
        items: [
            { text: "item1" },
            { text: "item2" },
            { text: "item3" }
        ]
    },
    {
        key: "group3 caption",
        items: [
            { text: "item1" },
            { text: "item2" },
            { text: "item3" }
        ]
    }
];

The key property value is displayed as a group header. Group items specified by the items array are displayed below.

If a group header is specified by a different property, you should specify a custom group template in the same way as a custom item template. Use the jQuery, Knockout or Angular approach to specify a custom group template.

JavaScript
var listData = [
    {
        groupName: "A",
        items: [
            { text: "Alabama" },
            { text: "Alaska" },
            { text: "Arizona" },
            { text: "Arkanzas" }
        ]
    },
    {
        groupName: "C",
        items: [
            { text: "California" },
            { text: "Colorado" },
            { text: "Connecticut" }
        ]
    },
    . . .
];
  • jQuery Approach

    To specify the structure of a rendered group using jQuery, use the groupRender configuration option. The function assigned to this option is called each time a widget group is rendered. It should have the following input parameters.

    • groupData - an object representing the rendered group
    • groupIndex - an index of the rendered group
    • groupElement - a container element containing the rendered group caption

    The following example illustrates a group header rendering function that takes the value of the groupName data source item property as a group caption.

    JavaScript
    groupRenderer = new function(groupData, groupIndex, groupElement) {
        return "<h1 style=\"color: red\">" + groupData.groupName + "...</h1>";
    };

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

    JavaScript
    $(function(){
    $("#listContainer").dxList({
            dataSource: listData,
            groupRender: groupRenderer
        });
    });
  • Knockout Approach

    To specify a group header 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="dxList:{ dataSource: listData, grouped: true }">
        <div data-options="dxTemplate:{name:'group'}">
        </div>
    </div>

    Insert the required structure in the newly added dxTemplate element.

    HTML
    <div data-bind="dxList:{ dataSource: listData, grouped: true }">
        <div data-options="dxTemplate:{ name:'group' }">
            <h1 style="color:red;"><span data-bind="text: groupName"></span>...</h1>
        </div>
    </div>

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

    HTML
    <div data-bind="dxList:{ dataSource: listData, groupTemplate:'myGroup' }">
        <div data-options="dxTemplate:{ name:'myGroup' }">
            ...
        </div>
    </div>
  • Angular Approach

    The angular approach to specifying group header 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-list="{ dataSource: listData }">
        <div data-options="dxTemplate:{ name:'item' }">
        </div>
    </div>

    Insert the required structure in the newly added dxTemplate element.

    HTML
    <div dx-list="{ dataSource: listData }">
        <div data-options="dxTemplate:{ name:'item' }">
            <h1 style="color:red;">{{groupName}}...</h1>
        </div>
    </div>

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

    HTML
    <div dx-list="{ dataSource: listData, groupTemplate:'myGroup' }">
        <div data-options="dxTemplate:{ name:'myGroup' }">
            ...
        </div>
    </div>

Paging

The dxList widget can display data source items by pages. You can modify paging options using the DataSource instance associated with the widget.

JavaScript
var listData = new DevExpress.data.DataSource({
    store: [ . . . ], //Specifies data associated with the DataSource instance
    paginate: true, //Specifies whether or not DataSource loads data by pages
    pageSize: 10 //Specifies the number of items contained in a single page
});
var listOptions = {
    dataSource: listData
};

The widget includes the following means used to simplify working with paged data.

  • Automatic paging

    If the data source associated with the widget loads data by pages, the dxList widget can automatically add a new page to the end of the list each time the list is scrolled to the bottom. To enable automatic paging, set the autoPagingEnabled option to true.

    JavaScript
    var listOptions = {
        dataSource: listData,
        autoPagingEnabled: true
    };
  • The Next button

    An end-user can also load the next page by clicking the Next button displayed at the bottom of the list. Button availability is specified by the showNextButton option.

    JavaScript
    var listOptions = {
        dataSource: listData,
        showNextButton: true
    };
  • Refreshing the list

    If the list data is displayed by pages, an end-user can refresh the list (clear and load the first page) by the "Pull down to refresh" gesture. You can specify feature availability using the pullRefreshEnabled option.

    JavaScript
    var listOptions = {
        dataSource: listData,
        pullRefreshEnabled: true
    };

Edit Mode

The dxList widget supports Edit mode. Edit mode enables an end-user to select list items or delete an item. You can enable the edit mode using the editEnabled option. The edit mode enables you to perform the following operations. The editConfig option takes on the edit mode configuration object.

JavaScript
var listOptions = {
    dataSource: listData,
    editEnabled: true,
    editConfig: {
        //The edit mode configuration options
    }
}

Select Items

The dxList widget allows an end-user to select single or multiple items depending on the selectionMode option value. If selection mode is set to "multi", the widget allows multi-selection and displays check boxes at the left of each item, otherwise it supports only single item selection and displays radio buttons at the left of each item.

To enable selection mode, assign true to the editConfig.selectionEnabled option.

JavaScript
var listOptions = {
    dataSource: listData,
    selectionMode: "multi",
    editConfig: {
        selectionEnabled: true
    }
};

You can also specify the way the widget items are selected or unselected using the editConfig.selectionType option, which can take on one of the following values.

  • "item"
    A list item is selected/unselected when an entire item element including the check box or radio button is clicked (touched).

  • "control"
    A list item is selected/unselected when only the check box or radio button associated with the item is clicked (touched).

JavaScript
var listOptions = {
    dataSource: listData,
    selectionMode: "multi",
    edtiEnabled: true,
    editConfig: {
        selectionEnabled: true,
        selctionType: "item"
    }
};

You can access the list of the selected items using the selectedItems option. If no items are selected, the option contains an empty array.

Handle Selection Events

The widget allows you to handle events that occurred when an item is selected or unselected. Declare the appropriate handler functions and assign them to the itemSelectAction and itemUnselectAction configuration options respectively.

JavaScript
var itemSelected = function(eventArgs) {
    //Process item selection
};
var itemSelected = function(eventArgs) {
    //Process item unselection
};

var listOptions = {
    dataSource: listData,
    editEnabled: true,
    editConfig: {
        selectionEnabled: true
    },
    itemSelectAction: itemSelected,
    itemUnselectAction: itemUnselected
};

An object passed to the handler function as an argument contains properties that enable you to access the widget instance, widget element, current viewModel, item data object and item element.

Reorder Items

The dxList widget supports the reordering of items by an end-user. Set the editConfig.reorderEnabled option to true to allow a user to reorder items. To change an item position, drag the required item by the special icon located at the right side of the item and drop it over the target position.

JavaScript
var listOptions = {
    dataSource: listData,
    editEnabled: true,
    editConfig: {
        reorderEnabled: true
    }
};

Note that the item reordering feature requires the useNativeScrolling option to be set to false in Windows Phone 8 and Android 4.0 or higher.

Item Context Menu

An end-user can call a context menu for a list item. The menu items are specified using the editConfig.menuItems option. The context menu is available if the editConfig.menuItems option includes an array containing at least one item.

The editConfig.menuType option specifies the way an end-user calls the context menu for an item. This option can take on one of the following values.

  • "hold"
    The context menu appears if a user holds the required item. In this case, the context menu may include the "Delete" item in addition to the specified items if item deletion is enabled and the deleteType option is set to "hold".

  • "slide"
    A user swipes the required item to uncover the More button, which calls the context menu.

JavaScript
var listOptions = {
    dataSource: listData,
    editEnabled: true,
    editConfig: {
        menuItems: contextMenuItems,
        menuType: "hold"
    }
};

An array passed to the menuItems option should contain objects including the following properties.

  • text
    Specifies the menu item text.

  • action
    Takes on a function called when the item is clicked (tapped). The function passed to this property has the itemElement and itemData parameters used to access the element and the data object of a list item for which the context menu is called.

JavaScript
var contextMenuItems = [
    {
        text: "Show on the map",
        action: function (itemElement, itemData) {
            //Action implementation
        }
    },
    {
        text: "Show info",
        action: function (itemElement, itemData) {
            //Action implementation
        }
    },
    {
        text: "Edit info",
        action: function (itemElement, itemData) {
            //Action implementation
        }
    }
];

Delete Items

The dxList widget allows an end-user to remove items. To enable deletion set the deleteEnabled option to true.

JavaScript
var listOptions = {
    dataSource: listData,
    editEnabled: true,
    editConfig: {
        deleteEnabled: true
    }
}

You can specify the way an end-user can delete a required item using the editConfig.deleteType option. This option can take on one of the following values.

  • "toggle"
    A user can toggle Delete button visibility by clicking the appropriate icon, located to the left of the required item.

  • "slideButton"
    The "Delete" button slides from out the screen when a user swipes the item.

  • "slideItem"
    The item slides left and uncovers the Delete button when a user swipes the item.

  • "swipe"
    A user can delete an item just swiping it.

  • "hold"
    The widget adds the Delete item to the context menu called when the list item is held.

JavaScript
var listOptions = {
    dataSource: listData,
    editEnabled: true,
    editConfig: {
        deleteEnabled: true,
        deleteType: "toggle"
    }
}