CollectionKit

Reimagining UICollectionView

A modern Swift framework for building composable data-driven collection view.

Migration Guide

Features

Rewritten UICollectionView on top of UIScrollView.
Automatically diff data changes and update UI.
Superb performance through cell reuse, batched reload, visible-only diff, & the use of swift value types.
Builtin layout & animation systems specifically built for collections.
Composable sections with independent layout.
Strong type checking powered by Swift Generics.

Install

# CocoaPods
pod "CollectionKit"

# Carthage
github "SoySauceLab/CollectionKit"

Getting Started

To start using CollectionKit, use CollectionView in place of UICollectionView. CollectionView is CollectionKit's alternative to UICollectionView. You give it a Provider object that tells CollectionView how to display a collection.

The simpliest way to construct a provider is by using BasicProvider class.

BasicProvider

To build a BasicProvider, here is what you need:

DataSource
- an object that supplies data to the BasicProvider.
ViewSource
- an object that maps each data into a view, and update the view accordingly
SizeSource
- an function that gives the size for each cell.

It sounds complicated, but it really isn't. Here is a short example demostrating how it all works.

let dataSource = ArrayDataSource(data: [1, 2, 3, 4])
let viewSource = ClosureViewSource(viewUpdater: { (view: UILabel, data: Int, index: Int) in
  view.backgroundColor = .red
  view.text = "\(data)"
})
let sizeSource = { (index: Int, data: Int, collectionSize: CGSize) -> CGSize in
  return CGSize(width: 50, height: 50)
}
let provider = BasicProvider(
  dataSource: dataSource,
  viewSource: viewSource,
  sizeSource: sizeSource
)

//lastly assign this provider to the collectionView to display the content
collectionView.provider = provider

Note that we used ArrayDataSource & ClosureViewSource here. These two classes are built-in to CollectionKit, and should be able to serve most jobs. You can implement other dataSource and viewSource as well. Imagine implementing a NetworkDataSource in your project, that retrives json data and parse into swift objects.

Reload

It is easy to update the CollectionView with new data.

dataSource.data = [7, 8, 9]

This will trigger an update of the CollectionView that is served by this dataSource.

Note that append and other array mutating methods will also work.

dataSource.data.append(10)
dataSource.data.append(11)
dataSource.data.append(12)

We updated the array three times in this example. Each update is triggering a reload. You might be thinking that this is very computational intensive, but it isn't. CollectionKit is smart enough to only update once per layout cycle. It will wait until the next layout cycle to actually reload.

After executing the 3 lines above, CollectionView will still show [7, 8, 9]. But once the current run loop cycle is completed, CollectionView will update immediately. Your user won't notice any lag from this process.

To trigger an update immediately, you can call collectionView.reloadData() or provider.reloadData() or dataSource.reloadData().

To make collectionView reload on the next layout cycle, you can call collectionView.setNeedsReload() or provider.setNeedsReload() or dataSource.setNeedsReload(). You might already noticed, once you update the array inside ArrayDataSource, it is basically calling setNeedsReload() for you.

Note that if you assign an array to the dataSource and later update that array instead. It won't actually update the CollectionView

var a = [1, 2 ,3]
dataSource.data = a
a.append(5) // won't trigger an update be cause dataSource.data & a is now two different array.
a = [4 ,5 ,6] // also won't trigger an update

Layout

Up to this point, the collection is still a bit ugly to look at. Every cell is left aligned and doesn't have space in between. You might want the views to be evenly spaced out, or you might want to add some spacing in between items or lines.

These can be achieved with Layout objects. Here is an example.

provider.layout = FlowLayout(spacing: 10, justifyContent: .center)

FlowLayout is a Layout class that it built-in to CollectionKit. There are many more built-in layouts including WaterfallLayout & RowLayout. You can also easily create your own layout.

FlowLayout is basically a better UICollectionViewFlowLayout that aligns items in row by row fashion. It supports lineSpacing, interitemSpacing, alignContent, alignItems, & justifyContent.

Every layout also supports inset(by:) and transposed() methods.

inset(by:) adds an outer padding to the layout and return the result layout as InsetLayout.

let inset = UIEdgeInset(top: 10, left: 10, bottom: 10, right: 10)
provider.layout = FlowLayout(spacing: 10).inset(by: inset)

transposed() converts a vertical layout into a horizontal layout or vice-versa. It returns the original layout wrapped inside a TransposedLayout

provider.layout = FlowLayout(spacing: 10).transposed()

You can also use them together like

let inset = UIEdgeInset(top: 10, left: 10, bottom: 10, right: 10)
provider.layout = FlowLayout(spacing: 10).transposed().inset(by: inset)

There can be a lot to talk about with Layouts. We will create more tutorial later to teach you how to create your own layout and show you some advance usages. In the mean time, feel free to dive in the source code. I promise you it is not complecated at all.

Composing (ComposedProvider)

The best feature of CollectionKit, is that you can freely combine providers together into multiple sections within one CollectionView. And it is REALLY EASY to do so.

let finalProvider = ComposedProvider(sections: [provider1, provider2, provider3])

collectionView.provider = finalProvider

To update individual sections, just update its own dataSource.

provider2DataSource.data = [2]

You can also live update sections around.

finalProvider.sections = [provider2, provider3, provider1]

Or add more to it.

finalProvider.sections.append(provider4)

You can even put ComposedProvider into another ComposedProvider no problem.

let trulyFinalProvider = ComposedProvider(sections: [finalProvider, provider5])

collectionView.provider = trulyFinalProvider

How cool is that!

Animation

CollectionKit offers a animation system which allows you to create fancy animations and adjust how cells are displayed.

Here are some examples of custom animators that is included in the example project. They can be used in combination with any layout. Here we are using a transposed waterfall layout.

Wobble	Edge Shrink	Zoom

Animator can also perform animations when a cell is added/moved/deleted. Here is an example showing a 3d scale animation with a cascading effect.

It is easy to use an Animator. You can assign it to providers, cells, or to entire CollectionView.

// apply to the entire CollectionView
collectionView.animator = ScaleAnimator()

// apply to a single section, will override CollectionView's animator
provider.animator = FadeAnimator()

// apply to a single view, will take priority over all other animators
view.collectionAnimator = WobbleAnimator()

Note: that in order to use WobbleAnimator, you have to include pod "CollectionKit/WobbleAnimator" subspec to your podfile.

Please checkout the example project to see many of these examples in action.

Questions? Want to contribute?

Join our public Slack!

SoySauceLab / CollectionKit

readme