Overview

TLIndexPathDataModel is an immutable object you use in your view controller to hold your data items instead of an array. Creating a data model is as easy as passing an array of items (of any type) to the initializer. Or if the data needs to be organized into sections, there are two additional initializers, one for implicitly defined sections using sectionNameKeyPath and another for an explicitly defined array of TLIndexPathSectionInfo objects. A multitude of APIs are provided for accessing the data and translating between index paths and data items.

This class can be used on it’s own to help fulfill the table or collection view data source and delegate methods. For example, the prototypically implementation of numberOfRowsInSection is:

- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section
{
    return [self.dataModel numberOfRowsInSection:section];
}

But the real power of TLIndexPathTools lies in use of the companion class TLIndexPathUpdates to perform animated batch udpates when items are inserted, moved or deleted from the data model. To modify the data model, one would typically either extract items from the current data model into an NSMUtableArray, make changes, and then instantiate a new data model with the updated items:

TLIndexPathDataModel *oldDataModel = self.dataModel;
NSMutableArray *items = [NSMutableArray arrayWithArray:oldDataModel.items];
... //make changes to items
self.dataModel = [TLIndexPathDataModel alloc] initWithItems:items];

//batch updates
TLIndexPathUpdates *updates = [TLIndexPathUpdates alloc] initWithOldDataModel:oldDataModel updatedDataModel:self.dataModel];
[updates performBatchUpdatesOnTableView:self.tableView withRowAnimation:UITableViewRowAnimationFade];

Another common pattern is to write a factory method for the data model that recreates the data model from scratch based current state of the view controller:

TLIndexPathDataModel *oldDataModel = self.dataModel;
self.dataModel = [self newDataModel];

//batch updates
TLIndexPathUpdates *updates = [TLIndexPathUpdates alloc] initWithOldDataModel:oldDataModel updatedDataModel:self.dataModel];
[updates performBatchUpdatesOnTableView:self.tableView withRowAnimation:UITableViewRowAnimationFade];

But the recommended approach is to use TLIndexPathController because it works interchangeably with Core Data NSFetchRequests or plain arrays of arbitrary data. Thus, it provides a unified programming model for building tables and collection views. The typical way to use TLIndexPathController is:

NSMutableArray *items = [NSMutableArray arrayWithArray:self.indexPathController.items];
... //make changes to items
self.indexPathController.items = items;

where the items property is just a shortcut for setting the dataModel property.

When the controller’s data model gets updated, the it calls its delegate methods, the primiry one being didUpdateDataModel. The typical implementation would simply perform the batch updates:

- (void)controller:(TLIndexPathController *)controller didUpdateDataModel:(TLIndexPathUpdates *)updates
{
    [updates performBatchUpdatesOnTableView:self.tableView withRowAnimation:UITableViewRowAnimationFade];
}

When working with Core Data, the main differences is that you’d initialize the TLIndexPathController with an NSFetchRequest and then the data model get generated/updated internally as the fetch results change.

Another advantage in using TLIndexPathController is that you can define base table and collection view controller classes and use them everywhere (i.e. with or without Core Data). TLIndexPathTools provides two such implementations: TLTableViewController and TLCollectionViewController. Both classes provide default implementations of the essential data source and delegate methods to get you up-and-running quickly. TLTableViewController also provides a default implementation of heightForRowAtIndexPath that can handle custom cell heights (static heights defined in Interface Builder or dynamic heights defined by implementing the TLDynamicSizeView protocol in a custom cell class).

Item Identification

TLIndexPathDataModel needs to be able to identify items in order to keep an internal mapping between items and index paths and to track items across versions of the data model. It does not assume that the item itself is a valid identifier (for example, if the item doesn not implement NSCopying, it cannot be used as a dictionary key). So the following set of rules are used to locate a valid identifier. Each rule is tried in turn until a non-nil value is found:

1. If identifierKeyPath is specified (through an appropriate initializer), the data model attempts to use the item’s value for this key path. If the key path is invalid for the given item, the next rule is tried.
2. If the item is an instance of TLIndexPathItem, the value of the identifier property is tried.
3. If the item is an instance of NSManagedObject, the objectID property is used.
4. If the item conforms to NSCopying, the item itself is used.
5. If all else fails, the item’s memory address is returned as a string.

Section Name Identifcation

TLIndexPathDataModel identifies sections by their name, which is defined according to the following rules.

1. If sectionNameKeyPath is specified (through the appropriate initializer), the data model attempts to use the item’s value for this key path. If the key path is invalid for the given item, the next rule is tried.
2. If the item is an instance of TLIndexPathItem, the value of the sectionName property is tried.
3. The value TLIndexPathDataModelNilSectionName is used.