Object Cell

Object Cell is a list item view that can represent a business object.

Anatomy

An Object Cell consists of an unread object indicator, avatar,icon stack, labels (headline, subheadline,footnote), tags, description, statuses, attribute icons, avatar stack and action icon.

Object Cell Anatomy

Example

Object Cell on a Tablet

Development

Object Cell are implemented entirely using Jetpack Compose, including a Composable FioriHorizonTheme. To understand the fundamentals of Jetpack Compose, refer to the Android Developer's documentation.

The Object Cell provides two UI components for application developers to use

• FioriObjectCell – a UI component to display a single Fiori Object Cell.
• FioriObjectCellList – a UI component to display a series of Object Cell in a horizontally scrollable list.

Usage in an Application

This section describes how to use the Object Cell components in an application.

Object Cell on a Phone

How to Create an Object Cell

FioriObjectCell is a Composable function that takes below parameters:

• uiState – a FioriObjectCellUiState that specifies the data to be displayed on the cell. We provide rememberFioriObjectCellUiState to generate uiState to let it be rememberSaveable
• modifier – a Modifier that is used to define the height and width of the cell.
• onClick – a lambda that specifies the lamda function that can be called when click on cell
• onLongPress – a lambda that specifies the lamda function that can be called when long press on cell
• onSwipeToStart – a lambda that specifies the lamda function that can be called when swipe to Start, this function will not work when cellSwipeable in FioriObjectCellData not set to true
• onSwipeToStartIcon – a Painter icon define for the icon displayed when swipe to Start
• onSwipeToEnd – a lambda that specifies the lamda function that can be called when swipe to End, this function will not work when cellSwipeable in FioriObjectCellData not set true
• onSwipeToEndIcon – a Painter icon define for the icon displayed when swipe to End
• progress – a lambda for the progress bar. This will displayed when displayProgress set to true in FioriObjectCellUiState
• colors – a FioriObjectCellColors define the color use in cell
• textStyles – a FioriObjectCellTextStyles define the textStyles in cell
• styles – a FioriObjectCellStyles define the styles such like padding in cell

@Composable
fun FioriObjectCell(
    uiState: FioriObjectCellUiState,
    modifier: Modifier = Modifier,
    onClick: (() -> Unit)? = {
        uiState.isRead = true
    },
    onLongPress: (() -> Unit)? = {
    },
    onSwipeToStart: (() -> Unit)? = null,
    onSwipeToStartIcon: Painter = PainterBuilder.build(icon = FioriIcon(resId = R.drawable.ic_delete_white_24dp)),
    onSwipeToEnd: (() -> Unit)? = null,
    onSwipeToEndIcon: Painter = PainterBuilder.build(icon = FioriIcon(resId = R.drawable.ic_outline_add_24px)),
    progress: (@Composable () -> Unit)? = {
        CircularProgressIndicator(
            modifier = Modifier.size(FioriObjectCellDefaults.styles().actionButtonSize()),
            color = FioriObjectCellDefaults.colors().progressIndicatorColor()
        )
    },
    colors: FioriObjectCellColors = FioriObjectCellDefaults.colors(),
    textStyles: FioriObjectCellTextStyles = FioriObjectCellDefaults.textStyles(),
    styles: FioriObjectCellStyles = FioriObjectCellDefaults.styles(),
)

An object of the FioriObjectCellUiState has to be passed in from the application in order to create an FioriObjectCell.

class FioriObjectCellUiState(
    data: FioriObjectCellData,
    isRead: Boolean = false,
    displayProcess: Boolean = false,
    displaySelectBox: Boolean = false,
)

FioriObjectCellUiState including data a FioriObjectCellData ,isRead a Boolean, displayProcess a Boolean,displaySelectBox a Boolean, these four parameters are defined as mutableStateOf. We provide rememberFioriObjectCellUiState function to generate rememberSaveable FioriObjectCellUiState .

FioriObjectCellData is like below

@Parcelize
data class FioriObjectCellData(
    val headline: String = "",
    val avatar: FioriAvatarConstruct? = null,
    var iconStack: List<IconStackElement>? = null,
    val subheadline: String? = null,
    val footnote: String? = null,
    val description: String? = null,
    val tags: List<FioriTagData> = listOf(),
    val avatarStack: FioriAvatarConstruct? = null,
    val cellClickable: Boolean = true,
    val cellSwipeable: Boolean = true,
    var status: FioriObjectCellStatusData? = null,
    var subStatus: FioriObjectCellStatusData? = null,
    val attributeIcons: AttributeIcons? = null,
    val action: Action? = null,
    val contactActions: List<Action>? = null,
    val enabled: Boolean = true,
    var isSelected: Boolean = false,
    var cellType: CellType = CellType.OBJECT
) : Parcelable

Fields

Headline

The headline is the main area for text content. The headline is the only mandatory content for Object Cell. The title can be specified by:

headline = ""

