Upgrading to 2.0
- GitHub Release Notes
- Getting the 2.0 Release Candidate
- Testing your app with 2.0
- Migrating to 2.0
- Migrating to 2.0 (Layout)
Please read the official release notes on GitHub.
Getting the Release Candidate
Add the following to your podfile
pod 'AsyncDisplayKit', '>= 2.0'
pod repo update pod update AsyncDisplayKit
in the terminal.
Once you have updated to 2.0, you will see many deprecation warnings. Don’t worry!
These warnings are quite safe, because we have bridged all of the old APIs for you, so that you can test out the 2.0, before migrating to the new API.
If your app fails to build instead of just showing the warnings, you might have Warnings as Errors enabled for your project. You have a few options:
- Disable deprecation warnings in the Xcode project settings
- Disable warnings as errors in the project’s build settings.
- Disable deprecation warnings in ASDK. To do this, change
# define ASDISPLAYNODE_WARN_DEPRECATED 0
Once your app builds and runs, test it to make sure everything is working normally. If you find any problems, try adopting the new API in that area and re-test.
One key behavior change you may notice:
.alignItemsproperty default changed to
ASStackLayoutAlignItemsStart. This may cause distortion in your UI.
If you still have issues, please file a GitHub issue and we’d be happy to help you out!
Migrating to 2.0
Once your app is working, it’s time to start converting!
A full API changelog from
2.0-beta.1 is available here.
.usesImplicitHierarchyManagementhas been renamed to
.automaticallyManagesSubnodes. The Automatic Subnode Management API has been moved out of Beta, but has a few documented limitations.
-cancelLayoutTransitionsInProgresshas been renamed to
-cancelLayoutTransition. The Layout Transition API has been moved out of Beta. Significant new functionality is planed for future dot releases.
Updated Interface State Callback Methods
The new method names are meant to unify the range update methods to show how they relate to each other and be a bit more self-explanatory:
didEnterPreloadState / didExitPreloadState
didEnterDisplayState / didExitDisplayState
didEnterVisibleState / didExitVisibleState
These new methods replace the following:
Collection / Table API Updates
AsyncDisplayKit’s collection and table APIs have been moved from the view space (
tableView) to the node space (
- Search your project for
collectionView. Most, if not all, of the data source / delegate methods have new node versions.
It is important that developers using AsyncDisplayKit understand that an ASCollectionNode is backed by an ASCollectionView (a subclass of UICollectionView). ASCollectionNode runs asynchronously, so calling number -numberOfRowsInSection on the collectionNode is different than calling it on the collectionView.
For example, let’s say you have an empty table. You insert
100 rows and then immediately call -tableView:numberOfRowsInSection. This will return
0 rows. If you call -waitUntilAllUpdatesAreCommitted after insertion (waits until the collectionNode synchronizes with the collectionView), you will get 100, but you might block the main thread. A good developer should rarely (or never) need to use -waitUntilAllUpdatesAreCommitted. If you update the collectionNode and then need to read back immediately, you should use the collectionNode API. You shouldn’t need to talk to the collectionView.
As a rule of thumb, use the collection / table node API for everything, unless the API is not available on the collectionNode.
To summarize, any
indexPath that is passed to the
collectionView space references data that has been synced with
UICollectionView. Conversly, any
indexPath that is passed to the
collectionNode space references asynchronous data that might not yet have been synced with ASCollectionNode’s underlying
UICollectionView. The same concepts apply to
An exception to this is
-didSelectRowAtIndexPath:, which is called in UIKit space to make sure that
indexPath indicies reference the data in the onscreen (data that has been synced to the underlying
While previous versions of the framework required the developer to be aware of the asynchronous interplay between
ASCollectionNode and its underlying
UICollectionView, this new API should provide better safegaurds against developer-introduced data source inconsistencies.
Other updates include:
ASTableView’s -init method. Please use
ASTableView. While this makes adopting the framework marginally more difficult to, the benefits of using ASTableNode / ASCollectionNode over their ASTableView / ASCollectionView counterparts are signficant.
-endUpdatesAnimated:. Please use the
-reloadDataImmediately. Please see the header file comments for the deprecation solution.
Moved range tuning to the
constrainedSizeForNodeAtIndexPath:moved from the
.delegateto be consistent with UIKit definitions of the roles. Note: Make sure that you provide a delegate for any
ASPagerNodesthat use this method. Your code will silently not call your delegate method, if you do not have a delegate assigned.
collection view update validation assertions are now enabled. If you see something like
"Invalid number of items in section 2. The number of items after the update (7) must be equal to the number of items before the update (4) plus or minus the number of items inserted or removed from the section (4 inserted, 0 removed)”, please check the data source logic. If you have any questions, reach out to us on GitHub.
- Use node blocks if possible. These are run in parallel on a background thread, resulting in 10x performance gains.
- Use nodes to store things about your rows.
- Make sure to batch updates that need to be batched.
Layout API Updates
Please read the separate Layout 2.0 Conversion Guide for an overview of the upgrades and to see how to convert your existing layout code.
Help us out
If we’re missing something from this list, please let us know or edit this doc for us (GitHub edit link at the top of page)!