Customize fragments using builder

Sendbird UIKit for Android provides a simple interface to customize various fragments, primarily through the Builder class. This page walks you through the process to effectively customize fragments for your app.

The UIKit utilizes Android's concept of fragment which represents the reusable portion of a screen for your app's UI.

We use fragments for the following reasons:

• Modularity: Fragments allow you to modularize your code, making complex UIs more manageable and organized.
• Adaptability: On devices with larger screens, you can display multiple fragments in a single activity as a multi-pane interface.
• Reusability: You can use the same fragment in different activities, promoting code reuse.

In the context of Sendbird UIKit, you can have a ChannelListFragment to display a list of channels or a ChannelFragment to display messages within a specific channel. By utilizing fragments, we enable developers to customize and embed chat functionalities seamlessly into your app.

Fragment represents a modular piece of an activity. Every fragment has a 1-to-1 relationship with an activity. The activity is responsible for instantiating and presenting the fragment. It has its own lifecycle, receives its own input events, and can be added or removed while the activity is running.

The Fragment is organized within a single module, in which there could be several Components defined within it. This organization provides a cohesive structure for the UI components and their interactions.

A ViewModel is an architecture component of the UIKit that handles the data for the UI and prepares it for presentation. The UIKit fragments bridge the gap between the component configured in the module and the ViewModel's data.

The following are some example cases of when to consider customization:

• Event modifications: When you need to alter the pre-configured functions between the components in the module.
• Passing custom events or data: When you need to add custom events, functions, or data types not present in the ViewModel or Fragment.
• Utilizing the builder: When you want to easily modify options or data using the builder interface provided for each fragment.

The following table shows a list of fragments that the UIKit provides.

Every fragment comes with its own Builder class. Through the interface provided by each Builder, you can modify the fragment's settings or data. In the sample code below, the ChannelFragment.Builder is an instance of the Builder pattern designed for the ChannelFragment class in Sendbird UIKit. Using this Builder, you can set various properties of the fragment which in this case uses the setHeaderTitle() method to change the title of the channel to "Custom Title".

val fragment = ChannelFragment.Builder(channelUrl)
      .setHeaderTitle("Custom Title")
      .build()

It's possible to directly instantiate a Fragment without the Builder. You can directly create a fragment for each screen by inhering from the Fragment. In the sample code below, we are providing an entirely custom fragment CustomChannelFragment() to the Builder.

// How to create a custom Fragment with the required arguments needed by UIKit.
val fragment = ChannelFragment.Builder(channelUrl)
      .setCustomFragment(CustomChannelFragment())
      .build()

It is still recommended to use the provided Builder class because the builder ensures all required arguments and configurations are correctly set, making the process error-free and more efficient.

You can integrate the custom fragments globally within the UIKit framework using FragmentProviders. Each provider provides the arguments for creating a fragment. Additionally, every time a fragment for the same activity is created, the same Fragment class will be used. It's recommended to integrate custom fragments within the onCreate() method of your Application class. This ensures that custom configurations are consistently applied throughout the app's lifecycle.

The following code is an example of how to globally apply a custom channel fragment.

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        FragmentProviders.channel = ChannelFragmentProvider { channelUrl, args ->
            ChannelFragment.Builder(channelUrl).withArguments(args)
                .setCustomFragment(CustomChannelFragment())
                .setUseHeader(true)
                .build()
        }
    }
}

For an in-depth practical demonstration, see our sample code.