in FioriObjectCellData

Icon Stack

The iconStack is the area for icon and text display. The text will always displayed at the top of iconStack.Two iconStack elements can be displayed in the stack. The iconStack can be specified by

iconStack = listOf(
    IconStackElement(text = "Display"),
    IconStackElement(
        icon = FioriIcon(
            resId = R.drawable.ic_directions_24px,
            contentDescription = "checked"
        )
      )
    ),

Avatar

The avatar provides a visual representation of the object , can be specified by :

avatar = FioriAvatarConstruct(
    hasBadge = hasBadge,
    hasBorder = hasBorder,
    avatarList = listOf(
        FioriAvatarData(
            image = FioriImage(url = ""),
        ), FioriAvatarData(
            image = FioriImage(url = ""),
        )
    ),
    size = 18.dp,
    avatarBadge = FioriIcon(
        resId = R.drawable.ic_circle_unread
    ),
    type = FioriAvatarType.DOUBLE
)

FioriAvatarConstruct is used to construct the Avatar area.

@Parcelize
data class FioriAvatarConstruct(
    val type: FioriAvatarType = FioriAvatarType.SINGLE,
    var avatarList: List<FioriAvatarData>,
    val hasBadge: Boolean = false,
    val avatarBadge: FioriIcon? = null,
    val groupDisplayNumber: Int = 0,
    val size: Dp = 40.dp,
    val hasBorder: Boolean = false,
    val borderColor: Color? = null,
    val backgroundColor: Color? = null,
    val shape: FioriAvatarShape = FioriAvatarShape.ROUNDEDCORNER
) : Parcelable

• type – a FioriAvatar have three type. SINGLE,DOUBLE,GROUP. SINGLE and DOUBLE is used to display in the Avatar area. Group is used to display in Avatar stack area.
• avatarList – a List contains FioriAvatarData objects
• hasBadge – a Boolean is used to display the badge or not
• avatarBadge – a FioriIcon is used to define the badge
• groupDisplayNumber – a Int is used to display the number when use the group type.
• size – a Dp is used to define the Avatar area size when AvatarType is Single and Double.
• hasBorder – a Boolean is used to display the border of Avatar.
• borderColor – a Color is used to define the color of border.
• backgroundColor – a Color is used to display the background of Avatar.
• Shape – a FioriAvatarShape is used to support two type.ROUNDEDCORNER and CIRCLE.

Subheadline

The subheadline is under the headline and provides additional information.The subheadline can be specified by:

subheadline = ""

Footnote

The footnote is under the subheadline and provides further information.The footnote can be specified by:

footnote = ""

Tags

Tags may be used to indicate categories, types, or statuses. Tags are displayed next to the footnote if space is available. The tags can be specified by :

tagsDemo = listOf(
    FioriTagData(text = "gray"),
    FioriTagData(text = "blue"),
    FioriTagData(text = "red"),
)

Description

The description is under the headline/subheadline/foots/tags and status/substatus/attribute icons and provides further information.The description can be specified by:

description = ""

Avatar Stack

The avatar stack is a FioriAvatarConstruct that displays a row of FioriAvatar at the bottom of the cell. FioriAvatarType should set to the Group. The Avatar stack can be specified by :

avatarStack = FioriAvatarConstruct(
    hasBadge = false,
    type = FioriAvatarType.GROUP,
    avatarList = listOf(avatar2, avatar3, avatar4, avatar5),
    size = 16.dp,
    groupDisplayNumber = 4,
    hasBorder = false
)

Status

Up to two statuses(status and substatus) can be displayed, stacked vertically, to show attributes of the object. Status could be customized as either text or an image.

statusData = FioriObjectCellStatusData(
    label = "Success",
    icon = FioriIcon(
        resId = R.drawable.ic_baseline_tag_faces_24,
        contentDescription = "Positive status icon",
    ),
    type = FioriObjectCellStatusType.Positive,
    isIconAtStart = true
)

Attribute Icons

A set of icons can be displayed horizontally under the statuses. These icons can represent both persistent and variable information about the object. It is recommended to have at most four attribute icons.

