Default Item Template
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
Data Shaping
Usually the DataSource instance used by the List widget to access data supports data shaping (sorting, filtering, grouping, etc.). The List widget includes special features for the following kinds of data shaping.
Grouping
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.
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>
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); }
Paging
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.
JavaScriptvar listOptions = { dataSource: listData, pullRefreshEnabled: true };
End User Interaction With Items
The List widget enables an end user to perform the following operations on items.
Select Items
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.
Handle Selection Events
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.
Reorder Items
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
Item Context Menu
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 } } ];
Delete Items
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" }
Scrolling
If list content height exceeds the widget height, an end user can scroll content vertically to view the required item.
Scrolling is enabled by default. However, you can set the enableScrolling option to false to disable it.
If scrolling is enabled, you can specify whether or not a user can scroll the widget by content and by a scroll bar thumb using the scrollByContent and scrollByThumb options respectively.
var listOptions: { . . . scrollByThumb: true, scrollByContent: true }
The List widget also enables you to scroll its content programmatically using the scrollBy(distance), scrollTo(location), scrollToItem(itemElement), scrollToItem(itemIndex) or scrollTop() method.
// Get widget instance . . . listInstance.scrollToItem(15);
In addition, you can execute a custom action once the list has been scrolled. Handle the scroll event or pass the required function to the onScroll option.
See Also
Indicate Data Loading
The List widget can display the loading panel when it is loading data. Set the indicateLoading option to true to enable this feature.
var listOptions = { dataSource: new DevExpress.data.DataSource(myDataStore), indicateLoading: true }
Keyboard Support
An end-user can use the following keys to interact with the widget.
Up/down arrow
Highlight the previous/next item.Page up/page down
Highlights the item located a page above/below the current one.Home/End
Highlight the first/last element.Enter (Space)
Select the current element.Delete
Remove the current item. Available if the allowItemDeleting option is set to true.Shift + up/down arrow
Transpose the current and previous/next items. Available if the allowItemReordering option is set to true.