Upgrading to 2.0

  1. GitHub Release Notes
  2. Getting the 2.0 Release Candidate
  3. Testing your app with 2.0
  4. Migrating to 2.0
  5. Migrating to 2.0 (Layout)

Release Notes

Please read the official release notes on GitHub.

Getting the Release Candidate

Add the following to your podfile

pod 'AsyncDisplayKit', '>= 2.0'

then run

pod repo update
pod update AsyncDisplayKit

in the terminal.

Testing 2.0

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:

  1. Disable deprecation warnings in the Xcode project settings
  2. Disable warnings as errors in the project’s build settings.
  3. Disable deprecation warnings in ASDK. To do this, change line 74 in ASBaseDefines.h to # 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:

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 1.9.92 to 2.0-beta.1 is available here.

ASDisplayNode Changes

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:

These new methods replace the following:

Collection / Table API Updates

AsyncDisplayKit’s collection and table APIs have been moved from the view space (collectionView, tableView) to the node space (collectionNode, tableNode).

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 ASCollectionNode’s underlying 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 ASTableNode.

An exception to this is ASTableNode’s -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 UICollectionView dataSource).

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:

Best Practices:


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)!

Edit on GitHub