Navigation Bar¶

By extending the standard Android BottomNavigationView, the SDK allows developers to readily adopt the SAP Fiori Navigation bar "out of the box" or customize the look and feel to support their own requirements.

Anatomy¶

¶

A Navigation Bar appears at the bottom of the screen. There should only be one instance of a Navigation Bar per layout at any time. This Navigation Bar can be used within your activity like any traditional Android view.

Construction¶

A Navigation Bar can be created by the constructor in code:

val navbar = NavigationBar(context)

Navigation Bars may also be constructed using XML:

<com.sap.cloud.mobile.fiori.nav.NavigationBar
     android:id="@+id/nav_bar"
     android:layout_width="match_parent"
     android:layout_height="wrap_content"
     app:layout_constraintBottom_toBottomOf="parent"
     app:layout_constraintEnd_toEndOf="parent"
     app:layout_constraintStart_toStartOf="parent"
     app:menu="@menu/nav_bar_menu" />

The Navigation Bar also has many customizable options (icon color, label text appearance, badge styling, etc.) that can be declared:

<com.sap.cloud.mobile.fiori.nav.NavigationBar
     android:id="@+id/nav_bar"
     android:layout_width="match_parent"
     android:layout_height="wrap_content"
     app:layout_constraintBottom_toBottomOf="parent"
     app:layout_constraintEnd_toEndOf="parent"
     app:layout_constraintStart_toStartOf="parent"
     app:menu="@menu/nav_bar_menu"
     app:labelVisibilityMode="labeled"
     app:itemTextColor="@color/bottom_navigation_bar_label"
     app:itemIconTint="@color/bottom_navigation_bar_label"
     app:itemActiveIndicatorStyle="@style/FioriBottomNavigationView.ActiveIndicator"
     app:itemActiveIndicatorEnabled="true"
     app:itemActiveIndicatorRadius="@dimen/bottom_navigation_active_indicator_radius"
     app:itemActiveIndicatorColor="@color/bottom_navigation_active_indicator"
     app:itemActiveIndicatorWidth="@dimen/bottom_navigation_active_indicator_width"
     app:itemActiveIndicatorHeight="@dimen/bottom_navigation_active_indicator_height"
     app:badgeHorizontalOffset="8dp"
     app:badgeVerticalOffset="8dp"
     app:badgeMaxCharacterCount="4"
     app:badgeBackgroundColor="#00FFFF"
     app:badgeTextColor="#000000"
     app:badgeGravity="TOP_END"
     app:badgesAreVisible="true"
     app:badgeAlpha="255" />

Details on the customization attributes are described in the Customization section below.

For more custom attributes see BottomNavigationView.

Each item in the Navigation Bar is a MenuItem. The Navigation Bar currently supports three to five MenuItems. Adding MenuItems can be done programmatically in code:

navbar.menu.add(Menu.NONE, aUniqueId , Menu.NONE, "Title").setIcon(R.drawable.icon)

The parameters for menu.add are:

groupId – int: The group identifier that this item should be part of. This can be used to define groups of items for batch state changes. Normally use NONE if an item should not be in a group.
itemId – int: Unique item ID. Use NONE if you do not need a unique ID.
order – int: The order for the item. Use NONE if you do not care about the order.
title – CharSequence: The text to display for the item.

The Navigation Bar can also have its menu inflated using XML. These XML files must be in the menu folder inside the resource directory. In this example we are creating a menu with three items:

nav_bar_menu.xml:

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">

    <item
        android:id="@+id/item1"
        android:icon="@drawable/item1"
        android:title="Title1"/>

    <item
        android:id="@+id/item2"
        android:icon="@drawable/item2"
        android:title="Title2"/>

    <item
        android:id="@+id/item3"
        android:icon="@drawable/item3"
        android:title="Title3"/>

</menu>

Inside the onCreate method in your activity:

navbar.inflateMenu(R.menu.nav_bar_menu)

Handling On-Click Events¶

The Navigation Bar provides a simple API to respond to click events, called setOnItemSelectedListener, that takes an OnItemSelectedListener object:

navbar.setOnItemSelectedListener {
    when (it.itemId) {
        R.id.item1 -> { goToFragmentA() }
        R.id.item2 -> { goToFragmentB() }
        R.id.item3 -> { goToFragmentC() }
        else -> { doNothing() }
    }
    true
}

A badge represents dynamic information, such as a number for pending notifications. A badge may have a number or may only be an icon:

// Creates a badge (without a number).
var badge = navbar.getOrCreateBadge(menuItemId)

// Setting a number is optional.
badge.number = 99

Customization¶

The following attributes and APIs are available to customize the basic attributes for the Navigation Bar:

Basic Attributes¶

