AsyncDisplayKit 2.0 Tutorial: Getting Started

Naming Nodes

In order to see a node move through the various states, it is useful to give it a name. This way, you’ll be able to watch as each node loads its data, displays its content, comes on-screen and then does the whole thing in reverse as it leaves.

Go back to -tableNode:nodeBlockForRowAtIndexPath:, and find the comment that says:

//You'll add something extra here later...

Right below it, add the following line to give each cell a debugName.

cardNode.debugName = [NSString stringWithFormat:@"cell %zd", indexPath.row];

Now you’ll be able to track the cells’ progression through the ranges.

Observing the Cells

Navigate to CardNode_InterfaceCallbacks.m. Here you’ll find six methods you can use to track a node’s progress through the various ranges. Uncomment them, and then build and run. Make sure your console in Xcode is visible and then scroll slowly. As you do, watch as the various cells react to their changing states.

Note: In most cases, the only ASInterfaceState change method you’ll care about is -didEnterVisibleState or -didExitVisibleState. That said, a lot of work is going on under the hood for you. To check out what you can do by integrating with the Preload and Display states, take a look at the code in ASNetworkImageNode. All network image nodes will automatically fetch and decode their content, as well as free up memory, without you needing to lift a finger.

(Intelligent Preloading)²

In the 2.0 release, the concept of intelligently preloading content in multiple directions was introduced. Say you have a vertically scrolling table view, and at some point a cell comes onscreen that contains a horizontal collection view.

Though this collection is now technically in the visible region, you wouldn’t want to load the entire collection up front. Instead, both scroll views have their own ASRangeController complete with separately configurable range tuning parameters.

Entering the Second Dimension

Now that you have completed AnimalTableController, you’re able to use it as a page in an ASPagerNode.

The view controller you’ll use to contain this pager is already in the project so the first thing you need to do is navigate to AppDelegate.m.

Find -installRootViewController and replace:

AnimalTableController *vc = [[AnimalTableController alloc] 
                              initWithAnimals:[RainforestCardInfo allAnimals]];

with:

AnimalPagerController *vc = [[AnimalPagerController alloc] init];

Then, go into AnimalPagerController.m and add the following lines to the initializer right before the return statement. All you need to do is create a new pager and set its dataSource to be this view controller.

_pagerNode = [[ASPagerNode alloc] init];
_pagerNode.dataSource = self;

The pager node is actually a subclass of an ASCollectionNode preconfigured to be used in the same way you’d use a UIPageViewController. The nice thing about this is that the API is actually quite a bit simpler to think about than UIPageViewController‘s.

The next thing you have to do is to implement the pager’s data source methods. Navigate to the ASPagerDataSource category implementation at the bottom of this file.

First, tell the pager that its number of pages is equal to the number of animal arrays, in this case, three by replacing the existing -numberOfPagesInPagerNode:.

- (NSInteger)numberOfPagesInPagerNode:(ASPagerNode *)pagerNode {
  return self.animals.count;
}

Then, you need to implement -pagerNode:nodeAtIndex:, similar to the node block data source method you implemented for the ASTableNode earlier.

- (ASCellNode *)pagerNode:(ASPagerNode *)pagerNode nodeAtIndex:(NSInteger)index {
  //1
  CGSize pagerNodeSize = pagerNode.bounds.size;
  NSArray *animals = self.animals[index];
    
  //2
  ASCellNode *node = [[ASCellNode alloc] initWithViewControllerBlock:^{
    return [[AnimalTableController alloc] initWithAnimals:animals];
  } didLoadBlock:nil];
   
  return node;
}

Let’s review this section by section:

1. Although this version isn’t block-based, it’s good practice to grab your data model first.
2. This time, you’re using the powerful -initWithViewControllerBlock: initializer. All you need to do is return a block that returns the table node controller you fixed up earlier and the managed view will automatically be used as the view for each page. Pretty cool if you ask me. ;]

Once you’ve added this method you’ll have a fully functioning pager whose cells are generated from the tableNodeController you created earlier. This comes fully stocked with two dimensional preloading based on the vertical and horizontal scrolling performed by the user!

Where To Go From Here?

To see the completed project for this AsyncDisplayKit 2.0 tutorial, download it here. If you’re wanting to see all this in Swift, we’ve got that too.

When you’re ready, move on to part 2 to learn about the powerful new layout system introduced with AsyncDisplayKit 2.0.

If you’d rather do a little more research before moving on, you can check out AsyncDisplayKit’s home page and read through some of the documentation. Scott Goodson (the original author of AsyncDisplayKit) also has a few talks you may be interested in, the newest of which gives a good overview of some of the bigger picture problems the framework is trying to tackle.

You may also be interested in the Building Paper event. Although none of this was open sourced at that time, and a lot has changed, it’s pretty interesting to see where it all started.

Lastly, as part of the AsyncDisplayKit community’s legendary reputation for welcoming newcomers, there is a public Slack channel where anyone is invited to come and ask questions!

Hopefully you enjoyed this tutorial, let us know if you have any questions or comments by joining the forum discussion below!