IGInterfaceDataTable is a category on WKInterfaceTable that makes configuring tables with multi-dimensional data easier. Instead of flattening your data structures into an array, configure your watch tables using a data source pattern similar to UITableViewDataSource.

Use IGInterfaceDataTable to build beautiful Apple Watch apps with complex data structures, just like in the Instagram Apple Watch app.

Installation

You can quickly install IGInterfaceDataTable using CocoaPods. Add the following to your Podfile:

pod 'IGInterfaceDataTable'

If you would rather install the framework manually, simply copy the WKInterfaceTable+IGInterfaceDataTable.h and WKInterfaceTable+IGInterfaceDataTable.m files into your project's WatchKit Extension target.

Import the framework header, or create an Objective-C bridging header if you're using Swift.

#import <IGInterfaceDataTable/IGInterfaceDataTable.h>

Getting Started

In order to start using IGInterfaceDataTable, you simply need to conform an object to IGInterfaceTableDataSource (defined here) and set it as your table's ig_dataSource.

There are only two required methods that you need to implement to start displaying data. The first returns the number of rows for a section.

- (NSInteger)numberOfRowsInTable:(WKInterfaceTable *)table section:(NSInteger)section {
    return self.items.count;
}

Note: If you don't implement numberOfSectionsInTable:, the data source defaults to just a single section.

The other required method returns the identifier of a row controller configured in your WatchKit storyboard.

- (NSString *)table:(WKInterfaceTable *)table rowIdentifierAtIndexPath:(NSIndexPath *)indexPath {
    return @"RowIdentifier";
}

Beyond the required methods, you can also provide identifiers for the header, footer, and even section headers. Check out the header documentation to see everything you can do!

Customizing Rows

IGInterfaceDataSource provides convenience methods to update your row controllers whenever you reload or add data to your WKInterfaceTable.

The following method will pass the data source a row controller for a row in the table. You're then free to configure the row, such as setting text labels or adding images.

- (void)table:(WKInterfaceTable *)table 
        configureRowController:(NSObject *)rowController 
        forIndexPath:(NSIndexPath *)indexPath {
    MyController *controller = (MyController *)rowController;
    [controller.textLabel setText:@"Hello!"];
}

There are configure methods for headers, footers, and sections as well.

Convenience

IGInterfaceDataSource also provides methods to make bridging between WKInterfaceTable and your data structures more seamless.

For example, in order to map a row selection back to the index path of your data, you call -[WKInterfaceTable indexPathFromRowIndex:]

- (void)table:(WKInterfaceTable *)table didSelectRowAtIndex:(NSInteger)rowIndex {
  NSIndexPath *indexPath = [table indexPathFromRowIndex:rowIndex];
  if (indexPath) {
    // do something with the index path or data
  }
}

Or, you can scroll straight to a section without having to lookup the row index of your data:

[table scrollToSection:section];

Testing

Since WKInterfaceTable objects must be initialized from storyboards, and there is no mechanism yet to create a WatchKit storyboard in code, we cannot use Xcode unit tests yet.

For now, tests are run manually by executing the ApplicationTests WatchKit extension and ensuring that none of the asserts are fired.

Contributing

See the CONTRIBUTING file for how to help out.

License

IGInterfaceDataTable is BSD-licensed. We also provide an additional patent grant.