Swiftgram/submodules/AsyncDisplayKit/docs/_docs/adoption-guide-2-0-beta1.md

title	layout	permalink	prevPage
Upgrading to 2.0	docs	/docs/adoption-guide-2-0-beta1.html	adoption-guide-2-0-beta1.html

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 'Texture', '>= 2.0'

then run

pod repo update
pod update Texture

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 Texture. 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:

• ASStackLayoutSpec's .alignItems property default changed to ASStackLayoutAlignItemsStretch instead of 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 1.9.92 to 2.0-beta.1 is available here.

ASDisplayNode Changes

• ASDisplayNode's .usesImplicitHierarchyManagement has been renamed to .automaticallyManagesSubnodes. The Automatic Subnode Management API has been moved out of Beta, but has a few documented limitations.

• ASDisplayNode's -cancelLayoutTransitionsInProgress has 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:

• loadStateDidChange:(BOOL)inLoadState
• displayStateDidChange:(BOOL)inDisplayState
• visibleStateDidChange:(BOOL)isVisible

Collection / Table API Updates

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

• Search your project for tableView and collectionView. Most, if not all, of the data source / delegate methods have new node versions.

It is important that developers using Texture understand that an ASCollectionNode is backed by an ASCollectionView (a subclass of UICollectionView). ASCollectionNode runs asynchronously, so calling -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:

• Deprecate ASTableView's -init method. Please use ASTableNode instead of ASTableView. While this makes adopting the framework marginally more difficult to, the benefits of using ASTableNode / ASCollectionNode over their ASTableView / ASCollectionView counterparts are signficant.

• Deprecate -beginUpdates and -endUpdatesAnimated:. Please use the -performBatchUpdates: methods instead.

• Deprecate -reloadDataImmediately. Please see the header file comments for the deprecation solution.

• Moved range tuning to the tableNode / collectionNode (from the tableView / collectionView)

• constrainedSizeForNodeAtIndexPath: moved from the .dataSource to the .delegate to be consistent with UIKit definitions of the roles. Note: Make sure that you provide a delegate for any ASTableNode, ASCollectionNode or ASPagerNodes that use this method. Your code will silently not call your delegate method, if you do not have a delegate assigned.

• Renamed pagerNode:constrainedSizeForNodeAtIndexPath: to pagerNode:constrainedSizeForNodeAtIndex:

• 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.

Best Practices:

• 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.

Resources:

• Video of the ASCollectionNode Behind-the-Scenes talk at Pinterest. The diagrams seen in the talk.

• PR #2390 and PR #2381 show how we converted AsyncDisplayKit's example projects to conform to this new API.

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