1 of 6

Overriding UIKit Behaviour

UIKIT allows the default behaviour to be overridden by custom logic.

Feed UI Settings

Post Sharing
Post Rendering

Post Sharing

This setting allows you to control where a post can be shared to based on the post origin.

There are five possible targets that a post can be shared to

My feed - The post can be shared to my feed. This option will enable "Share to my timeline" menu when user clicks share button.

Public community - The post can be shared to any public community. This option will enable "Share to group" menu when user clicks share button.

Private community - The post can be shared to any private community. This option will enable "Share to group" menu when user clicks share button.

External - The post can be shared externally. This option will enable "More options" menu when user clicks share button.

Origin - The post can be shared within the community feed that it was created. If the post was created in either public or private community, this option will enable "Share to group" menu when user clicks share button.

There are four possible origins

My feed post - Posts that were created on my feed. By default, possible sharing targets are My feed, Public community, and Private community.

User feed post - Posts that were created on any other users' feed. By default, possible sharing targets are My feed, Public community, and Private community.

Public community feed post - Posts that were created on any public community. By default, possible sharing targets are My feed, Public community, and Private community.

Private community feed post - Posts that were created on any private community. By default, possible sharing target is Origin.

Usage

You can select a set of targets for each post origin.

Based on Post sharing settings, there are up to three post sharing events that can be emitted by UIKit.

Share to my timeline - an event emitted when a user clicks on "Share to my timeline" button.

Share to group - an event emitted when a user clicks on "Share to group" button.

Share externally - an event emitted when a user clicks "More options" button.

Usage

You can choose to intercept one or all of the events and apply your custom behavior.

Post Rendering

Custom Post Rendering

UIKit provides default renderers for the core data types: text, image, and file. It also provides a way to render your own UI for your custom post.

Post Structure:

A single post UI is composed of 1 or more UITableViewCell. This allows reusability of cell components such as header or footer which can be shared by different kinds of posts.

This is an example of simple text post which contains 3 tableview cell. Top cell represents the header, middle cell contains text content and bottom cell is footer cell.

Creating UI for custom posts :

There are 3 steps involved in creating custom post renderer.

Step 1: Create your UI using UITableView cells.

Step 2: Compose a post UI component. For this create a component which conforms to AmityPostComposable protocol.

You can also use our default header cell AmityPostHeaderTableViewCell & default footer cell AmityPostFooterTableViewCell in your custom post component.

Step 3: Register your custom cell & implement datasource.

Event Handling

Custom Event Handler

There are many pages and actions on AmityUIKit. Pages can be nested inside others and it would be hard for overriding events on the nested pages. In order to solve this problem, we provide EkoEventHandler which is a behavior controller for actions that happen in UIKit.

Supported Events

Example

When a user clicks on the user profile avatar at the post creator area, UIKit will open User profile page

However, you can intercept the event and define your own logic following the example below.

Usage

To customize message cell layouts, please follow these instructions:

Create a subclass of UITableViewCell and conform it to AmityMessageCellProtocol
To bind message data to UI, implement display(message:). You can also implement height(for message:boundingWidth:) to specify the cell height. We've included some examples below for static-height calculation and dynamic-height calculation as reference
Subclass AmityEventHandler, and override its default functions channelDidTap(from:channelId:) and conform to AmityMessageListDataSource.

class CustomChannelEventHandler: AmityChannelEventHandler {
    
    override func channelDidTap(from source: AmityViewController, channelId: String) {
        let viewController = AmityMessageListViewController.make(channelId: channelId, settings: settings)
        viewController.dataSource = self
        source.navigationController?.pushViewController(viewController, animated: true)
    }
    
}

extension CustomChannelEventHandler: AmityMessageListDataSource {
    func cellForMessageTypes() -> [AmityMessageTypes : AmityMessageCellProtocol.Type] {
	// determine which cell represents for which message type.
        return [
            .imageIncoming: StaticHeightMessageCell.self,
	.textIncoming: DynamicHeightMessageCell.self
        ]
    }
}

4. Assign a class instance through a set function of AmityUIKitManager

AmityUIKitManager.set(channelEventHandler: CustomChannelEventHandler())

Customizing Cells with Different Layouts

Static-Height Cell Layout

