DOCSEARCHbyAlgolia
Submit Docs

ChatLayout Documentation

repository·master·Indexed 21 days ago

https://github.com/ekazaev/chatlayout

A custom UICollectionViewLayout for iOS designed as a high-performance alternative to MessageKit for building chat interfaces. It supports dynamic cell sizes, animated updates, sticky cells, and agent mode without requiring view controller hacks or rotating the collection view. ChatLayout is data-agnostic and compatible with UICollectionViewDiffableDataSource, DifferenceKit, and Texture. It can be installed via CocoaPods, Carthage, or Swift Package Manager.

Tokens
1.8K
Snippets
2
Records
13
Agent score
75%

What's inside ChatLayout

  1. Overview of ChatLayout features and architecture

    master

    ChatLayout is a custom UICollectionViewLayout designed as an alternative to MessageKit. Unlike many chat libraries, it does not require you to use a specific UIViewController or a modified UICollectionView. You instantiate your own standard UIKit components and simply apply the ChatLayout to your UICollectionView.

    Key Features

    • Dynamic Cell Sizes: Supports cells with varying heights using Auto Layout.
    • Smooth Animations: Handles animated insertion, deletion, reloading, and moving of items.
    • Content Anchoring: Keeps the content of the last visible item at the top or bottom during updates.
    • Precise Scrolling: Provides tools for accurate scrolling to specific items.
    • Sticky Cells: Supports pinned cells that behave like headers or footers.
    • Agent Mode: Built-in support for agent-style chat interfaces.

    Architectural Principles

    • No View Controller Hacks: It does not rotate your UICollectionView upside-down or rely on UICollectionViewFlowLayout modifications. This allows you to use standard UIKit features like adjustedContextInsets normally.
    • Data Agnostic: It does not enforce a specific data model. You can use any diffing algorithm (like DifferenceKit) or UICollectionViewDiffableDataSource to manage your data.
    • Layout-Centric: It is strictly a UICollectionViewLayout. It does not handle keyboard appearance or input controls; you are responsible for updating the contentInsets of your UICollectionView when the keyboard appears.

  2. Using ChatLayout with Texture

    master

    You can use ChatLayout with Texture to improve Auto Layout performance.

    Note: The default Texture wrapper in the library is hardcoded to work with UICollectionViewFlowLayout. To use ChatLayout with Texture, you must manually implement ChatLayoutDelegate and propagate the node size yourself.

  3. How to use ChatLayout with UICollectionViewDiffableDataSource

    master
    Because ChatLayout is a standard UICollectionViewLayout, it is fully compatible with UICollectionViewDiffableDataSource. You can send any update commands through the data source, and ChatLayout will process them as part of the collection view's update cycle.

  4. Install ChatLayout

    master

    ChatLayout can be installed using CocoaPods, Carthage, or Swift Package Manager (SwiftPM).

    CocoaPods

    To install the full package:

    pod 'ChatLayout'

    If you only need the layout engine without the additional components, install only the core:

    pod 'ChatLayout/Core'

  5. Overview of ChatLayout

    master

    ChatLayout is a custom UICollectionViewLayout designed as an alternative to MessageKit. It provides full control over chat presentation while leveraging all standard UICollectionView tools.

    Key features include:

    • Support for dynamic cell sizes.
    • Animated insertion, deletion, reloading, and moving of items.
    • Content persistence: keeps the last visible item at the top or bottom during updates.
    • Precise scrolling tools for specific items.
    • Generic container views to simplify custom item implementation.
    • Pinned (sticky) cells that can function as headers or footers.
    • Agent mode support.

  6. Integration with UICollectionViewDiffableDataSource

    master
    ChatLayout is compatible with UICollectionViewDiffableDataSource. It can process any update commands sent to your UICollectionView, allowing you to use modern diffable data sources for managing your chat messages.

  7. Understanding ChatLayout's design philosophy

    master

    ChatLayout is strictly a UICollectionViewLayout. This design choice provides several benefits:

    • No Controller Overrides: You do not need to extend or override UIViewController or UICollectionView. You instantiate and use them as you normally would.
    • Standard UIKit Behavior: It does not rely on a modified UICollectionViewFlowLayout and does not rotate the collection view upside-down. This allows you to use standard UIKit implementations like adjustedContextInsets without hacks.
    • Flexible Sizing: You can use Auto Layout constraints for cell sizes. While the layout calculates sizes at runtime, providing estimated sizes will improve performance.
    • Data Agnostic: It does not enforce a specific data model. You can use any model and any diffing algorithm (e.g., DifferenceKit). You only need to implement a standard UICollectionViewDataSource.
    • Customizable UI: It does not enforce specific UIView types for cells, though generic container views are provided to speed up development.
    • Full Control over Input/Keyboard: ChatLayout does not handle keyboard appearance or input controls. You are responsible for updating the contentInsets of your UICollectionView when the keyboard appears.

  9. Key Features of ChatLayout

    master

    ChatLayout provides several specialized features for chat UIs:

    • Dynamic Cell Sizes: Supports cells with varying heights.
    • Animated Updates: Handles animated insertion, deletion, reloading, and moving of items.
    • Content Persistence: Keeps the content of the last visible item at the top or bottom of the UICollectionView during updates.
    • Precise Scrolling: Tools for accurate scrolling to specific items.
    • Generic Containers: Includes generic container views to speed up custom item implementation.
    • Sticky Cells: Supports pinned cells that function like headers or footers.
    • Agent Mode: Support for agent-style chat interfaces.

  11. Install ChatLayout via CocoaPods

    master

    You can install ChatLayout using CocoaPods. You have two options depending on whether you need the extra UI components or just the layout logic:

    1. Full Package: Installs the layout and additional generic container views.
      pod 'ChatLayout'
    2. Core Only: Installs only the layout engine, excluding additional components.
      pod 'ChatLayout/Core'
    # Install full package
pod 'ChatLayout'

# Install layout only
pod 'ChatLayout/Core'

  12. Troubleshoot unexpected animations in ChatLayout

    master

    If you encounter strange or unexpected animations during updates, the issue is likely in the commands being sent to UICollectionView.performBatchUpdates.

    Common causes include:

    • Incorrectly configured diffing algorithms (e.g., DifferenceKit) sending delete/insert commands when a reload was expected.

    Debugging Tip: Add a print statement inside the ChatLayout.prepare(forCollectionViewUpdates:) method to inspect the updateItems being processed. ChatLayout executes exactly what the UICollectionView receives; it does not know your intended data state.