Customize the FUIKPIHeader

Hi, my friends,

I hope you’re all getting ready for the holiday session. One of my habits by the end of the year is to go through the most commonly asked questions I received from the community during workshops and events.

As many of you might know, I was part of a Roadshow series this and last year, which was discussing design as well as the development of iOS Business apps. The big exercise in the workshops was to implement a Travel Expense app. Most of the attendees started out with using the FUIKPIHeader as a starting point for their first screen.

The FUIKPIHeader, in particular, is a great control for starting an overview screen in a lot of business apps.

One of the questions which came up quite often was:

“In what way can we as developers change the appearance of the FUIKPIHeader?”

For this blog post, I want to give a couple of ideas on how to change the appearance of the KPIs.

NOTE: If you’re interested in the content of the Fiori for iOS Roadshow 2019 please go to the official GitHub repository here.

Implementing the FUIKPIHeader

Initially, you would need a KPI header first:

let kpiHeader = FUIKPIHeader()

Each and every single KPI Item will be added to a FUIKPIView or a FUIKPIProgressView which will be added to the FUIKPIHeader.

Each of those Views can hold a set of KPI items. Typically you combine the items in a meaningful way, e.g. using a metric item for the number and the unit item for %, $ or lbs.

To get started let’s implement a simple FUIKPIView displaying 84% Customer Happiness.

let kpiView = FUIKPIView()
let metricItem = FUIKPIMetricItem(string: "54")
let unitItem = FUIKPIUnitItem(string: "%")
kpiView.items = [metricItem, unitItem]
kpiView.captionlabel.text = "Customer Happines"

// Add more FUIKPIViews here

kpiHeader.items = [kpiView]
tableView.tableHeaderView = kpiHeader

As you can see the view being displayed contains the number including the unit and a caption text below.

Using a FUIKPIProgressView allows you to have a progress circle around the KPI itself. This circle gets nicely animated.

let kpiProgressView = FUIKPIProgressView()

let metricItem = FUIKPIMetricItem(string: "84")
let unitItem = FUIKPIUnitItem(string: "%")

kpiProgressView.items = [metricItem, unitItem]
kpiProgressView.captionLabelText = "Customer Happiness"
kpiProgressView.progress = 0.84

kpiHeader.items = [kpiProgressView]
tableView.tableHeaderView = kpiHeader

Another way would be using the metric and unit property on the FUIKPIProgressView.

let kpiProgressView = FUIKPIProgressView()

kpiProgressView.captionLabelText = "Customer Happiness"

kpiProgressView.metric = 84
kpiProgressView.unit = "%"
kpiProgressView.progress = 0.84

kpiHeader.items = [kpiProgressView]
tableView.tableHeaderView = kpiHeader

With that, we have an initial FUIKPIHeader containing a FUIKPIProgressView. In the next section, we’ll see how to make changes to the just implemented FUIKPIHeader, View and Item.

Make some changes!!!

FUIKPIProgressView

First, let’s change the whole thing to green.

Simply add this line of code to the KPI setup code above.

kpiProgressView.tintColor = .preferredFioriColor(forStyle: .positive)

With that one line of code, you can set the tint color and change it accordingly for all elements contained in the FUIKPIProgressView.

Using NSAttributedString, you can change the font and color of the metric and the unit item.

// ...

// Defined the font and the color in the NSAttributes array.
let kpiViewAttributes: [NSAttributedString.Key: Any] = [
    .font: UIFont.systemFont(ofSize: 53),
    .foregroundColor: UIColor.preferredFioriColor(forStyle: .positive)
]

// Use the attributes on both metric- and unit- Item.
let metricItem = FUIKPIMetricItem(attributedString: NSAttributedString(string: "84", attributes: kpiViewAttributes))

let unitItem = FUIKPIUnitItem(attributedString: NSAttributedString(string: "%", attributes: kpiViewAttributes))

kpiProgressView.items = [metricItem, unitItem]

// ...

FUIKPIView

Visually the only difference between the FUIKPIProgressView and the FUIKPIView is that the latter doesn’t have a progress circle around it.

The same code above will get the same result as the FUIKPIView. Using the FUIKPIView gives the advantage of having access to the caption label.

Based on the code using NSAttributedString adding the following line of code to change the color of the caption label.

kpiView.captionlabel.textColor = .preferredFioriColor(forStyle: .critical)

If you have any other questions about the KPIs or any other control feel free to leave a suggestion in the comment section below.

With that Happy Coding!