You can use static-height cell layout types for static content, where the cell height is fixed and will not be scaled regardless of the data being received.

Below is an example of how you can configure a static-height cell layout. In this example, we're assuming that the image message is a class named StaticHeightMessageCell.

class StaticHeightMessageCell: UITableViewCell, AmityMessageCellProtocol {
    
    func display(message: AmityMessageModel) {
        // configure cell here, e.g. set message text to label.
    }
    
    static func height(for message: AmityMessageModel, boundingWidth: CGFloat) -> CGFloat {
        // Calculate the actualHeight by summing up all components height.
        let actualHeight: CGFloat = 34 + 228 + 34 // 296
        
        return actualHeight
    }
    
}

Dynamic-Height Cell Layout

You can use dynamic-height cell layout when you require your cell height to expand dynamically according to the data (e.g. label expands upon strings).

Dynamic-height cell layouts require more complexity in height calculation. Let's look at a text message as an example, where the height of the cell needs to expand dynamically to display the full content.

class DynamicHeightMessageCell: UITableViewCell, AmityMessageCellProtocol {
    
    func display(message: AmityMessageModel) {
        // configure cell here, e.g. set message text to label.
    }
    
    static func height(for message: AmityMessageModel, boundingWidth: CGFloat) -> CGFloat {
        
        // (1) Calculate the width that is reserved by other components.
        let reservedWidth: CGFloat = 12 + 40 + 12 + 8 + 8 + 76 // 156
        
        // (2) Calculate the maximum possible width that content can fit in.
        //
        // A `boundingWidth` is a width that returns from table view. In this example is 375.
        // To get the possible with. We need to subtract it by (1).
        let possibleWith: CGFloat = boundingWidth - reservedWidth // 375 - 156 = 210
        
        // (3) Calculate the content height using font and string.
        let messageHeight = message.text?.height(withConstrainedWidth: possibleWith, font: AmityFontSet.body) ?? 0.0
        
        // (4) Calculate the height that is reserved by other component.
        let reservedHeight: CGFloat = 34 + 8 + 8 + 34 // 84
        
        // (5) Calculate the actualHeight by summing up (3) and (4).
        let actualHeight: CGFloat = messageHeight + reservedHeight
        
        return actualHeight
    }
    
}

Post Sharing

This setting allows you to control where a post can be shared to based on the post origin.

There are five possible targets that a post can be shared to

My feed - The post can be shared to my feed. This option will enable "Share to my timeline" menu when user clicks share button.

Public community - The post can be shared to any public community. This option will enable "Share to group" menu when user clicks share button.

Private community - The post can be shared to any private community. This option will enable "Share to group" menu when user clicks share button.

External - The post can be shared externally. This option will enable "More options" menu when user clicks share button.

There are four possible origins

My feed post - Posts that were created on my feed. By default, possible sharing targets are My feed, Public community, and Private community.

User feed post - Posts that were created on any other users' feed. By default, possible sharing targets are My feed, Public community, and Private community.

Public community feed post - Posts that were created on any public community. By default, possible sharing targets are My feed, Public community, and Private community.

Private community feed post - Posts that were created on any private community. By default, possible sharing target is Origin.

Usage

You can select a set of targets for each post origin.

// In your AppDelegate class

// Ensure post created in private community cannot be shared elsewhere
let privateCommunityShringTargets: Set<AmityPostSharingTarget> = [.originFeed]

// Allow post created by any other user to be shared anywhere
let publicCommunityShringTargets: Set<AmityPostSharingTarget> = [.myFeed, .originFeed, .publicCommunity, .external]

// Allow post created by logged-in user to be shared anywhere
let myFeedShringTargets: Set<AmityPostSharingTarget> = [.myFeed, .originFeed, .external]
        
let sharingSettings = AmityPostSharingSettings(privateCommunity: privateCommunityShringTargets, publicCommunity: publicCommunityShringTargets, myFeed: myFeedShringTargets)
        
AmityUIKitManager.feedUISettings.setPostSharingSettings(settings: sharingSettings)

Based on Post sharing settings, there are up to three post sharing events that can be emitted by UIKit.

Share to my timeline - an event emitted when a user clicks on "Share to my timeline" button.

