Custom List Item

SAPUI5 contains several list items that are used with the sap.m.List control to serve different standard scenarios. These are outlined in the table below, along with sap.m.ColumnListItem, which is used together with the sap.m.Table control:

If none of the predefined list items (the first seven entries in the table above) fit your scenario, you can also create your own layout by using sap.m.CustomListItem directly, or create a new control that inherits from sap.m.CustomListItem.

For more information about the different list items, refer to the corresponding API documentation in the Demo Kit.

A list item can be split into three parts, as shown in the following graphic:

The parts that are to the left and right of the dotted area are part of the ListItemBase and are used to display the selection and deletion mode, as well as different list item type indicators such as navigation, details, and counter. The Unread indicator also comes from the ListItemBase and when it is set, any unread text will be displayed in bold format.

The dotted area is the area in which the content of a list item is placed. If you are using sap.m.CustomListItem, all of the content will be placed there. The section below explains how to use sap.m.CustomListItem in more detail.

As mentioned above, you can either use sap.m.CustomListItem directly by adding any content via content aggregation, or you can create your own control that inherits from sap.m.CustomListItem if you need a more sophisticated list item featuring your own properties, styling, and complex layout. Below is an example showing how you can use the sap.m.CustomListItem together with sap.m controls.

<List headerText="Custom Content" mode="Delete" items="{path: '/ProductCollection'}" >
	<CustomListItem>
		<HBox>
			<core:Icon size="2rem" src="sap-icon://attachment-photo" class="sapUiSmallMarginBegin sapUiSmallMarginTopBottom" />
			<VBox  class="sapUiSmallMarginBegin sapUiSmallMarginTopBottom" >
				<Link text="{Name}" target="{ProductPicUrl}" press="handlePress"/>
				<Label text="{ProductId}"/>
			</VBox>
		</HBox>
	</CustomListItem>
</List>

The example above creates an attachment list item that displays an attachment title as a link, as shown in the graphic below. Clicking on the link will open the attachment. Below the attachment title, we want to display the details of the attachment, so we have used sap.m.HBox and sap.m.VBox for basic layouting. Data binding is also supported, and here it assumes that a model featuring ProductPicUrl and ProductId properties is used.

The following example shows how to use a notepad control as a reusable control in an sap.m.CustomListItem. It assumes you want to build a product list item that shows an image of the product and displays its details:

jQuery.sap.declare("my.control.ListItemContent");
sap.ui.core.Control.extend("my.control.ListItemContent", {

metadata: {
        properties : {
            "name": {type: "string", defaultValue: ""},
            "description": {type: "string", defaultValue: ""},
            "price": {type: "string", defaultValue: ""},
            "currency": {type: "string", defaultValue: ""},
            "image": {type: "string", defaultValue: ""}
        },
                events: {
            "myTap": {},
        },
    },

    init: function(){
        this._image = new sap.m.Image({src:"<myImageSrc>"}).addStyleClass("myImageCSS").setParent(this);
    },
    
    renderer: function(oRm, oControl) { 
        oRm.write("<div class='listItemCSS'");
        oRm.writeControlData(oControl);
        oRm.write(">");
            oRm.renderControl(oControl._image); 
            oRm.write("<div class='descCSS'>");
            oRm.writeEscaped(oControl.getDescription());
            oRm.write("</div>");        
                        
            oRm.write("<div class='priceCSS'>");
            oRm.writeEscaped(oControl.getPrice());
            oRm.write("</div>");

            oRm.write("<div class='curCSS'>");
            oRm.writeEscaped(oControl.getCurrency());
            oRm.write("</div>");
                            
            oRm.write("<div class='nameCSS'>");
            oRm.writeEscaped(oControl.getName());
            oRm.write("</div>");        
        oRm.write("</div>");        
    oRm.write("</div>");
    }
});

//example how to avoid rerendering of text, when the name property is changed
my.control.ListItemContent.prototype.setName = function(sText){
    this.setProperty("name", sText, true);
    return this;
};

//example how to use events
my.control.ListItemContent.prototype.ontap = function(){
        //your own tap logic
    this.fireMyTap({});
};

After we've created this notepad control above, we consume it in the sap.m.CustomListItem as a content aggregation, as shown here:

var oCustomListItem = new sap.m.CustomListItem({ content: [new my.control.ListItemContent({
    //usual control setup
})]});