Skip to Content
Technical Articles

Extending ListItem control with Highlight Tooltip (and touch enablement)

The highlight property of a (sap.m.) ListItem (Base) is quite handy to – well “highlight” items.

However, personally I’ve always missed one thing: to be able to give it a tooltip, so I can explain my user, why this item is highlighted and also why in this specific color (Error or Warning etc.).

I am aware that there is the highlightText property, but it is my understanding, that it’s not meant to function as a tooltip and I just wanted to mention it here, that I have used it, but of course it gave me no tooltip.

The goal

Let’s get straight into it:

  • What do I want? A simple tooltip to appear when I mouse-over the little highlight bar.
  • Is there a HTML5 standard for this? Yes, the title attribute.
  • What about touch-only devices without mouse-over? We can enable an “on hold” feature so the tooltip may still appear, even on touch-devices.

The steps

1) Create extended control

We need to create a JS file for our extended control. In my example I will be using ObjectListItem however please note that this should work with any ListItem, that inherits from sap.m.ListItemBase! You may just replace ObjectListItem with whatever ListItem you have (for example ColumnListItem). Let’s put the whole file down for easy copy-paste and then I go into step-by-step.

PROJECT/webapp/controls/ListItemExtended.js

sap.ui.define([
	"sap/m/ObjectListItem",
	"sap/ui/Device"
], function (ListItem, Device) {
	"use strict";
	
	return ListItem.extend("NAMESPACE.controls.ListItemExtended", {
		
		/* Add new property */
		metadata: {
			properties: {
				highlightTooltip: {
					type: "string",
					defaultValue: ""
				}
			}
		},
		
		/* Rendering... */
		renderer: function(oRM, oControl) {
			// call standard renderer 
			// !!! this method is REQUIRED, or otherwise the view will go into error: 
			// this is because by default, UI5 will try to load a renderer with the same 
			// name as the extended control itself and will end in following error:
			// "Uncaught Error: failed to load 'NAMESPACE/controls/ListItemExtendedRenderer.js' from ../../../../../webapp/controls/ListItemExtendedRenderer.js"
			// !!!
			sap.m.ObjectListItemRenderer.render(oRM, oControl); 
		},
		
		/* Changes, after rending is done... */
		onAfterRendering: function() {
			if(ListItem.prototype.onAfterRendering) {
				ListItem.prototype.onAfterRendering.apply(this, arguments);
			}
			//...check if there is a highlight and tooltip
			if(this.getHighlight() !== "None" && this.getHighlightTooltip() !== "") {
				// get highlight DIV
				var oHl = this.$().find(".sapMLIBHighlight");
				if(typeof oHl !== "undefined") {
					// add tooltip property as title attribute
					oHl.attr("title", this.getHighlightTooltip() );
					// check for non-desktop case (touch devices, where we have no "mouseover" title showing)
					if(Device.support.touch) {
						oHl.addClass("titleOnTouch"); // add new css class to show the title when the DIV is :active (touch holding)
					}
				}
			}
		}
	});
});

We are doing 3 things (besides the usual define and extend):

  1. We add the new property to the metadata of our ListItem
  2. We add a renderer and simply call the standard renderer for ObjectListItem (in my case; you may just replace this with for example ColumnListItemRenderer)
  3. Now comes the real code: we use the lifecycle method “onAfterRendering” to add the title attribute, to the finished rendered hightlight DIV.
    1. First of, we again get standard onAfterRendering.
    2. Next we check if we have a highlight at all (“None” value means there is no highlight) and secondly we check, if we have a tooltip to be added at all. Only if both are true, do we need to continue
    3. Next, we need to get the DIV, that is our highlight. This is rather easy; it will always have CSS class sapMLIBHighlight (regardless for color of the highlight) and so we use jQuery (via this.$()) and the find method to get our DIV.
    4. Of course we check and make sure we actually found the highlight DIV. And if yes, we once again use jQuery and the attr method to add (overwrite) the “title” attribute, into the div, with our new property (through the getter method)
    5. Lastly the touch-device support: we check if we have a touch device and if yes, we add our own CSS class into the DIV which I called titleOnTouch