Share to group - an event emitted when a user clicks on "Share to group" button.

Share externally - an event emitted when a user clicks "More options" button.

Usage

You can choose to intercept one or all of the events and apply your custom behavior.

// In your AppDelegate class

// Create custom event handler class
class CustomFeedEventHandler: AmityFeedEventHandler {
    // Event handler for more options
    override func sharePostDidTap(from source: AmityViewController, postId: String) {
        // generate a link 
        let urlString = "https://amity.co/posts/\(postId)"
        guard let url = URL(string: urlString) else { return }
        
        // create AmityActivityController to share generated link
        let viewController = AmityActivityController.make(activityItems: [url])
        source.present(viewController, animated: true, completion: nil)
    }
    
    // Event handler for share post to group
    override func sharePostToGroupDidTap(from source: AmityViewController, postId: String) {
        // Handle event here
    }
    
    // Event handler for share to my timeline
    override func sharePostToMyTimelineDidTap(from source: AmityViewController, postId: String) {
        // Handle event here
    }
}

...

AmityUIKitManager.feedUISettings.eventHandler = CustomFeedEventHandler()

Example

When a user clicks on the user profile avatar at the post creator area, UIKit will open User profile page

However, you can intercept the event and define your own logic following the example below.

Usage

To customize message cell layouts, please follow these instructions:

Create a subclass of UITableViewCell and conform it to AmityMessageCellProtocol
To bind message data to UI, implement display(message:). You can also implement height(for message:boundingWidth:) to specify the cell height. We've included some examples below for static-height calculation and dynamic-height calculation as reference
Subclass AmityEventHandler, and override its default functions channelDidTap(from:channelId:) and conform to AmityMessageListDataSource.

class CustomChannelEventHandler: AmityChannelEventHandler {
    
    override func channelDidTap(from source: AmityViewController, channelId: String) {
        let viewController = AmityMessageListViewController.make(channelId: channelId, settings: settings)
        viewController.dataSource = self
        source.navigationController?.pushViewController(viewController, animated: true)
    }
    
}

extension CustomChannelEventHandler: AmityMessageListDataSource {
    func cellForMessageTypes() -> [AmityMessageTypes : AmityMessageCellProtocol.Type] {
	// determine which cell represents for which message type.
        return [
            .imageIncoming: StaticHeightMessageCell.self,
	.textIncoming: DynamicHeightMessageCell.self
        ]
    }
}

4. Assign a class instance through a set function of AmityUIKitManager

AmityUIKitManager.set(channelEventHandler: CustomChannelEventHandler())

Customizing Cells with Different Layouts

Static-Height Cell Layout

You can use static-height cell layout types for static content, where the cell height is fixed and will not be scaled regardless of the data being received.

Below is an example of how you can configure a static-height cell layout. In this example, we're assuming that the image message is a class named StaticHeightMessageCell.

class StaticHeightMessageCell: UITableViewCell, AmityMessageCellProtocol {
    
    func display(message: AmityMessageModel) {
        // configure cell here, e.g. set message text to label.
    }
    
    static func height(for message: AmityMessageModel, boundingWidth: CGFloat) -> CGFloat {
        // Calculate the actualHeight by summing up all components height.
        let actualHeight: CGFloat = 34 + 228 + 34 // 296
        
        return actualHeight
    }
    
}

Dynamic-Height Cell Layout

You can use dynamic-height cell layout when you require your cell height to expand dynamically according to the data (e.g. label expands upon strings).

class DynamicHeightMessageCell: UITableViewCell, AmityMessageCellProtocol {
    
    func display(message: AmityMessageModel) {
        // configure cell here, e.g. set message text to label.
    }
    
    static func height(for message: AmityMessageModel, boundingWidth: CGFloat) -> CGFloat {
        
        // (1) Calculate the width that is reserved by other components.
        let reservedWidth: CGFloat = 12 + 40 + 12 + 8 + 8 + 76 // 156
        
        // (2) Calculate the maximum possible width that content can fit in.
        //
        // A `boundingWidth` is a width that returns from table view. In this example is 375.
        // To get the possible with. We need to subtract it by (1).
        let possibleWith: CGFloat = boundingWidth - reservedWidth // 375 - 156 = 210
        
        // (3) Calculate the content height using font and string.
        let messageHeight = message.text?.height(withConstrainedWidth: possibleWith, font: AmityFontSet.body) ?? 0.0
        
        // (4) Calculate the height that is reserved by other component.
        let reservedHeight: CGFloat = 34 + 8 + 8 + 34 // 84
        
        // (5) Calculate the actualHeight by summing up (3) and (4).
        let actualHeight: CGFloat = messageHeight + reservedHeight
        
        return actualHeight
    }
    
}

