Skip to Content

Design Studio SDK: (Generic) Kpi Tile

It was quite hot weekend in Germany, I had to stay in the shade for a while.. here is the output ;-)


Purpose

You have a requirement to use a KPI Tile, but all KPI Tiles are not matching your UI Specification?

All other KPI Tiles I have seen were quite restricted, you also the KPI View (in the SCN community) can help you to show KPIs, but the layouting is basic - and you cannot really change it.


The look at this component, brand new KPI Tile for really generic content - you decide what and where is places, you can use all UI5 components which you find in the SAP UI5 Explored page - SAPUI5 Explored

Show Case

This is an example of an KPI View which I have designer - and very similar content is provided as "default".

The new 2.0 release Additional Properties

The additional properties are allowing you to place new content (other UI5 components as in the SAPUI5 Explored web page) into the component. This is the main strength of this generic Kpi Tile.

For today, this component is not yet data bound, but I will try to add also data binding there. The same is for the more complex content (like the micro charts) - we need more convenient API to change the content on the fly (today it is possible, but you need to pass the XML definition of the UI5 property).


How to use

First, just drop into the canvas, it will come with some pre-defined settings - some texts etc. You can use the Additional Property Sheet to change the properties and place your data.

The Properties - The Core Piece of this Component

For the generic usage, it is important to understand how the properties are working. I will make this on the example of the application SDK_GENERIC_TILE

First, when you look at the default component after dropping into canvas, this is what you see:

There are already some sub-components predefined in the default values, you can see them in additional properties.

as you see, it is the header, title, value, chart and footer. Lets take a look on the header - it has some properties.

in the first area, there are basic properties - for size, position, component type (as of the UI5 page) and Full Specification (later).

Now, on the right side, you can see more properties.

here, we have for instance the property "text". All properties are starting with the technical name of the component and divided by the / sign, then the property name is given.

the property value is describing the content of this property. It is allowed to use also XML here for more complex properties. Here is an example of the CHART component.

Name: CHART/maxThreshold

the name is always COMPONENT_ID/propertyName

Value:

<maxThreshold>

         <MicroAreaChartItem color="Good">

           <points>

             <MicroAreaChartPoint x="0" y="0" />

            <MicroAreaChartPoint x="30" y="40" />

            <MicroAreaChartPoint x="60" y="50" />

            <MicroAreaChartPoint x="100" y="100" />

          </points>

         </MicroAreaChartItem>

       </maxThreshold>

Important: the check for XML is based on FIRST character (if it is <), assure that you do not have spaces before. I hope this can be improved later.

The "Full Specification" property.

This property is based on the fact, that all UI5 controls can be specified by XML. you can see the URL when you look at the controls on SAPUI5 Explored web page:

and when you click into the "code" icon, you will see the XML. Currently, as here to make it easier to use there are no special namespaces, you can use controls of:

  • sap.m
  • sap.suite.ui.commons

// example for charts

Taking it as a control, you can copy paste the complete XML into the area and the control will be generated based on this specification. All properties from the details view are applied on top (here you can then overwrite some properties).

Interesting Point

the complete specification of the content is placed in this property (in the standard property grid):


it means, you can easily copy & paste the complete content. in current version, assure that you do not put empty value here, minimum is an empty JSON array: [] (other case you need to reload the app in designer)


Dynamic in Script

if you check the available script, you can have full freedom there - add, delete or change components or properties.


// to add new component:

KPITILE_2.addComponent("LABEL", "Label", 10, 10, -1, 10, 200, 30, "");

KPITILE_2.addProperty("LABEL", "LABEL/text", "halo");


// to change text property

KPITILE_2.setPropertyValue("LABEL/text", "halo");


// to delete property in the model (current visualization will be NOT updated)

KPITILE_2.removeProperty("LABEL/text");


// to delete property in the UI (current visualization will be NOT updated)

KPITILE_2.setPropertyValue("LABEL/text", "-clean-");


Examples for Scripting


In scripts, you can change also complex properties. the definition can be made by the same XML. Internally XML is always converted to JSON (some OS XML2JSON component makes it..), to you can even use JSON model for the property.


1 - you want to add a component with property...

KPITILE_2.addComponent("LABEL", "Label", 10, 10, -1, 10, 200, 30, "");

KPITILE_2.addProperty("LABEL", "LABEL/text", "KPI IS CHECKED");

KPITILE_2.addProperty("LABEL", "LABEL/textAlign", "Right");


2 - you want to change complex property. You can use set if you sure the property is already there!

var def = "";

def = def + "<chart>";

def = def + "         <MicroAreaChartItem>";

def = def + "           <points>";

def = def + "            <MicroAreaChartPoint x='0' y='100' />";

def = def + "            <MicroAreaChartPoint x='30' y='40' />";

def = def + "            <MicroAreaChartPoint x='60' y='20' />";

def = def + "            <MicroAreaChartPoint x='100' y='60' />";

def = def + "          </points>";

def = def + "         </MicroAreaChartItem>";

def = def + "       </chart>";

KPITILE_1.setPropertyValue("CHART/chart", def);


3 - you want to change not so complex property, using XML and existence check

var def = "";

def = def + "<firstXLabel>";

def = def + "<MicroAreaChartLabel label='September 1' color='Good'/>";

def = def + "</firstXLabel>";

var propId = "CHART/firstXLabel";

if(KPITILE_1.hasPropertyValue(propId)) {

  KPITILE_1.setPropertyValue(propId, def);

} else {

  KPITILE_1.addProperty("CHART", propId, def);

}


4 - you want to set the same property using JSON notation

var def = "";

def = def + "{";

def = def + "   \"lastXLabel\":{";

def = def + "      \"MicroAreaChartLabel\":{";

def = def + "         \"label\":\"September 30\",";

def = def + "         \"color\":\"Critical\"";

def = def + "      }";

def = def + "   }";

def = def + "}";

var propId = "CHART/lastXLabel";

KPITILE_1.addProperty("CHART", propId, def);


See SDK_KPI_TILE for examples.


What is Next?

in best case, this is the last SDK component which has been written ;-)

1. But, still it is quite generic - therefore I will investigate if the "technology" can be used for new components, then the work would be even easier as the spec can be done then in XML and no code is required any more.

2. it would be good to make it data bound, this is the next planned step.

3. setting of properties are quite technical, I am not sure how far the generic component is good for daily use, perhaps someone can check and comment.


Download & Use

This component is available on the community package, release 2.0 for Design Studio 1.5, as in SCN Design Studio SDK Development Community

Example as BIAPP:

org-scn-design-studio-community/applications · GitHub

-> SDK_GENERIC_TILE

-> SDK_KPI_TILE

Documentation

Component List - SCN Design Studio Community -> look for the component in the list.

Any thoughts?

feel free to add as usual...

Enhancements Ideas?

if you have good ideas (to those who would like to contribute but cannot code...) - place an "issue" with tag "enhancement" under Issues · org-scn-design-studio-community/sdkpackage · GitHub

Tags: