In the first and the second article, I looked at how to work with UICollectionViewCompositionalLayout and UICollectionViewDiffableDataSource. They are the main components for UICollectionView. But all of this is just a theory, how to use them in practice? How to build a complex layout with them?

This is what I will explain in this article. My solution is not universal, but using it I have handled all the requirements I came up with.

Let’s imagine that we have a library, our goal is to build a mobile app in which library clients can take and return books. In this mobile application we will have three sections:

1. Information about a client
2. Client books list
3. Library books list

In the end, the application will look like at the screenshot

Before starting developing our sections, I need to resolve one problem. From the screenshot, you can see that in different sections we have different objects and they have a different layout. With UICollectionViewDiffableDataSource we can’t do that, that’s why I will build a wrapper and it will help us.

I want to use just structures, this will be a small experiment for me, with them it will be easier to implement a Hashable protocol, but harder to store them.

Section & Cell

For a start let’s create two basic objects for our application. First will be a simple protocol Cell, this protocol will be implemented by our collection view cells. Inside it will have only one function, this function will be called by section and will configure a cell. Also, it will have an associatedtype Object, which will be passed in that function.

Second object is an abstract class Section, it will implement a Hashable protocol and this class helps us to have the common behavior for all future sections.

CollectionAdapter

CollectionAdapter is a class, it will handle our two crucial objects UICollectionViewCompositionalLayout and UICollectionViewDiffableDataSource. This adapter will store UICollectionViewDiffableDataSource and will ask for snapshots data from its delegate. As we decided in sections, we will have different elements, that’s why will use the AnyHashable structure.

The delegate will have two simple methods, the first will return all sections to our collection, second will return elements for the section. Section will provide cells for the data source, that’s why we should add a function to it.

Working with UICollectionViewCompositionalLayout is much more simple, all we have to provide is how elements will layout in the sections. In order to do this, the section must have an additional function that will return this information.

One more important function we must add to our adapter is the one that will create snapshots and send them to the datasource using the apply method. Also before that, it must register cells in a collection. ViewController will be the delegate for our adapter and will return al thel needed data. Below you can find the code for this function.

CollectionSection

I have decided that in one section I will have only one kind of elements. With this let me introduce to you a generic section class which I will use for sections — CollectionSection. This class will have two generic elements, first will be our element and second — a cell for it. This class will inherit from the Section class and will return cells and layout for our adapter.

Client Section

Regarding our requirements in this section we should have short information about the client and amount of books he has taken. So we need a cell and a model.

After this we should configure our new section and return data for it from ViewController to the adapter.

Library Books Section

Next, our section will be the section where we will show books in the library. This section will hold books and if we take one it will have a checkmark on it and also will be added to the client books section.

Cells in it will have dynamic height and grid layout. For taking and returning books we should define one method, this method will be called when we tap on the cell. It should be added to CollectionAdapter, Section, and CollectionSection.

Next step is to implement this method inside ViewController

With this small amount of code we have two sections. And if a client takes some book we will see the change in the client section.

Client Books Section

In this section will be books which client have taken from the library, the section should have horizontal scrolling and if we tap on the return button in the cell, the book should be returned to the library.

Two interesting requirement we should cover here. First, we have to have an empty view which will show that we don’t have any books at a client home. For this requirement I have decided to use the supplementary view, using UICollectionViewCompositionalLayout we can put it inside the section and it will take the whole section size. UICollectionViewCompositionalLayout is pretty smart and will draw the empty view even if it has no elements inside.

I will create a separate section, it will inherit from ClientBooksSection, this section can return a supplementary view for the collection and will show it only if the section doesn’t have elements. Section will know about that from the adapter.

Second, add additional configuration to the cell, it is because ViewController will be the delegate for the cell and react when user taps on the return button, after that a book will be returned to the library.

Summary

The bottom line for all three articles is — Apple did what they should have done a long time ago, it gives us instruments that will help in the collection development, this is good, but it is bad that it is a little bit late. As soon as you stop supporting iOS 12 you can do refactoring for your old collections using these new instruments. Full project source code you can find at Github.

In the last article, I shared my investigation of UICollectionViewCompositionalLayout. But all experienced developers know that UICollectionView contains two parts — Layout and Datasource. In this article, I will look at the second part, the instrument which also was introduced at the last WWDC — UICollectionViewDiffableDataSource.

If you have ever heard or read about the IGListKit, then UICollectionViewDiffableDataSource will also look familiar to you, as usual, Apple took some idea and presented their solution.

In this solution you can find two classes, they are doing all heavy lifting work for you — UICollectionViewDiffableDataSource and NSDiffableDataSourceSnapshot, they are both generic and tightly coupled.

UICollectionViewDiffableDataSource

The main goal for this class is to prepare all the needed data for UICollectionView. It is initialized with closure, this closure has to provide cells for the collection. In addition, you can find optional closure which could provide Supplementary View.

Also, this class can take NSDiffableDataSourceSnapshot, this is the snapshot of your datasource data, at first it will save its copy, for the second time, it will find the difference between saved copy and new snapshot and apply it to the UICollectionView automatically.

Let’s remember what we had before this nice update. We had an object, it had all our data and provided this data to a collection, this object implements UICollectionViewDataSource. It provided the number of sections, elements, cells for these elements, etc. If we had to insert, remove or move elements in a collection, we would find what changed in our data and then tell to a collection about it through these methods.

After all of this, we had to call the method performBatchUpdates or tell nothing to a collection and just call reloadData. And a lot of programmers would choose the second option because of the two reasons:

1. Sometimes it is really hard to find the difference between two arrays, for this, we should develop some algorithm.
2. Calling method performBatchUpdates you can see this very often.

Invalid update: invalid number of items in section 0. The number of items contained in an existing section after the update (1) must be equal to the number of items contained in that section before the update (1), plus or minus the number of items inserted or deleted from that section (1 inserted, 0 deleted) and plus or minus the number of items moved into or out of that section (0 moved in, 0 moved out).

If you start googling this error, you won’t find an answer fast, after some time you will probably understand what this error means that somewhere in your UICollectionViewDataSource data and in a collection data system has found the difference and can’t build a collection layout. Then you have to spend some time to find where it is and fix it.

To tell the truth, this is a kind of a nightmare for me, because I have used IGListKit for a long time, I don’t have a problem together with it :) Now we have a native solution with UICollectionViewDiffableDataSource, it can save your time and nerves. Everything is simplified, just tell it, that you have new data and after this, all changes will be done in the UICollectionView automatically and you will see your new cells with nice animation.

NSDiffableDataSourceSnapshot

This is a struct and a snapshot of your data, UICollectionViewDiffableDataSource is using this data. Snapshot has all methods for data manipulation like insert, move, delete, append, reload. All these methods are simple, I think even a newbie can understand how to use them. I will describe something that is hard to understand from the documentation.

So basically this structure holds two generic elements:

SectionIdentifierType : Hashable
ItemIdentifierType : Hashable

From the description, you can see that this is section and element identifiers, by “identifiers” they mean object or struct which implements Hashable protocol. This item identifiers will later be passed to the UICollectionViewDiffableDataSource cellProvider closure. Section and elements identifiers don’t overlap each other, but also should be unique in the snapshot. If you had them twice or more, then datasource will show a warning in the logs.

In the snapshot must be at least one section, in the section you can add elements with two available options — with section identifier and without it.

If you pass elements without section identifier, then they will be added to the last one.

Basically elements and sections have different places in a store, due to this you can move elements without saying to what section they should be moved.

One reminder about Hashable protocol, it is used for comparing elements in snapshots, when datasource receives a new snapshot, it will compare the current and the new snapshot. Structs are more convenient than classes in this situation because they automatically implement this protocol in the latest Swift. In the classes you have to implement it is by yourself.

You can use a snapshot in two ways. First, you can take a current snapshot from datasource and modify it.

This is convenient if you have to reload cells and you did not implement Hashable for all your properties. With this we have one peculiarity, if you are using structs for elements identifiers, unfortunately, you can not reload them easily, they are value-based and to update them in the current snapshot you should do one trick. It would be convenient to have some kind of update method like in the Set but we don’t have it. Below you can find an example of how to update the struct in the snapshot.

If you are using classes you should not care about it, datasource will copy only references, that’s why you can change variables and reload an item inside a snapshot.

The second way, and personally I like it more, is to create a new snapshot from your data and pass it to the datasource using the apply method.

Bonus

I have found some additional features about UICollectionViewDiffableDataSource during researching and want to share them with you.

You can call UICollectionViewDiffableDataSource apply method in the background queue, in this case, it will calculate the difference inside that queue and then will call UICollectionView methods automatically in the main queue. You will probably need this when you have a lot of data and have some performance issues with it. One restriction here, you must call apply the method in the same queue always, or you will see warnings in the logs and maybe undefined behavior.

