Conversation List Page

The conversation list page displays all conversations on the current user's device. Once the SDK's local message database generates messages, the SDK will generate a conversation list, sorted in reverse chronological order, with pinned conversations appearing at the top.

Global IM UIKit provides a conversation list page implemented based on the Activity class and the Fragment class.

• Activity-based: The default conversation list provided by Global IM UIKit is ChatListActivity. When the SDK's internal pages need to navigate to the conversation list, it will jump to the default conversation list Activity.
• Fragment-based: You can integrate the conversation list ChatListFragment provided by Global IM UIKit into your application's Activity, i.e., customizing the conversation list Activity. Note that you need to register the custom conversation list Activity with the Global IM UIKit SDK to replace the default conversation list Activity provided by Global IM UIKit.

Conversation List Interface

The conversation list interface generally consists of two parts: the navigation bar and the conversation list.

Conversation List Page Structure

• ChatListActivity: Provides a container for loading ChatListFragment and has no specific implementation.
• ChatListFragment: Binds ViewModel and various Components in the page, and provides data source capabilities to the components.
• ChatListModule: Responsible for the UI display of ChatListFragment and initializes the various Components on the current page.
• ChatListViewModel: Provides the data source for the conversation list page and interfaces for all operations.

Conversation List Page Components

• HeaderComponent: Navigation component, providing display of connection status prompts and a search entry button.
• HeaderSelectComponent: Multi-select mode component, triggered when long-pressing a conversation to enter multi-select mode. Global IM UIKit has default implementations for Conversation Do Not Disturb, Mark as Read, Pin Conversation, and Delete Conversation.
• ChatListComponent: Conversation list component, displaying all conversations in reverse chronological order, with pinned conversations appearing at the top. Long-pressing a conversation in the list will default to triggering multi-select mode and selecting the current conversation. The view for each item in the conversation list is created and customized in BaseChatListItemProvider.java.
• PageStatusComponent: Page status component, displayed when there is no data in the current conversation list.

Page Effect Display

If the Multi-Device Message Synchronization feature is enabled in the Console, in scenarios such as logging in on a new device or reinstalling the application, the offline compensation mechanism can only retrieve recent (default offline compensation period is 1 day, maximum 7 days) one-to-one and group chat messages. Conversations older than this period cannot be retrieved through the offline compensation mechanism. Therefore, the conversation list after offline compensation may not be consistent with the conversation list on the original device or before uninstallation (you may feel like some conversations are missing).

Usage

Global IM UIKit provides Activity and Fragment to create the conversation list page. ChatListActivity is the default conversation list page provided. You can choose to directly use the default conversation list page Activity, or inherit ChatListActivity or use ChatListFragment to build a custom conversation list Activity.

Global IM UIKit has already implemented the default behavior of jumping to the corresponding conversation page when clicking on a conversation in the conversation list.

Launching the Conversation List Page

There are two ways to launch the conversation list Activity: by calling the SDK's built-in Activity router, or through intent navigation. You can also customize the launch method of the conversation list page to implement launching the conversation list page from other Activities in your application.

Using RouteUtil

RouteUtil is the built-in Activity router in Global IM UIKit, encapsulating the navigation methods for various pages within the SDK, avoiding repetitive intent encapsulation in the application.

If you have built a custom conversation list Activity, you must first register the custom Activity with RouteUtil to navigate to the custom conversation list Activity using this method; otherwise, it will navigate to the SDK's default ChatListActivity.

Navigating to the conversation list Activity:

RouteUtil.routeToChatListActivity(context);

Navigating via Intent

You can assemble the Intent yourself and use the default Android mechanism to navigate.

Intent intent = new Intent(context, MyChatListActivity.class);
context.startActivity(intent);

Inheriting the Default Conversation Page Activity

You can create a custom conversation list Activity by inheriting ChatListActivity to adjust the conversation list page. Note that you must register the custom conversation list Activity with RouteUtil. After registration, when the SDK needs to navigate to the conversation list, it will navigate to your registered custom conversation list Activity. The registration method needs to be called once in the application lifecycle, in the main process.

RouteUtil.registerActivity(RouteUtil.ActivityType.CHAT_LIST_ACTIVITY, MyChatListActivity.class);

Using Custom ChatListFragment to Build a Custom Conversation List

The conversation list Fragment class provided by Global IM UIKit is named ChatListFragment. To facilitate customizing the conversation list page in the application, it is recommended to inherit and use the conversation list ChatListFragment class to build a custom conversation list Activity. By overriding factory methods.

1. You first need to inherit KitFragmentFactory to override the methods of the Fragment you wish to customize. Please refer to the following code as an example.

   public class CustomFragmentFactory extends KitFragmentFactory {
   
       @NonNull
       @Override
       public Fragment newChatListFragment(@NonNull Bundle args) {
           return new ChatListFragment.Builder()
                   .withArguments(args)
                   .setCustomFragment(new CustomChatListFragment())
                   .build();
       }
   }

