Contact Cell¶
ContactCell
is used to give quick access to the various methods of communicating with a contact. It is commonly found in an Object.
Anatomy¶
A ContactCell
consists of image, labels (headline, and sub headline), description, and contact actions. Comparing to Object Cell, ContactCell
does not have footnote, icon stack and statuses; secondary action becomes multiple contact actions; and the image border becomes a circle. A common rule for image shape is that object image should be rectangle while person image should be circle.
Examples¶
Here is an example of ContactCell
s on a tablet:
Here is an example of ContactCell
s on a phone:
Usage¶
ContactCell
can be used inside a RecyclerView
, ListView
or other ViewGroup
s. The example code below assumes the parent view is RecyclerView
.
Construction¶
ContactCell
can be created either by the constructor in code or by declaring an ContactCell
element in XML like this:
<com.sap.cloud.mobile.fiori.contact.ContactCell xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:layout_width="match_parent"
android:layout_height="wrap_content"
app:lines="3"
app:descriptionWidthPercent=".60"
app:preserveDetailImageSpacing="true"
app:asyncRendering="true"
>
<ImageButton
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:layout_contact_group="ACTION"
/>
</com.sap.cloud.mobile.fiori.contact.ContactCell>
Then the XML can be inflated in a RecyclerView.Adapter
.
public ViewHolder onCreateViewHolder(
ViewGroup parent, int viewType) {
Context context = parent.getContext();
ContactCell view = inflater.inflate(R.layout.contact_cell, parent,
false);
return new ViewHolder(view);
}
The above XML declaration creates an ContactCell
with the following attributes:
app:lines="3"
3 lines of text enabled, with room for headline and sub headline. On tablet, description field can show at most 3 lines of text. (description is hidden on a phone.)app:asyncRendering="true"
On tablet, description field will delay the rendering and show "Loading..." first. This is a performance tuning approach to speed up frame rendering during scrolling since multiple line text measurement and layout is expensive. No effect on phone.app:descriptionWidthPercent=".60"
60% horizontal space will be used for description, 40% will be used for headline. This percentage calculation excludes other fields, like image and statuses.app:preserveDetailImageSpacing="true"
When image for theContactCell
is missing, the space will be preserved to maintain consistent layout. A letter can be specified as the placeholder.
Fields¶
Image¶
An image provides visual representation of the contact and is highly recommended. Glide can be used to streamline image download and decryption without blocking UI.
RequestOptions cropOptions = new RequestOptions().placeholder(
R.drawable.rectangle);
holder.target = mGlide.load(obj.getDetailImageUri()).apply(cropOptions).into(
cell.prepareDetailImageView());
cell.setDetailImageDescription(R.string.avatar);
Tip
For Glide to asynchronously load image into a view, the view instance must be created beforehand. cell.prepareDetailImageView()
can make sure the image view exists. Also, to improve app accessibility, all images should provide content description, thus cell.setDetailImageDescription(R.string.avatar)
.
If image is missing, a letter can be used as placeholder instead.
cell.setDetailImage(null);//make sure we're not showing recycled images
cell.setDetailImageCharacter(obj.getName().substring(0, 1));
Headline¶
The headline/name is the main area for text content. The headline is the only mandatory content for ContactCell
. Headline can be specified by:
cell.setHeadline(obj.getName());
Sub Headline¶
The sub headline is under headline to show more information such as the contact's title.
cell.setSubheadline(obj.getTitle());
Description¶
If a description has been defined, it will appear only in views with a tablet-like form factor. This is typically a longer string of text such as address of the contact.
cell.setDescription(obj.getAddress());
Contact Actions¶
Up to four action icons can be can be displayed in a view with a phone-like form factor, a profile image cannot be used if four action icons are to be used.
Action icons can be created in XML via "contactActions" attribute:
app:contactActions="CALL,EMAIL,VIDEO_CALL,MESSAGE"
or via "ImageButton" child elements:
<com.sap.cloud.mobile.fiori.contact.ContactCell
android:layout_width="match_parent"
android:layout_height="wrap_content"
app:headline="@string/testName"
app:subheadline="@string/testTitle"
app:description="@string/testAddress"
app:detailImage="@drawable/ic_account_circle_black_24dp"
app:detailImageDescription="@string/testDetailImageDesc"
>
<ImageButton
android:id="@+id/contactCell3_s1"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:layout_contact_group="ACTION"
android:src="@drawable/ic_phone_black_24dp"
/>
<ImageButton
android:id="@+id/contactCell3_s2"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:layout_contact_group="ACTION"
android:src="@drawable/ic_email_black_24dp"
/>
</com.sap.cloud.mobile.fiori.contact.ContactCell>
Tip
Notice the usage of app:layout_contact_group="ACTION"
. Without it, the child view will be ignored by ContactCell
.
Or in code:
cell.setContactActions(ContactCell.ContactAction.CALL, ContactCell.ContactAction.EMAIL, ContactCell.ContactAction.VIDEO_CALL, ContactCell.ContactAction.MESSAGE);
cell.getContactActionView(0).setEnabled(false);
cell.getContactActionView(1).setEnabled(true);
cell.getContactActionView(1).setOnClickListener(l);
...
Style¶
Style of the component can be customized on application level or component level. Similar to Object Cell, the FioriTheme
uses a contactCellStyle
which points to the ContactCell
style. Example:
<!-- Base application theme. -->
<style name="AppTheme" parent="FioriTheme">
<!-- Customize your theme here. -->
<item name="contactCellStyle">@style/TestContactCell</item>
</style>
<style name="AppTheme.NoActionBar" parent="AppTheme">
<item name="windowActionBar">false</item>
<item name="windowNoTitle">true</item>
</style>
<style name="AppTheme.AppBarOverlay" parent="FioriTheme.AppBarOverlay" />
<style name="AppTheme.PopupOverlay" parent="FioriTheme.PopupOverlay" />
<style name="TestContactCell" parent="ContactCell">
<item name="headlineTextAppearance">@style/Test.ContactCell.Headline</item>
</style>
<style name="Test.ContactCell.Headline" parent="TextAppearance.Fiori.ContactCell.Headline">
<item name="android:textColor">@color/colorPrimaryDark</item>
<item name="android:textStyle">italic</item>
</style>
AppTheme
will be your application main theme, while AppTheme.NoActionBar
can be used when the default toolbar is not used. Here we're only customizing the FioriTheme
with a new contactCellStyle
, which in turn only customizes the headline text appearance. The headline of ContactCell
is still going to use the default font and size defined in TextAppearance.Fiori.ContactCell.Headline
and all other fields in ContactCell
will keep the default style.
The AppTheme
can then be applied to your application in AndroidManifest.xml
:
<application
android:name=".DemoApplication"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:theme="@style/AppTheme">
On the other hand, if only one instance of the ContactCell
needs to be customized, you can set the text appearances as this:
<com.sap.cloud.mobile.fiori.contact.ContactCell
android:layout_width="match_parent"
android:layout_height="wrap_content"
app:headlineTextAppearance="@style/Test.ContactCell.Headline"
app:subheadlineTextAppearance="@style/Test.ContactCell.Subheadline"
app:descriptionTextAppearance="@style/Test.ContactCell.Description"
...
Data Binding¶
Please reference Object Cell for an example.