AsyncDisplayKit

Batch Fetching API

AsyncDisplayKit’s Batch Fetching API makes it easy to add fetching chunks of new data. Usually this would be done in a -scrollViewDidScroll: method, but ASDK provides a more structured mechanism.

By default, as a user is scrolling, when they approach the point in the table or collection where they are 2 “screens” away from the end of the current content, the table will try to fetch more data.

If you’d like to configure how far away from the end you should be, just change the leadingScreensForBatching property on an ASTableView or ASCollectionView to something else.

SwiftObjective-C
tableNode.view.leadingScreensForBatching = 3.0;  // overriding default of 2.0

Batch Fetching Delegate Methods

The first thing you have to do in order to support batch fetching, is implement a method that decides if it’s an appropriate time to load new content or not.

For tables it would look something like:

SwiftObjective-C
- (BOOL)shouldBatchFetchForTableNode:(ASTableNode *)tableNode
{
  if (_weNeedMoreContent) {
    return YES;
  }

  return NO;
}

and for collections:

SwiftObjective-C

- (BOOL)shouldBatchFetchForCollectionNode:(ASCollectionNode *)collectionNode
{
  if (_weNeedMoreContent) {
    return YES;
  }

  return NO;
}

These methods will be called when the user has scrolled into the batch fetching range, and their answer will determine if another request actually needs to be made or not. Usually this decision is based on if there is still data to fetch.

If you return NO, then no new batch fetching process will happen. If you return YES, the batch fetching mechanism will start and the following method will be called next.

-tableNode:willBeginBatchFetchWithContext:

or

-collectionNode:willBeginBatchFetchWithContext:

This is where you should actually fetch data, be it from a web API or some local database.

Note: This method will always be called on a background thread. This means, if you need to do any work on the main thread, you should dispatch it to the main thread and then proceed with the work needed in order to finish the batch fetch operation.
SwiftObjective-C
- (void)tableNode:(ASTableNode *)tableNode willBeginBatchFetchWithContext:(ASBatchContext *)context 
{
  // Fetch data most of the time asynchronoulsy from an API or local database
  NSArray *newPhotos = [SomeSource getNewPhotos];

  // Insert data into table or collection node
  [self insertNewRowsInTableNode:newPhotos];

  // Decide if it's still necessary to trigger more batch fetches in the future
  _stillDataToFetch = ...;

  // Properly finish the batch fetch
  [context completeBatchFetching:YES];
}

Once you’ve finished fetching your data, it is very important to let ASDK know that you have finished the process. To do that, you need to call -completeBatchFetching: on the context object that was passed in with a parameter value of YES. This assures that the whole batch fetching mechanism stays in sync and the next batch fetching cycle can happen. Only by passing YES will the context know to attempt another batch update when necessary.

Check out the following sample apps to see the batch fetching API in action:

Edit on GitHub