attribute = AttributeIcons(
    iconsList = listOf(
        FioriIcon(
            resId = R.drawable.ic_chip_checked,
            contentDescription = "checked"
        ),
        FioriIcon(
            resId = R.drawable.ic_chip_checked,
            contentDescription = "checked"
        )
    )

Action

Action can be displayed on the right of cell. It is suggest to only have one action in object cell.

iconAction =
    Action(
        icon = FioriIcon(
            resId = R.drawable.ic_email_black_24dp,
            contentDescription = "email",
        )
    )

Progress

User can define the progress by using lambda. Below is the default Progress bar. Progress display or not decide by displayProcess in FioriObjectCellUiState

{
    CircularProgressIndicator(
        modifier = Modifier.size(FioriObjectCellDefaults.styles().actionButtonSize()),
        color = FioriObjectCellDefaults.colors().progressIndicatorColor(),
    )
},

User Action

Simple Tap/Click to Enable/Disable Read Mode

Upon clicking or tapping an Object Cell, the entire cell will display a ripple effect and then the details about the clicked Object Cell will open up. Returning to the list of Object Cells, the clicked Object Cell will be marked as Read, i.e.the unread object indicator will disappear. User can customize the onClick function. Below is the default implementation.

{
     uiState.isRead = true
}

Long Press to Enable/Disable Selection Mode

An Object Cell can enter and exit selection mode by displaySelectBox in FioriObjectCellUiState. The Object Cell gains a checkbox in Selection mode.User can also customize the onLongPress. FioriObjectCellList use enableSelectBox to enable the selection mode. User can customize the onLongPress function. Below is the default implementation in FioriObjectCellList

{
    enableSelectBox.value = !enableSelectBox.value
}

Enabling Actions on Swipe

cellSwipeable can set to true to enable the swipe action of Object Cell. onSwipeToStart,onSwipeToStartIcon,onSwipeToEnd,onSwipeToEndIcon are used to define the swipe lambda and swipe icon. App developers can define their own actions in response to the swipe gesture in two directions. In the demo app provided by Fiori UI, a delete action is defined for swiping from right to left, and a mock add action is defined for swiping from left to right. Swipe can defined either in FioriObjectCell or FioriObjectCellList. Below is the example in FioriObjectCellList. Swipe can have two behavior when Release the swipe. Release.EXTEND and Release.Reset . These two behavior can defined in styles.

FioriObjectCellList(
    objectCellList = objectList,
    enableSelectBox = enableSelectBox,
    onClick = {
        if (it.isRead == false) {
            it.isRead = true
        }
        currentNews.newsData = it.stateData
        navController.navigate(Screen.ObjectCellDetail.route)
    },
    onSwipeToEnd = { p1, p2 ->
        p2.isRead = !p2.isRead
    },
    onSwipeToStart = { p1, p2 ->
        objectList.remove(p2)
        Toast.makeText(
            context,
            " The index ${p1!!} item is deleted from list ",
            Toast.LENGTH_SHORT
        )
            .show()
    },
    styles = FioriObjectCellDefaults.styles(
        headlineDisplayLineMaxNumber = headlineNumber,
        subheadlineDisplayLineMaxNumber = subheadlineNumber,
        footnoteDisplayLineMaxNumber = footnoteNumber,
        swipeToEnd = SwipeRelease.RESET,
        swipeToStart = SwipeRelease.EXTEND
    ),
)

Contact Cell

Object cell can defined as a special type Contact cell. Contact cell can have multiple actions. User can define the Contact cell by set the cell type.

cellType = CellType.CONTACT

Fiori Object Cell List

FioriObjectCellList provide to display the Object Cell in a list.It accept a list of FioriObjectCellUiState as parameter.

@Composable
fun FioriObjectCellList(
    modifier: Modifier = Modifier,
    objectCellList: MutableList<FioriObjectCellUiState>,
    onSwipeToStart: ((Int, FioriObjectCellUiState) -> Unit)? = null,
    onSwipeToStartIcon: Painter = PainterBuilder.build(icon = FioriIcon(resId = R.drawable.ic_delete_white_24dp)),
    onSwipeToEnd: ((Int, FioriObjectCellUiState) -> Unit)? = null,
    onSwipeToEndIcon: Painter = PainterBuilder.build(icon = FioriIcon(resId = R.drawable.ic_outline_add_24px)),
    enableSelectBox: MutableState<Boolean> = mutableStateOf(false),
    onClick: ((FioriObjectCellUiState) -> Unit)? = {
        it.isRead = true
    },
    onLongPress: ((FioriObjectCellUiState) -> Unit)? = {
        enableSelectBox.value = !enableSelectBox.value
    },
    progress: (@Composable () -> Unit)? = {
        CircularProgressIndicator(
            modifier = Modifier.size(FioriObjectCellDefaults.styles().actionButtonSize()),
            color = FioriObjectCellDefaults.colors().progressIndicatorColor()
        )
    },
    colors: FioriObjectCellColors = FioriObjectCellDefaults.colors(),
    textStyles: FioriObjectCellTextStyles = FioriObjectCellDefaults.textStyles(),
    styles: FioriObjectCellStyles = FioriObjectCellDefaults.styles(),
    )

Styles

The style of the component can be customized . The recommended approach is to override FioriObjectCellDefaults.styles and only customize the attributes you desire. This means that other attributes can be retained and all the components in the application will have a consistent look and feel. For example:

FioriObjectCell(
    uiState = myUiState,
    modifier: Modifier = Modifier,
    progress = { MyProgressButton() },
    styles = FioriObjectCellDefaults.styles(avatarSize = 40.dp)
)

User can also pass in the modifier to set the width and height of the object cell

---

Last update: February 20, 2023