2. Replace the custom KitFragmentFactory in Application ConfigCenter.setKitFragmentFactory(KitFragmentFactory).

   public class CustomApplication extends Application {
       @Override
       public void onCreate() {
           super.onCreate();
           ConfigCenter.setKitFragmentFactory(new CustomFragmentFactory());
       }
   }

Customization

tip

Some styles and behaviors in the conversation page list are affected by Global IM UIKit's global configuration. For details on global configuration, see [Configuration Guide].

Modifying Navigation Bar Style and Functionality

Global IM UIKit supports customization of components, such as adding an icon and click event in the right area of the navigation bar. This is provided by Global IM UIKit's ChatListHeaderComponent for adding and removing Views.

public class CustomChatListFragment extends ChatListFragment {

    @Override
    protected void onBindHeaderComponent(@NonNull ChatListModule module, @NonNull ChatListHeaderComponent headerComponent, @NonNull ChatListViewModel viewModel) {
        super.onBindHeaderComponent(module, headerComponent, viewModel);

        // Navigation bar left - add a View at the specified position
        module.getHeaderComponent().addLeftView(new View(getContext()), 0);
        // Navigation bar left - remove the View at the specified position
        module.getHeaderComponent().removeLeftView(0);

        // Navigation bar center - add a View at the specified position
        module.getHeaderComponent().addCenterView(new View(getContext()), 0);
        // Navigation bar center - remove the View at the specified position
        module.getHeaderComponent().removeCenterView(0);

        // Navigation bar right - add a View at the specified position
        module.getHeaderComponent().addRightView(new View(getContext()), 0);
        // Navigation bar right - remove the View at the specified position
        module.getHeaderComponent().removeRightView(0);
    }
}

Adding and Removing Operation Items in Multi-Select Mode Component

This component supports adding or removing operation items.

1. Inherit Global IM UIKit's ChatListHeaderSelectComponent to create a subclass, such as CustomChatListHeaderSelectComponent.

   public class CustomChatListHeaderSelectComponent extends ChatListHeaderSelectComponent {
       public CustomChatListHeaderSelectComponent(@NonNull Context context) {
           super(context);
       }
   
       public CustomChatListHeaderSelectComponent(@NonNull Context context, @Nullable AttributeSet attrs) {
           super(context, attrs);
       }
   
       @NonNull
       @Override
       protected List<ChatAction<List<Conversation>>> beforeCreateChatActionView(@NonNull List<ChatAction<List<Conversation>>> chatActions) {
           // Add an operation item to the navigation bar at position 0
           chatActions.add(0, new ChatAction<List<Conversation>>() {
               @Override
               public String obtainTitle(@NonNull Context context, List<Conversation> data) {
                   return "Item Name";
               }
   
               @Override
               public Drawable obtainDrawable(@NonNull Context context, List<Conversation> data) {
                   return ResourcesCompat.getDrawable(context.getResources(), io.rong.uikit.R.drawable.ic_drawable, null);
               }
   
               @Override
               public void onClick(@NonNull List<Conversation> data) {
                   Toast.makeText(getContext(), "Clicked", Toast.LENGTH_SHORT).show();
               }
           });
   
           // Add an operation item to the more window
           chatActions.add(new ChatAction<List<Conversation>>() {
               @Override
               public String obtainTitle(@NonNull Context context, List<Conversation> data) {
                   return "Item Name";
               }
   
               @Override
               public Drawable obtainDrawable(@NonNull Context context, List<Conversation> data) {
                   return ResourcesCompat.getDrawable(context.getResources(), io.rong.uikit.R.drawable.ic_drawable, null);
               }
   
               @Override
               public void onClick(@NonNull List<Conversation> data) {
                   Toast.makeText(getContext(), "Clicked", Toast.LENGTH_SHORT).show();
               }
   
               // Whether to add to the more window
               @Override
               public boolean isLocationMoreWindow() {
                   return true;
               }
           });
           return chatActions;
       }
   }

2. Copy global IM Kit's rc_chat_list_module.xml to the main project's res/layout, find <com.rongcloud.im.uikit.chatlist.component.ChatListHeaderSelectComponent /> and replace it with the subclass's full path <com.rongcloud.im.uikit.custom.component.CustomChatListHeaderSelectComponent />.

   Before change:

   <?xml version="1.0" encoding="utf-8"?>
   <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
           android:orientation="vertical"
           android:layout_width="match_parent"
           android:layout_height="match_parent">
   
           <com.rongcloud.im.uikit.chatlist.component.ChatListHeaderSelectComponent
               android:id="@+id/rc_header_select_component"
               android:layout_width="match_parent"
               android:layout_height="match_parent" />
   
           // Other components xx
   
   </FrameLayout>

   After change:

   <?xml version="1.0" encoding="utf-8"?>
   <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
           android:orientation="vertical"
           android:layout_width="match_parent"
           android:layout_height="match_parent">
   
           // Only replace the custom component, other components need to be retained (Note: do not modify the android:id of the component)
           <com.rongcloud.im.uikit.custom.component.CustomChatListHeaderSelectComponent
               android:id="@+id/rc_header_select_component"
               android:layout_width="match_parent"
               android:layout_height="match_parent" />
   
           // Other components xx
   
   </FrameLayout>