XML Attribute	Java API	Description
`itemBackground`	`setItemBackground(@Nullable Drawable)`	Set the background of our menu items to the given drawable. This will remove any ripple backgrounds created by `setItemRippleColor(ColorStateList)`.
`itemHorizontalTranslationEnabled`	`setItemHorizontalTranslationEnabled(boolean)`	Sets whether the menu items horizontally translate on selection when the combined item widths fill up the screen.
`itemRippleColor`	`setItemRippleColor(@Nullable ColorStateList)`	Set the `ColorStateList` of the active indicator drawable, replacing any background previously set by `setItemBackground(Drawable)`.
`labelVisibilityMode`	`setLabelVisibilityMode(@LabelVisibility int)`	Sets the navigation items' label visibility mode.The label is either always shown, never shown, or only shown when activated. Also supports "auto" mode, which uses the item count to determine whether to show or hide the label.

Item Icon¶

The following attribute and API is available to customize icons:

XML Attribute	Java API	Description
`itemIconTint`	`setItemIconTintList(@Nullable ColorStateList)`	Set the tint which is applied to our menu items' icons.

Item Label¶

The following attributes and APIs are available to customize labels:

XML Attribute	Java API	Description
`itemTextAppearanceActive`	`setItemTextAppearanceActive(@StyleRes int)`	Set an active `menuitem`'s text appearance.
`itemTextAppearanceInactive`	`setItemTextAppearanceInactive(@StyleRes int)`	Set an inactive `menuitem`'s text appearance.
`itemTextColor`	`setItemTextColor(@Nullable ColorStateList)`	Set the colors to use for the different states (normal, selected, focused, etc.) of the `menuitem` text.

Active Indicator¶

The following attributes and APIs are available to customize the active indicator:

XML Attribute	Java API	Description
`itemActiveIndicatorColor`	`setItemActiveIndicatorColor(@Nullable ColorStateList)`	Set the `ColorStateList` of the active indicator drawable.
`itemActiveIndicatorEnabled`	`setItemActiveIndicatorEnabled(boolean)`	If `true`, show the active indicator, otherwise hide it.
`itemActiveIndicatorHeight`	`setItemActiveIndicatorHeight(@Px int)`	Set the height of the active indicator.
`itemActiveIndicatorRadius`	N/A	Set the radius of the active indicator.
`itemActiveIndicatorWidth`	`setItemActiveIndicatorWidth(@Px int)`	Set the width of an item's active indicator.

Badge¶

The following attributes and APIs are available to customize badges present in the Navigation Bar. Please note that the APIs are applied to all badges. See the BadgeDrawable class for information on customizing individual badges.

XML Attribute	Java API	Description
`badgeAlpha`	`setBadgeAlpha(float)`	Sets the text alpha.
`badgeBackgroundColor`	`setBadgeBackgroundColorInt(@ColorInt int)` `setBadgeBackgroundColorRes(@ColorRes Int)`	Sets a background color.
`badgeGravity`	`setBadgeGravity(@BadgeDrawable.BadgeGravity int)`	Sets a `BadgeDrawable.BadgeGravity`.
`badgeHorizontalOffset`	`setBadgeHorizontalOffset(@Px Int)`	Sets the badge horizontal offset (in pixels).
`badgeHorizontalOffsetWithoutText`	`setBadgeHorizontalOffsetWithoutText(@Px int)`	Sets a horizontal offset without text. Default: `badgeHorizontalOffset`
`badgeHorizontalOffsetWithText`	`setBadgeHorizontalOffsetWithText(@Px int)`	Sets horizontal offset with text. Default: `badgeHorizontalOffset`
`badgeLayoutDirection`	`setBadgeLayoutDirection(int)`	Sets the layout badge direction.
`badgeLevel`	`setBadgeLevel(int)`	Sets the badge level.
`badgeMaxCharacterCount`	`setBadgeMaxCharacterCount(int)`	Sets the badge maximum character count. Default: 4
`badgeTextColor`	`setBadgeTextColorInt(@ColorInt int)` `setBadgeTextColorRes(@ColorRes int)`	Sets the badge text color.
`badgeVerticalOffset`	`setBadgeVerticalOffset(@Px int)`	Sets the badge vertical offset (in pixels).
`badgeVerticalOffsetWithText`	`setBadgeVerticalOffsetWithoutText(@Px int)`	Sets a vertical offset without text. Default: `badgeVerticalOffset`
`badgeVerticalOffsetWithoutText`	`setBadgeVerticalOffsetWithText(@Px int)`	Sets a vertical offset with text. Defualt: `badgeVerticalOffset`
`badgeVisible`	`setBadgeVisible(boolean)`	Set whether all badges should be shown (`true`) or hidden (`false`).

Navigation Bar¶

Anatomy¶

¶

Using the Navigation Bar¶

Construction¶

Adding Menu Items Programmatically to the Navigation Bar¶

Adding Menu Items via XML to the Navigation Bar¶