You can control animation time for the collection changes, just put apply the method in the animation block.

And the last one, sooner or later you will ask yourself, how to use different items for different sections. UICollectionViewDiffableDataSource is a generic class and you can’t use Hashable protocol directly, only via specific classes, you should use additional techniques. I see at least two options.

You can use an associative enum:

Or AnyHashable struct:

Conclusion

With UICollectionViewDiffableDataSource it is easier to develop collections and do updates on them. We don’t need to call additional methods and will reduce the number of errors which we can produce during the development.

In the next and the last article for this series, I will combine UICollectionViewDiffableDataSource and UICollectionViewCompositionalLayout and build a complex screen with a collection which will use them.

1. Documentation
2. Advances in UI Data Sources(WWDC)
3. Using Collection View Compositional Layouts and Diffable Data Sources
4. Github

In the current year, Apple showed mind-blowing conference WWDC to us. All iOS dev community are focusing on new cool frameworks and features(SwiftUI, Combine, RealityKit, etc.) trying to figure out how they are working and what to do with them. Many other small but very helpful for current applications features somehow stayed off the screen and today I want to share my own research about one of them — UICollectionViewCompositionalLayout.

I am pretty sure that every newbie iOS developer has started his learning path from the list view, this is a crucial UI element you can find almost in all applications. UICollectionView evolved from UITableView, this fancy UI element helps us to put items in a different order on the screen, all that we have to do is to use UICollectionViewFlowLayout or create a custom one extending UICollectionViewLayout.

But stop! Have you ever tried to do that? If you have you know how hard this is, there is a bunch of different methods, we have to use to create a nice behavior, later on, you would figure out that maybe you should add caching or something else.

All these hard things are stopping developers, they are lazy, they don’t want to do something like this and usually, they are trying to find some library which will help them. That’s why this year Apple gives us UICollectionViewCompositionalLayout and this class continues the era of declarative programming.

UICollectionViewCompositionalLayout is a new fancy Layout, with it we can declaratively setup how it should display items in UICollectionView. After a little amount of code layout will understand what to do and will do all the hard work instead of us, with it you don’t have to implement any of those methods from UICollectionViewLayout!

Let’s look at a simple example the code below will create a list in which all the rows have the same absolute height.

Our next step will be to look at all those classes which are involved in Layout creation.

NSCollectionLayoutSize

We should use NSCollectionLayoutSize for setting width and height of the item in Layout. It has two main variables which you should setup during initialization.

NSCollectionLayoutDimension has four variants

One interesting thing you can do with it, you can set in the NSCollectionLayoutSize.widthDimension NSCollectionLayoutDimension.fractionalHeight and vice versa. For example NSCollectionLayoutSize.heightDimension = .fractionalWidth(0.5) means that the height of the item will be equal to half of the width group.

Estimated is the most interesting and powerful one, it is calculating the size for the row “on the fly”. If you have tried to do it previously, you know that it does not work at all with complex cells. I have tested current implementation and it looks pretty good to me, I did not see any problems there at all. Only one thing you have to do is to set item and group heightDimension into type estimated. One restriction we have here is that you must not set contentInsets for element, otherwise Layout will warn you and won’t draw respectively.

In this example you will see Layout for the list where size for the elements is calculated during the rendering process.

NSCollectionLayoutItem

NSCollectionLayoutItem is responsible for setting item in collection group, it’s initializing with NSCollectionLayoutSize. In this class you can find two variables which help setup insets and spacing.

contentInsets is working in this way: at first Layout calculates the place and size for the element, then it is looking for element insets in this variable. Like I said before, don’t use contentInsets with estimated size.

edgeSpacing is much more interesting, this is the separate class NSCollectionLayoutEdgeSpacing inside which you can find the same variables as for insets(leading, top, trailing, bottom) but you must use the separate class NSCollectionLayoutSpacing there, not just simple float variable. This spacing is used by Layout before calculating the place for the items, you can use it for filling empty space in your Layout. You can find two types of spacing in the class

flexible is for filling empty space which we have in a group

fixed is doing what it is saying, sets fixed spacing

As an example I will create Layout where with edgeSpacing two columns will be placed in the middle of the screen.

NSCollectionLayoutGroup