Post Rendering

Custom Post Rendering

UIKit provides default renderers for the core data types: text, image, and file. It also provides a way to render your own UI for your custom post.

Post Structure:

A single post UI is composed of 1 or more UITableViewCell. This allows reusability of cell components such as header or footer which can be shared by different kinds of posts.

This is an example of simple text post which contains 3 tableview cell. Top cell represents the header, middle cell contains text content and bottom cell is footer cell.

Creating UI for custom posts :

There are 3 steps involved in creating custom post renderer.

Step 1: Create your UI using UITableView cells.

class MyPostHeaderCell: UITableViewCell { 
    // ...
}

class MyPostContentCell: UITableViewCell {
    // ...
}

Step 2: Compose a post UI component. For this create a component which conforms to AmityPostComposable protocol.

struct MyCustomPostComponent: AmityPostComposable {
    
    var post: AmityPostModel
    
    // Post data model which you can use to render ui.
    init(post: AmityPostModel) {
        self.post = post
    }
    
    func getComponentCount(for index: Int) -> Int {
        return 2
    }
    
    func getComponentCell(_ tableView: UITableView, at indexPath: IndexPath) -> UITableViewCell {
        switch indexPath.row {
        case 0:
            let cell = tableView.dequeueReusableCell(withIdentifier: "my-cell-identifier", for: indexPath) as! MyPostHeaderCell
            // ... populate cell data here
            return cell
        case 1:
            let cell = tableView.dequeueReusableCell(withIdentifier: "my-cell-identifier", for: indexPath) as! MyPostContentCell
            // ... populate cell data here
            return cell
        default:
						fatalError("indexPath is out of bound")
        }
    }
    
    // Height for each cell component
    func getComponentHeight(indexPath: IndexPath) -> CGFloat {
        return UITableView.automaticDimension
    }
}

You can also use our default header cell AmityPostHeaderTableViewCell & default footer cell AmityPostFooterTableViewCell in your custom post component.

Step 3: Register your custom cell & implement datasource.

class YourViewController: UIViewController {
    
		func showFeed() {
				// 1.
				// Register your cell here. You can register both 
				// nib as well as class itself.
				AmityFeedUISettings.shared.register(UINib(nibName: "PostThumbsupTableViewCell", bundle: nil), forCellReuseIdentifier: "PostThumbsupTableViewCell")
        AmityFeedUISettings.shared.dataSource = self

        // Showing our feed UI
				let feedViewController = AmityGlobalFeedViewController.make()
	      navigationController?.pushViewController(feedViewController, animated: true)
		}
}

extension YourViewController: AmityFeedDataSource {
    
    // 2. 
    // Provide your rendering component for custom post.
    func getUIComponentForPost(post: AmityPostModel, at index: Int) -> AmityPostComposable? {
        switch post.dataType {
        case "your-data-type":
            return MyCustomPostComponent(post: post)
        default:
            return nil
        }
    }
}

Overriding UIKit Behaviour

Feed UI Settings

Post Sharing

Post Sharing Settings

There are five possible targets that a post can be shared to

There are four possible origins

Usage

Post Sharing Events

Usage

Post Rendering

Custom Post Rendering

Post Structure:

Creating UI for custom posts :

Event Handling

Custom Event Handler

Supported Events

Example

Usage

Customizing Cells with Different Layouts

Feed UI Settings

Overriding UIKit Behaviour

Post Sharing

Post Sharing Settings

There are five possible targets that a post can be shared to

There are four possible origins

Usage

Post Sharing Events

Usage

Event Handling

Custom Event Handler

Supported Events

Example

Usage

Customizing Cells with Different Layouts

Post Rendering

Custom Post Rendering

Post Structure:

Creating UI for custom posts :