Modifying the Shape of Conversation List Avatars

Each conversation item in the conversation list displays an avatar icon, i.e., the conversation avatar (not the avatar in the message list within the chat page). One-to-one chats display the other user's avatar, group chats display the group avatar, and aggregated conversations display the default avatar or an avatar actively set by the application. Global IM UIKit supports controlling the avatar style in the conversation list separately through Global IM UIKit's global configuration.

The conversation avatar is displayed as a circle by default and can be modified to a rectangle. The default avatar size is 58dp*58dp. Please call the following code for settings after App initialization:

   ConfigCenter.getFeatureConfig().setKitImageEngine(new GlideKitImageEngine() {
            @Override
            public void loadChatListPortrait(@NonNull Context context, @NonNull String url, @NonNull ImageView imageView, Conversation conversation) {
                Glide.with(context).load(url)
                        .apply(RequestOptions.bitmapTransform(new CircleCrop()))
                        .into(imageView);
            }
        });

To modify the avatar style displayed on messages within the chat page, please refer to Conversation Page.

Adding a Custom Empty Layout

Global IM UIKit's ChatListModule supports customizing the empty view in the conversation list page.

1. Method 1: Copy global IM Kit's rc_page_status_component.xml to the main project's res/layout and implement your own UI view.
2. Method 2: Inherit Global IM UIKit's PageStatusComponent to create a subclass, override onCreateView to implement your own UI view, and replace the original component in rc_chat_list_module.xml with the custom component.

Displaying Network Connection Status Prompts

When the connection is disconnected or reconnected, the SDK will display a connection status prompt bar at the top of the conversation list page and the conversation page.

If you need to disable this prompt on the conversation list page, please call the following code for settings after App initialization:

ConfigCenter.setShowConnectingStatus(false)

Clearing Notification Bar Notifications

Global IM UIKit supports clearing all notifications in the notification panel when opening the conversation list page and the conversation page. This switch is turned off by default in Global IM UIKit, i.e., notifications are not cleared.

If you need to clear notifications when on the conversation list page, please call the following code for settings after App initialization:

ConfigCenter.getChatListConfig().setWipeOutNotificationMessage(true)

Customizing UI via XML Resources

Global IM UIKit supports changing the display style of the conversation list and its conversation items. If the default display style does not meet your needs, you can modify the background, font color, or adjust the position of components in the layout by modifying the XML resource files.

Global IM UIKit Resource File	Location	Description
rc_chat_list_activity.xml	res/layout	The resource file for the conversation list page's Activity. Copy the XML resource file provided by Global IM UIKit and create a file with the same name under /res/layout in the application project.
rc_chat_list_module.xml	res/layout	The resource file for ChatListFragment. It consists of various Components. Copy the XML resource file provided by Global IM UIKit and create a file with the same name under /res/layout in the application project.
rc_item_chat_list.xml	res/layout	The display style of each conversation (item) in the conversation list. Copy the XML resource file provided by Global IM UIKit and create a file with the same name under /res/layout in the application project.

tip

Do not delete the Views in the XML or modify the IDs when making changes, as this may cause the SDK to crash.

Customizing the Display Template for Conversation Items

The table below lists the built-in conversation list item display templates in Global IM UIKit. If you need to modify the display logic of conversation list items, it is recommended to customize the display template and register it for use.

Template Class Name	Applicable Scenarios
PrivateChatListItemProvider.java	Display template for one-to-one conversations.
BaseChatListItemProvider.java	Base template for conversations, the default template. Conversations that do not match other templates will be displayed using this template.

1. Create CustomChatListProvider, inheriting the conversation template base class BaseChatListItemProvider.

2. Override isItemViewType() and other methods that need customization.

   public class CustomChatListProvider extends BaseChatListItemProvider {
       @Override
       public boolean isItemViewType(BaseChatModel item) {
           // Based on business needs, return true if the item is a conversation that this template needs to handle, otherwise return false
           // Here, a custom private chat conversation template is used as an example
           return item.mCore.getConversationType().equals(Conversation.ConversationType.PRIVATE);
       }
   
       @Override
       public ViewHolder onCreateViewHolder(ViewGroup parent, int viewType) {
           // Customize based on business needs
           return super.onCreateViewHolder(parent, viewType);
       }
   
       @Override
       public void bindViewHolder(ViewHolder holder, BaseChatModel model, int position, List<BaseChatModel> list, IViewProviderListener<BaseChatModel> listener) {
           // Customize based on business needs
           super.bindViewHolder(holder, model, position, list, listener);
       }
   }

3. Register the custom template or replace the SDK's built-in template.

   // Get the conversation template manager
   ProviderManager<BaseChatModel> providerManager = ConfigCenter.getChatListConfig().getProviderManager();
   
   // Replace the SDK's original private chat conversation display template with the custom template
   providerManager.replaceProvider(PrivateChatListItemProvider.class, new CustomChatListProvider());
   
   // Register a custom template
   providerManager.addProvider(new CustomSystemConversationProvider());