A data-driven UICollectionView framework for building fast and flexible lists.
4.0.0 is here! 🎉🎊🥳
This version has a number of improvements we've been working on for the last year. We're excited for everyone get their hands on the new improvements and features. Thanks so much to all who contributed code, submitted issues, and contributed to discussions around this release!
Added Swift annotation name to IGListAdapterDelegate which removes IG prefix. The new name for Swift clients is ListAdapterDelegate. Andrea Antonioni (#1116)
IGListKit has been split into IGListKit and IGListDiffKit for Xcode and Carthage builds. Cocoapods continues to use an all-inclusive IGListKit podspec. Nate Stedman (#1377)
Remove coalescanceTime from IGListAdapterUpdate, since it increase crash rate. Zhisheng Huang (2f76e8c)
All IGListBindingSectionControllerSelectionDelegate methods are now required. Bofei Zhu (#1186)
Renamed [IGListAdapterUpdatingDelegate listAdapterUpdater:willPerformBatchUpdatesWithCollectionView:] to [IGListAdapterUpdatingDelegate listAdapterUpdater:willPerformBatchUpdatesWithCollectionView:fromObjects:toObjects:listIndexSetResult:] to include more supporting info on updated objects. Jeremy Cohen (b200dda)
Renamed [IGListAdapterUpdatingDelegatelistAdapterUpdater:collectionView:willCrashWithException:fromObjects:toObjects:updates:] to [ IGListAdapterUpdatingDelegatelistAdapterUpdater:collectionView:willCrashWithException:fromObjects:toObjects:diffResult:updates:] to include diff result info. Zhisheng Huang (039e77e)
Remove IGListStackedSectionController. Hanton Yang (#1355)
Added IGListCollectionScrollingTraits for exposing UICollectionView scrolling traits to section controllers via IGListCollectionContext. Adam Stern (b4c8ea1)
IGListBindingSectionController no longer asserts when reloading the entire section. A warning message is now logged if the entire section is going to be reloaded. Jeff Bailey (#1213)
Added preferItemReloadsForSectionReloads in IGListAdapterUpdater so that the item updates are invoked with the proper collectionView animation, instead of using the delete+insert section operation when the number of items is unchanged. Zhisheng Huang (f699ea0)
Created IGListAdapterPerformanceDelegate for IGListAdapter to be able to measure how long some operations take across all section controllers. For example, how long it takes to dequeue a cell. Maxime Ollivier (4662454)
Update CocoaPods integration to use the CocoaPods specs CDN Koen Punt (#1386)
Fixed bug with layouts inconsistency in updateAnimated:completion of IGListBindingSectionController. Qinghua Hong (#1285)
Fixed bug with -[IGListAdapter scrollToObject:supplementaryKinds:scrollDirection:scrollPosition:animated:] where the content inset(bottom/right) of the collection view was incorrectly being applied to the final offset and was inconsistent with the content inset(top/left) of the collection view being applied. Qinghua Hong (#1284)
Fixed crash when the data source is nil before calling -[IGListAdapterUpdater performUpdateWithCollectionViewBlock:fromObjects:toObjectsBlock:animated:objectTransitionBlock:completion:]. Zhisheng Huang (6cdd112)
Experimental fix to get the UICollectionView for batch updating immediately before applying the update. Ryan Nystrom (583efb9)
Fixed bug with IGListDiff.mm where arrays of NSIndexPath, instead of NSIndexPath, were incorrectly set as objects for the IndexPathMaps. Bofei Zhu (#1205)
[IGListAdapterUpdater performBatchUpdatesWithCollectionViewBlock:] and [IGListAdapterUpdater performReloadDataWithCollectionViewBlock:] clean state and run completion blocks if their UICollectionView is nil. Brandon Darin (290d592)
Ensuring view models with duplicate diff identifiers are removed when view models are first requested by IGListBindingSectionController Adam Stern (a1ee4c1)
Fixed [IGListAdapterUpdater reloadItemInCollectionView:fromIndexPath:toIndexPath:] does not call delegate when not inside a batch update. Bofei Zhu (#1211)
Log instead of assert for duplicate diff identifiers to make code testable. Adam Stern (bee2178)
Removed nibName argument from IGListReusableViewIdentifier. Trung Duc (#1223)
Fixed crash when using -[IGListCollectionContext dequeueReusableCellOfClass:withReuseIdentifier:forSectionController:atIndex:] Jeremy Lawrence (3b19cfb)
Added missing method override to IGListBindingSectionController that updates the internal viewModels array after moving a cell. Dennis Müller (#1262)
Fixed logic flaw in [IGListCollectionViewLayout shouldInvalidateLayoutForBoundsChange:]. Allen Hsu (#1236)
Fixed crash when calling [UICollectionView layoutAttributesForSupplementaryElementOfKind...] with IGListCollectionViewLayout and the section controller doesn't actually return a supplementary view Maxime Ollivier (cddb297)
Added IGListExperimentAvoidLayoutOnScrollToObject to avoid creating off-screen cells when calling [IGListAdapter scrollToObject ...]. Maxime Ollivier (6faddd9)
Added IGListExperimentFixIndexPathImbalance to test fixing a crash when inserting and deleting the same NSIndexPath multiple times. Maxime Ollivier (7824698)
Relicensed IGListKit to MIT. Ryan Nystrom (000bc36)
Experimental performance improvement from deferring -[IGListAdapterDataSource objectsForListAdapter:] calls until just before diffing. Ryan Nystrom (3059c5e)
Add support for UICollectionView's interactive reordering in iOS 9+. Updates include -[IGListSectionController canMoveItemAtIndex:] to enable the behavior, -[IGListSectionController moveObjectFromIndex:toIndex:] called when items within a section controller were moved through reordering, -[IGListAdapterDataSource listAdapter:moveObject:from:to] called when section controllers themselves were reordered (only possible when all section controllers contain exactly 1 object), and -[IGListUpdatingDelegate moveSectionInCollectionView:fromIndex:toIndex] to enable custom updaters to conform to the reordering behavior. The update also includes two new examples ReorderableSectionController and ReorderableStackedViewController to demonstrate how to enable interactive reordering in your client app. Jared Verdi (#976)
5x improvement to diffing performance when result is only inserts or deletes. Ryan Nystrom (afd2d29)
Can always show sticky header although section data is empty. Marcus Wu (#1129)
Added -[IGListCollectionContext dequeueReusableCellOfClass:withReuseIdentifier:forSectionController:atIndex:] to allow for registering cells of the same class with different reuse identifiers. Jeremy Lawrence (f47753e)
Copy objects when retrieving from datasource to prevent modification of models in binding section controller. Kashish Goel (#1109)
Fixed footer is sticky when stickyHeader is true aelam (#1094)
Updated IGListCollectionViewLayout to rely on layoutAttributesClass instead of vanilla UICollectionViewLayoutAttributes Cole Potrocky #1135
-[IGListSectionController didSelectItemAtIndex:] is now called when a scrollViewDelegate or collectionViewDelegate is set. Ryan Nystrom (#1108)
Fixed binding section controllers failing to update their cells when the section controller's section changes. Chrisna Aing (#1144)
Added -[IGListSectionController didHighlightItemAtIndex:] and -[IGListSectionController didUnhighlightItemAtIndex:] APIs to support UICollectionView cell highlighting. Kevin Delannoy (#933)
Added -didDeselectSectionController:withObject: to IGListSingleSectionControllerDelegate Darren Clark (#954)
Added a new listener API to be notified when IGListAdapter finishes updating. Add listeners via -[IGListAdapter addUpdateListener:] with objects conforming to the new IGListAdapterUpdateListener protocol. Ryan Nystrom (5cf01cc)
Updated project settings for iOS 11. Ryan Nystrom (#942)
Added support UICollectionElementKindSectionFooter for IGListCollectionViewLayout. Igor Vasilenko (#1017)
Added experiment to make -[IGListAdapter visibleSectionControllers:] a bit faster. Maxime Ollivier (82a2a2e)
Added support -[UIScrollView adjustedContentInset] for iOS 11. Guoyin Li (#1020)
Added new transitionDelegate API to give IGListSectionControllers control to customize initial and final UICollectionViewLayoutAttributes. Includes automatic integration with IGListCollectionViewLayout. Sue Suhan Ma (26924ec)
Reordered position of intercepted selector in IGListAdapterProxy's isInterceptedSelector method to reduce overall consumption of compare. zhongwuzw (#1055)
Made IGListTransitionDelegate inherited from NSObject. Igor Vasilenko (#1075)
Duplicate objects for initial data source setup filtered out. Mikhail Vashlyaev (#993
Weakly reference the UICollectionView in coalescence so that it can be released if the rest of system is destroyed. Ryan Nystrom (d322c2e)
Fix bug with -[IGListAdapter scrollToObject:supplementaryKinds:scrollDirection:scrollPosition:animated:] where the content inset of the collection view was incorrectly being applied to the final offset. Ryan Nystrom (b2860c3)
Avoid crash when invalidating the layout while inside `-[UICollectionView performBatchUpdates:completion:]. Ryan Nystrom (d9a89c9)
Duplicate view models in IGListBindingSectionController gets filtered out. Weyert de Boer (#916)
Check object type on lookup to prevent crossing types if different objects collide with their identifiers. Ryan Nystrom (296baf5)
IGListBindingSectionControllerDelegate objects do not implement the optional deselection API. Ryan Nystrom (#921)
This release closes the 3.1.0 milestone.
po [IGListDebugger dump]. Candance Smith (#856)
Prevent a crash when update queued immediately after item batch update. Ryan Nystrom (3dc6060)
Return correct -[IGListAdapter visibleSectionControllers] when section has no items, but has supplementary views. Mani Ghasemlou (#643)
Call [CATransaction commit] before calling completion block in IGListAdapterUpdater to prevent animation issues. Maxime Ollivier (6f946b2)
Fix scrollToObject:supplementaryKinds:... not scrolling when section is empty but does have supplymentary views. Gulam Moledina (#808)
Better support for non-top positions in scrollToObject: API. Gulam Moledina (#861)
Added -[IGListSectionController didDeselectItemAtIndex:] API to support default UICollectionView cell deselection. Ryan Nystrom (6540f96)
Added -[IGListCollectionContext selectItemAtIndex:] Select an item through IGListCollectionContext like -[IGListCollectionContext deselectItemAtIndex:]. Marvin Nazari (#874)
Added horizontal scrolling support to IGListCollectionViewLayout. Peter Edmonston (#857)
Added support for scrollViewDidEndDecelerating to IGListAdapter. Phil Larson (#899)
Automatically disable [UICollectionView isPrefetchingEnabled] when setting a collection view on an adapter. Ryan Nystrom (#889)
This release closes the 3.0.0 milestone.
IG prefixes from class names, C functions, and other APIs. Note, this only affects Swift clients. Robert Payne (#593)
Example:
// OLD
class MySectionController : IGListSectionController { ... }
// NEW
class MySectionController : ListSectionController { ... }
// OLD
IGListDiff([], [], .equality)
// NEW
ListDiff(oldArray: [], newArray: [], .equality)
didSelect delegate call in IGListSingleSectionControllerDelegate to include object. Sherlouk (#397)
// OLD
- (void)didSelectSingleSectionController:(IGListSingleSectionController *)sectionController;
// NEW
- (void)didSelectSectionController:(IGListSingleSectionController *)sectionController
withObject:(id)object;
IGListUpdatingDelegate now conforms to NSObject, bringing it in line with other framework protocols. Adlai Holler (#435)
Changed hasChanges methods in IGListIndexPathResult and IGListIndexSetResult to read-only properties. Bofei Zhu (#453)
Replaced IGListGridCollectionViewLayout with IGListCollectionViewLayout. Ryan Nystrom (#482, #450)
Renamed IGListAdapterUpdaterDelegate method to listAdapterUpdater:didPerformBatchUpdates:collectionView:. Vincent Peng (#491)
Moved section controller mutations to IGListBatchContext, provided as a parameter when calling -performBatchAnimated:updates:completion on a section controller's collectionContext. All updates (insert, delete, reload item/section controller) must now be done inside a batch update block. Ryan Nystrom (a15ea08)
// OLD
[self.collectionContext performBatchAnimated:YES updates:^{
self.expanded = YES;
[self.collectionContext insertInSectionController:self atIndexes:[NSIndexSet indexSetWithIndex:1]];
} completion:nil];
// NEW
[self.collectionContext performBatchAnimated:YES updates:^(id<IGListBatchContext> batchContext) {
self.expanded = YES;
[batchContext insertInSectionController:self atIndexes:[NSIndexSet indexSetWithIndex:1]];
} completion:nil];
// OLD
[self.collectionContext reloadSectionController:self];
// NEW
[self.collectionContext performBatchAnimated:YES updates:^(id<IGListBatchContext> batchContext) {
[batchContext reloadSectionController:self];
} completion:nil];
-[IGListCollectionContext containerSize] no longer accounts for the content inset of the collection view when returning a size. If you require that behavior, you can now use -[IGListCollectionContext insetContainerSize]. Ryan Nystrom (623ff2a)
IGListCollectionView has been completely removed in favor of using plain old UICollectionView. See discussion at #409 for details. Jesse Squires (2284ce3)
IGListBatchUpdateData replaced its NSSet properties with NSArray instead. Ryan Nystrom (#616)
IGListUpdatingDelegate now requires method -reloadItemInCollectionView:fromIndexPath:toIndexPath: to handle reloading cells between index paths. Ryan Nystrom (#657)
-[IGListCollectionContext sectionForSectionController:] has been removed and replaced with the NSInteger sectionIndex property on IGListSectionController. Andrew Monshizadeh #671
Added an initializer on IGListAdapter that does not take a workingRangeSize and defaults it to 0. BasThomas (#686)
Added -[IGListAdapter visibleCellsForObject:] API. Sherlouk (#442)
Added -[IGListAdapter sectionControllerForSection:] API. Adlai-Holler (#477)
You can now manually move items (cells) within a section controller, ex: [self.collectionContext moveInSectionController:self fromIndex:0 toIndex:1]. Ryan Nystrom (#418)
Invalidate the layout of a section controller and control the transition with UIView animation APIs. Ryan Nystrom (#499)
Added -[IGListAdapter visibleIndexPathsForSectionController:] API. Malecks (#465)
Added IGListBindingSectionController which automatically binds view models to cells and animates updates at the cell level. Ryan Nystrom (#494)
Added IGListGenericSectionController to take advantage of Objective-C (and Swift) generics and automatically store strongly-typed references to the object powering your section controller. Ryan Nystrom (301f147)
Added a debug option for IGListKit that you can print to lldb via po [IGListDebugger dump]. Ryan Nystrom (#617)
Gracefully handle a nil section controller returned by an IGListAdapterDataSource. Ryan Nystrom (#488)
Fix bug where emptyView's hidden status is not updated after the number of items is changed with insertInSectionController:atIndexes: or related methods. Peter Edmonston (#395)
Fix bug where IGListStackedSectionController's children need to know numberOrItems before didUpdate is called. (#348)
Fix bug where -[UICollectionViewCell ig_setStackedSectionControllerIndex:] should use OBJC_ASSOCIATION_COPY_NONATOMIC for NSNumber. PhilCai (#424)
Fix potential bug with suppressing animations (by passing NO) during -[IGListAdapter performUpdatesAnimated: completion:] where user would see UI glitches/flashing. Jesse Squires (019c990)
Fix bug where scroll position would be incorrect in call to -[IGListAdapter scrollToObject:supplementaryKinds:scrollDirection:scrollPosition:animated: with scrollDirection/scrollPosition of UICollectionViewScrollDirectionVertical/UICollectionViewScrollPositionCenteredVertically or UICollectionViewScrollDirectionHorizontal/UICollectionViewScrollPositionCenteredHorizontally and with a collection view with nonzero contentInset. David Yamnitsky (5cc0fcd)
Fix a crash when reusing collection views between embedded IGListAdapters. Ryan Nystrom (#517)
Only collect batch updates when explicitly inside the batch update block, execute them otherwise. Fixes dropped updates. Ryan Nystrom (#494)
Remove objects that return nil diff identifiers before updating. Ryan Nystrom (af984ca)
Fix a potential crash when a section is moved and deleted at the same time. Ryan Nystrom (#577)
Prevent section controllers and supplementary sources from returning negative sizes that crash UICollectionViewFlowLayout. Ryan Nystrom (#583)
Add nullability annotations to a few more headers. Adlai Holler (#626)
Fix a crash when inserting or deleting from the same index within the same batch-update application. Ryan Nystrom (#616)
IGListSectionType protocol was removed and its methods were absorted into the IGListSectionController base class with default implementations. Ryan Nystrom (3102852)
When setting the collection view on IGListAdapter, its layout is now properly invalidated. Jesse Squires (#677)
Fixes a bug when reusing UICollectionViews with multiple IGListAdapters in an embedded environment that would accidentally nil the collectionView property of another adapter. Ryan Nystrom (#721)
Fixes a bug where maintaining a reference to a section controller but not the list adapter in an async block could lead to calling -[IGListAdapter sectionForSectionController:] (or checking -[IGListSectionController sectionIndex]) and receiving an incorrect value. With the adapter check the value would be 0 because the adapter was nil and for the section controller property the value would be the last set index value. Andrew Monshizadeh (#709)
This release closes the 2.1.0 milestone.
IGListAdapter, IGListSectionController, and other components at this time. Guilherme Rambo (#235)
prefetchEnabled by default on IGListCollectionView. Sven Bacia (#323)
IGListStackedSectionController. Ryan Nystrom (#356)
IGListKit/Diffing and an installation guide. Sherlouk (#368)
allowsBackgroundReloading flag (default YES) to IGListAdapterUpdater so users can configure this behavior as needed. Adlai-Holler (#375)
-[IGListAdapter updater] is now public (read-only). Adlai-Holler (#379)
UICollectionView crashes when queueing a reload and insert/delete on the same item as well as reloading an item in a section that is animating. Ryan Nystrom (#325)
This release closes the 2.0.0 milestone. We've increased test coverage to 97%. Thanks to the 27 contributors who helped with this release!
You can find a migration guide here to assist with migrating between 1.0 and 2.0.
IGListIndexPathResult changed. -resultWithUpdatedMovesAsDeleteInserts was removed and replaced with -resultForBatchUpdates (b5aa5e3)
// OLD
- (IGListIndexPathResult *)resultWithUpdatedMovesAsDeleteInserts;
// NEW
- (IGListIndexPathResult *)resultForBatchUpdates;
IGListDiffable equality method changed from isEqual: to isEqualToDiffableObject: (ab890fc)
NSObject<IGListDiffable> category was removed and replaced with NSString<IGListDiffable> and NSNumber<IGListDiffable> categories. All other models will need to conform to IGListDiffable. (3947600)
IGListAdapter scrolling method changed:// OLD
- (void)scrollToObject:(id)object
supplementaryKinds:(nullable NSArray<NSString *> *)supplementaryKinds
scrollDirection:(UICollectionViewScrollDirection)scrollDirection
animated:(BOOL)animated;
// NEW
- (void)scrollToObject:(id)object
supplementaryKinds:(nullable NSArray<NSString *> *)supplementaryKinds
scrollDirection:(UICollectionViewScrollDirection)scrollDirection
scrollPosition:(UICollectionViewScrollPosition)scrollPosition
animated:(BOOL)animated;
NSUInteger to NSInteger in all public APIs. Suraya Shivji (#200)
IGListSingleSectionController to be able to support single sections created from nibs. An example can be found here. (#56)
- (instancetype)initWithNibName:(NSString *)nibName
bundle:(nullable NSBundle *)bundle
configureBlock:(IGListSingleSectionCellConfigureBlock)configureBlock
sizeBlock:(IGListSingleSectionCellSizeBlock)sizeBlock;
-isFirstSection and -isLastSection APIs to IGListSectionController (316fbe2)
IGListCollectionContext protocol to do this. Bofei Zhu (#92)
// IGListCollectionContext
- (__kindof UICollectionViewCell *)dequeueReusableCellFromStoryboardWithIdentifier:(NSString *)identifier
forSectionController:(IGListSectionController<IGListSectionType> *)sectionController
atIndex:(NSInteger)index;
tvOS support. Jesse Squires (#137)
-[IGListAdapter visibleObjects] API. Ryan Nystrom (386ae07)
-[IGListAdapter objectForSectionController:] API. Ayush Saraswat (#204)
IGListGridCollectionViewLayout, a section-based grid layout. Bofei Zhu (#225)
IGListCollectionContext protocol to do this. Jesse Squires (e5afb5b)
// IGListCollectionContext
- (void)scrollToSectionController:(IGListSectionController<IGListSectionType> *)sectionController
atIndex:(NSInteger)index
scrollPosition:(UICollectionViewScrollPosition)scrollPosition
animated:(BOOL)animated;
-[IGListAdapter reloadDataWithCompletion:] not returning early when collectionView or dataSource is nil and completion is nil. Ben Asher (#51)
UICollectionView bug when accessing a cell during working range updates. Ryan Nystrom (#216)
-[IGListAdapter reloadObjects:]. Ryan Nystrom (ca15e29)
IGListStackSectionController would only set its supplementary source once. Ryan Nystrom (#286)
IGListStackSectionController passed the wrong section controller for will-drag scroll events. Ryan Nystrom (#286)
IGListStackSectionController. Ryan Nystrom (#295)
tvOS example pack. Sherlouk (#141)
Take a look at the documentation, add IGListKit to your Podfile, or take a pass at some of our starter tasks.
We're launching at version 1.0 because of how widely used the framework is here at Instagram, but looking forward to enhancing and extending the framework even further. 🚀