NSCollectionLayoutGroup extending NSCollectionLayoutItem. It adds a crucial feature, you can add there as many items as you want to. Section must have only one group, then during rendering process Layout will draw groups depending on how many items we have in the datasource. For example we have one group, and in it we have one element, datasource is “saying” that we have ten items, than ten groups will be drawn, if we have 2 items in a group then 5 groups will be drawn. Groups can be visualized like stacks, they can be vertical or horizontal, you can add there one kind of item or more. If you want to set some space between items you can use interItemSpacing variable.

If you don’t like vertical and horizontal groups, then you can create your own custom variant.

With NSCollectionLayoutGroupCustomItem class you can set object position in the group, also you can use zIndex if needed. In closure NSCollectionLayoutGroupCustomItemProvider we will receive NSCollectionLayoutEnvironment, it contains container size and also its trait collection.

The most important thing is that you can put a group in a group, like in a stack. That’s because group extends NSCollectionLayoutItem. Using this cool feature I have created complex layout with multiple groups.

NSCollectionLayoutSection

After looking at all previous section components, I think you should not have any questions about it. Section is the place where we can have one or more groups, groups can have one or more items. Here we can also set additional spacing for groups and for all content.

In addition we have two interesting variables here.

visibleItemsInvalidationHandler — this closure is called before each rendering cycle, you can use it if you want to know what items are currently visible on the screen, change this items layout or know what offset we currently have.

orthogonalScrollingBehavior — with this variable you can set opposite scroll for particular section. If you have ever tried to do that, you know that the simplest way was to put one more collection in the cell, but from the architecture perspective that was really awful. I think this is what we were waiting for for a long time. We have FIVE different scroll behaviours.

In the next example you can see how continuous type is working, this is amazing!

UICollectionViewCompositionalLayout

UICollectionViewCompositionalLayout is our main class, we can initialize it with NSCollectionLayoutSection or with closure, this closure will be called when layout needs information about the section, here you can set up different behaviour for different sections depending on container size and trait collection, portrait and landscape type. Using UICollectionViewCompositionalLayoutConfiguration, you can set scroll direction and space between sections.

NSCollectionLayoutSupplementaryItem, NSCollectionLayoutBoundarySupplementaryItem, NSCollectionLayoutDecorationItem

I keep silence about this additional items intentionally because we are not using them in full power usually, but with this new layout system it will be much easier. I will briefly touch all of them and will show examples with them.

NSCollectionLayoutSupplementaryItem is used for items and groups. The key difference here is how we should add this item to layout. For this we have separate class NSCollectionLayoutAnchor, this item is always rendering above the main element(group, item), that’s why we anchor it to the item sides. It is sounds complicated but on practice it is quite easy. Here is Apple doc example

In addition we can specify absolute or fractional offset. The Fractional one is based on the item size.

Here is my Layout example where I put a checkmark on a group

NSCollectionLayoutBoundarySupplementaryItem — this footers and headers, we all know them, right? This item you can add to NSCollectionLayoutSection and UICollectionViewCompositionalLayoutConfiguration. The size you can set with NSCollectionLayoutSize, and where the item will be — with NSRectAlignment. For header you should set NSRectAlignment to .top, for footer — equals to .bottom.

One interesting variable we have — pinToVisibleBounds, we can do a “sticky header/footer” with it. If you set it in true then current item will be visible whenever its section is visible.

In the example I create three items, at the top, left and bottom, one thing I want to note is that fractional size for this item is based on container not on the section, that’s why left item size you can not set as fractional, you should calculate your section size and set it in absolute value. Maybe in release Apple will change that.

And the last thing is NSCollectionLayoutDecorationItem, with it we can set background for section, it is easy to use and has only one static initializer.

This item extends from NSCollectionLayoutItem, that’s why we can set contentInsets for it, with insets you can adjust bounds for the background. One more specific thing for this item, you must register it in UICollectionViewCompositionalLayout.

In the example, I add shadow for the whole section which is quite cool.

Conclusion

UICollectionViewCompositionalLayout is one of the big steps in iOS development, with this tool it is much easier to create the collection of elements, declarative behavior will satisfy 99% developers.

While the SwiftUI is still in active development and there we still don’t have collections at all, I highly recommend using this new Layout in new projects. In the next article, I will try to experiment with UICollectionViewDiffableDataSource.

1. Documentation
2. Advances in Collection View Layout(WWDC)
3. Using Collection View Compositional Layouts and Diffable Data Sources
4. Github