That’s it, not that bad, right?

2) Use the extended control

Now that we have an extended control, of course we need to use it on our view. To do this we need 2 things:

PROJECT/webapp/view/MyView.view.xml

  1. Add reference to our control into the view: on the last line below, we add the “ext:” library and the path to our own control (see file location in step 1 – adjust for your file location if needed). Also be sure to replace NAMESPACE with your proper namespace for this project
    <mvc:View controllerName="NAMESPACE.controller.MyView" 
    	xmlns:html="http://www.w3.org/1999/xhtml" displayBlock="true"
    	xmlns:mvc="sap.ui.core.mvc" 
    	xmlns="sap.m"
    	xmlns:core="sap.ui.core"
    	xmlns:ext="NAMESPACE.controls">​
  2. Use our control instead of the standard UI5 one: below, we first have our sap.m.List and next, instead of using ObjectListItem (or whichever ListItem you have), you need to use the just referenced “ext:” library and the name of the control js file – in my case ListItemExtended:
    <List items="{listview>/MyItems}">
    	<ext:ListItemExtended
    		type="Navigation"
    		highlight="{= ${listview>stock} === 0 ? 'Error' : 'None' }"
    		highlightTooltip="{= 
    			${listview>stock} === 0 ? 'Product currently not in stock!' : '' 
    		}"
    		press="onItemPress"
    		title="{listview>name}"
    		number="{listview>stock}">
    	</ext:ListItemExtended>
    </List>​

    Also, I have above a model called “listview“, which has an array MyItems, in which we have objects with a name and stock property, which is used to dynamically show the Error highlight or not, depending on the stock. Even the tooltip is only added, depending on the stock. This is not really needed, since we are taking care of that already in the previous code in Step 1), where we only add the tooltip, if the highlight is not set to “None”. So it’s up to you if you want to use this or just set the text always. But since it’s possible you need several, different tooltips (depending on various things), you have an example how to achieve that. Of course, the new highlightTooltip property itself, could be bound to a property of the MyItems objects. Lots of possibilities 🙂 !

Still pretty simple! One more thing…

3) CSS “hack” for touch-devices

Above will work as long as we have a mouse that will show the title attribute on mouse-over. But we don’t have this for touch devices and we are already prepared: we add CSS class titleOnTouch to our highlight DIV, if we have a touch-device. Now we need to add this custom style class.

  1. Make sure your manifest includes custom style class file: PROJECT/webapp/manifest.json

    {
    	...
    	"sap.ui5": {
    		...
    		"resources": {
    			"css": [{
    				"uri": "css/style.css"
    			}]
    		},
    	}
    	...
    }
  2. add CSS class titleOnTouch to your custom CSS file: PROJECT/webapp/css/style.css

    .titleOnTouch:active:after {
        content:attr(title);
        /* turn into and style block */
        display: inline-block;
        padding: 5px;
        border: 1px solid #ccc;
        background: #333;
        width: max-content;
        /* position the block */
        position: relative;
        top: 10%;
        left: 6px;
        /* style text */
        font-size: smaller;
        color: #fff;
    }

    with :active, it means that this style is applied while holding the highlight DIV. With :after, we can create a new box, with our title attribute as content, as the CSS code above shows.
    Please note that above box is dark, with a white text. The reason for that is that my ListItem has type “Navigation” (see view code above). Type navigation means that on click (hold), UI5 will mark it and with for example the Belize theme, it will get a blue background. Therefore I found it better visible to have a dark box with white text. However, this can of course be styled exactly to your needs and wishes. Simply adjust the background and color and also border options.

All done! Now you have a ListItem with highlight and highlight tooltips 🙂

The result

And here is how it looks; top is the desktop regular tooltip and below an emulated touch device:

3 Comments
You must be Logged on to comment or reply to a post.
      • Right now it’s time.  I don’t have enough of it.  This change would be considered a “nice to have” instead of a “have to have”.

        If they had it on more projects and noticed how well it worked, I think it may become a “have to have” on their list.