dxList

The List 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.

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.

See Also

• Customize Item Template
• Customize Widget Element Appearance
• Customize Widget Element Appearance - MVVM Approach

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

The default group template supports the following array structure.

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.

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

You can render group elements using a custom rendering function. For this purpose, assign the required function to the groupTemplate option. Note that the function should not return a value.

The List widget passes the following arguments to the group rendering function.

• groupData
  The group object to be rendered.
• groupIndex
  The index of the group header to be rendered.
• groupElement
  An HTML element of the group header to be rendered.

$("#listContainer").dxList({
        dataSource: listData,
        groupTemplate: function(groupData, groupIndex, groupElement){
            groupElement.empty();
            groupElement.append("<h1 style="\color:red\">" + groupData.groupName + "</h1>");
        }
    });
});

To specify a group header structure in MVVM approach, do the following.

1. Create an HTML container element within the widget and apply the data-options attribute set to dxTemplate.

   AngularJS Approach

   HTML

   <div dx-list="{ dataSource: listData }" dx-item-alias="itemObj">
       <div data-options="dxTemplate:{ name:'item' }">
       </div>
   </div>

   Knockout Approach

   HTML

   <div data-bind="dxList:{ dataSource: listData, grouped: true }">
       <div data-options="dxTemplate:{name:'group'}">
       </div>
   </div>

2. Insert the required structure in the newly added dxTemplate element.

   AngularJS Approach

   HTML

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

   Knockout Approach

   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.

   AngularJS Approach

   HTML

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

   Knockout Approach

   HTML

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

In addition, the widget supports group collapsing. Assign true to the collapsibleGroups option to enable the feature. In this case, the down arrow is displayed to the right of a group header. An end-user can collapse or expand a group by clicking the group header.

var listOptions = {
    dataSource: listData,
    grouped: true,
    collapsibleGroups: true
}

You can also collapse and expand groups programmatically using the collapseGroup(groupIndex) and expandGroup(groupIndex) methods respectively.

// Get widget instance
. . .
collapseListGroup = function(index){
    listInstance.collapseGroup(index);
}

expandListGroup = function(index){
    listInstance.expandGroup(index);
}

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

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.

• Page load modes

  If the data source associated with the widget loads data by pages, the List widget can automatically add a new page to the end of the list each time the list is scrolled to the bottom or when a user clicks the "next" button, depending on the pageLoadMode option value.

  JavaScript

  //load next page when the list is scrolled to the bottom
  var listOptions = {
      dataSource: listData,
      pageLoadMode: "scrollBottom"
  };
  
  //load next page when the next button clicked
  var listOptions = {
      dataSource: listData,
      pageLoadMode: "nextButton"
  };

• 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
  };

The List widget allows an end-user to select single or multiple items depending on the selectionMode option value, which supports the "none", "single", "multiple" and "all" values.

var listOptions = {
    dataSource: listData,
    selectionMode: "multiple"
};

The showSelectionControls option enables you to display check boxes or radio buttons at items if the selectionMode value is "multiple" or "single" respectively.

var listOptions = {
    dataSource: listData,
    selectionMode: "multiple",
    showSelectionControls: true
};

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

The widget allows you to handle events that occurred when an item is selected or unselected. Declare the appropriate handling function and assign it to the onSelectionChanged configuration option.

var selectionChanged = function(e) {
    //Process item selection
};

var listOptions = {
    dataSource: listData,
    selectionMode: "single",
    onSelectionChanged: selectionChanged
};

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

The List widget supports the reordering of items by an end-user. Set the allowItemReordering 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.

var listOptions = {
    dataSource: listData,
    allowItemReordering: true
};

After an item is moved to another position, the widget fires the itemReordered event. To handle this event, pass a function to the onItemReordered option or subscribe the itemReordered event.

See Also

• Handle Events - jQuery
• Handle Events - AngularJS
• Handle Events - Knockout

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

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

• "context"
  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 itemDeleteMode option is set to "context".

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

var listOptions = {
    dataSource: listData,
    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.

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

The List widget allows an end-user to delete items. To enable deletion, set the allowItemDeleting option to true.

var listOptions = {
    dataSource: listData,
    allowItemDeleting: true
}

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

• "static"
  The Delete button is always displayed by each item. When an end-user clicks the Delete button, the corresponding item is deleted immediately without confirmation.

• "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 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 by just swiping it.

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

var listOptions = {
    dataSource: listData,
    allowItemDeletion: true,
    itemDeleteMode: "toggle"
}