Home

Overview

The functionality is split into two modules:

• SectionKit:

  This package contains the core functionality.

  Please note: ListCollectionViewAdapter and ListSectionController will not animate updates to the list of sections/items and call reloadData()/reloadSections(_:) respectively. On iOS 13+ you can use the FoundationDiffingListCollectionViewAdapter or FoundationDiffingListSectionController
  to get animated updates. When targeting iOS versions lower than 13, you can implement your own difference calculation by overriding calculateUpdate(from:to:) or you can use a class contained in DiffingSectionKit.

  Besides that, the SingleSectionCollectionViewAdapter, SingleModelSectionController and SingleItemSectionController support animated updates out of the box.

• DiffingSectionKit:

  This package extends SectionKit by containing three more base classes, DiffingListCollectionViewAdapter, DiffingListSectionController and ManualDiffingListSectionController. They simply override calculateUpdate(from:to:) where the difference between the old and new data is calculated using DifferenceKit. Therefore, animations are performed when the list of sections/items is updated (separate inserts/deletes/moves instead of reloadData()/reloadSections(_:)).

Supported APIs

The currently supported APIs are:

• UICollectionViewDataSource
• UICollectionViewDataSourcePrefetching
• UICollectionViewDelegate
• UICollectionViewDragDelegate
• UICollectionViewDropDelegate
• UICollectionViewDelegateFlowLayout
• UIScrollViewDelegate

Other APIs can be easily added by extending ListCollectionViewAdapter or SingleSectionCollectionViewAdapter.

CollectionViewAdapter

• ListCollectionViewAdapter:

  A CollectionViewAdapter that contains a list of sections. Changes to that list will result in a call to reloadData() on the underlying UICollectionView.

• SingleSectionCollectionViewAdapter:

  A CollectionViewAdapter that contains a single section. It will perform animated updates to the list of sections of the UICollectionView, but updates within the section are handled by the respective SectionController.

• FoundationDiffingListCollectionViewAdapter (iOS 13+):

  A CollectionViewAdapter that contains a list of sections. Separate inserts/deletes/moves will be performed when the list of sections change using Foundation.CollectionDifference (which is only available on iOS 13+). Updates within a section are handled by the respective SectionController.

• DiffingListCollectionViewAdapter (DiffingSectionKit):

  A CollectionViewAdapter that contains a list of sections. Separate inserts/deletes/moves will be performed when the list of sections change using DifferenceKit. Updates within a section are handled by the respective SectionController.

SectionController

• BaseSectionController:

  A base class that implements overridable methods/properties from the following protocols:

  • SectionController
  • SectionDataSource
  • SectionDataSourcePrefetchingDelegate (iOS 10+)
  • SectionDelegate
  • SectionFlowDelegate
  • SectionDragDelegate (iOS 11+)
  • SectionDropDelegate (iOS 11+)

• SingleModelSectionController<Model>:

  A SectionController that displays data of a single model. Unless overridden, numberOfItems will always be 1 and a change to its model will perform a call to reloadItems(at:).

  Warning: If numberOfItems is overridden, calculateUpdate(from:to:) needs to be overridden as well.

  This SectionController is typically used when there are one or multiple different cells from a single model. If however all items are semantically similar and one could derive an array of them, it is recommended to use the ListSectionController instead.

• SingleItemSectionController<Model, Item>:

  In contrast to the SingleModelSectionController, this SectionController will conditionally display 0 or 1 item and animate this change accordingly.

  Warning: If numberOfItems is overridden, calculateUpdate(from:to:) needs to be overridden as well.

  This SectionController is typically used when one item should be displayed conditionally. If multiple items should be displayed, it is recommended to use the ListSectionController instead.

• ListSectionController<Model, Item>:

  A SectionController that contains a list of items. Changes to that list will result in a call to reloadSections(_:) on the underlying UICollectionView.

  This SectionController is typically used when there are multiple semantically similar items of a model to be displayed and the list of items (almost) never changes or should not perform animated updates.

• FoundationDiffingListSectionController<Model, Item: Hashable> (iOS 13+):

  A SectionController that contains a list of items and animate the difference whenever there is an update.

  This SectionController is typically used when there are multiple semantically similar items of a model to be displayed and the list of items may dynamically change.

• DiffingListSectionController<Model, Item: Differentiable> (DiffingSectionKit):

  A SectionController that contains a list of items and animate the difference whenever there is an update.

  This SectionController is typically used when there are multiple semantically similar items of a model to be displayed and the list of items may dynamically change.

• ManualDiffingListSectionController<Model, Item> (DiffingSectionKit):

  A SectionController that contains a list of items and animate the difference whenever there is an update.

  This SectionController is typically used when there are multiple semantically similar items of a model to be displayed and the list of items may dynamically change.

  Note: Compared to the DiffingListSectionController this class doesn't have a Differentiable constraint on the generic Item type, instead it requires closures in the init to get diffing information for an item.