Home

Awesome

PJFDataSource

CI Status Version License Platform

PJFDataSource is a small library that provides a simple, clean architecture for your app to manage its data sources while providing a consistent user interface for common content states (i.e. loading, loaded, empty, and error).

Inspiration

PJFDataSource was built as a simpler and more focused alternative to Apple's AdvancedCollectionView sample code which was originally introduced in the 2014 WWDC presentation Advanced User Interfaces with Collection Views.

We keep the basic patterns that we like, but discard most of the more complex features. For example, PJFDataSource doesn't have any built-in support for "aggregate data sources". Nor does it do any handling of your actual view's content (e.g. configuring and displaying UICollectionViewCells). It doesn't even require you to use a UICollectionView. Your app remains responsible for providing and configuring your user interface's content view, giving you the flexibility to choose a table view, collection view, stack view, etc.

Installation

CocoaPods

To install PJFDataSource in your iOS project, install with CocoaPods:

platform :ios, '11.0'
pod 'PJFDataSource'

Demo

To see the featureset of PJFDataSource in a more concrete way, check out the simplistic demo app included in this repository.

  1. Clone this repository to your machine
  2. Open PJFDataSource.xcodeproj in Xcode
  3. Switch your Target to PJFDataSourceDemoApp and Run

The demo app will open in the iOS Simulator, presenting you with a table view showing a bunch of colored rows. This is our simplistic content view, a UITableView. The three buttons at the top of the view, labeled "Success", "Empty" and "Error" simply tell the demo app to reload it's content, and simulate either a successful response, an empty response, or an error response. Give each of these a try and notice:

That's really all there is to it!

Usage

There are two primary interaction points between your app and PJFDataSource are:

Basic integration into your app looks like this:

  1. Create the view controller that will own the content view you want to show.
  2. In the view controller, instantiate a PJFContentWrapperView using initWithFrame:contentView:, passing in your content view of choice (e.g. a UITableView). Insert the wrapper view into the appropriate place in your view hierarchy—likely as a full-size subview of your root view. Although not required, you will likely want to set your view controller as the PJFContentWrapperViewDelegate of the wrapper view, and implement at least willShowNoContentView: and willShowErrorView: so that you can customize the content of these placeholder views.
  3. In the view controller, instantiate your PJFDataSource subclass (see below), with your view controller as the delegate. Implement contentWrapperViewForDataSource:, the single required method on the PJFDataSourceDelegate protocol, having it return the content wrapper view created above.
  4. In the view controller's viewWillAppear: method, call loadContent on your data source.

You've now got your own PJFDataSource subclass instance. You're telling it to load when your view controller appears. The data source does its work and updates the content wrapper view appropriately. Ta-da!

Example -[PJFDataSource loadContent]

Implementing your loadContent method correctly is important and not entirely obvious from the API. The key is that the PJFDataSource instance uses its provided PJFLoadingCoordinator to actually kick off the load, as well as to notify of success/failure. See this example, taken directly from the demo app:

- (void)loadContent;
{    
    [self.loadingCoordinator loadContentWithBlock:^(PJFLoadingState *loadingState) {
        [self.colorsLoader asyncLoadColorsWithSuccess:^(NSArray *colors) {
            if (!loadingState.valid) {
                return;
            }
            
            self.colors = colors;
            
            [self.loadingCoordinator loadContentDidFinishWithError:nil];
            
        } error:^(NSError *error) {
            if (!loadingState.valid) {
                return;
            }
            
            [self.loadingCoordinator loadContentDidFinishWithError:error];            
        }];
    }];
}

The self.loadingCoordinator object is provided by the PJFDataSource base class. When you start loading your content, do so via the loadContentWithBlock: method. This allows the loading coordinator to know when you start loading and allows it to provide a PJFLoadingState object so we can ignore incoming responses from obsolete requests (i.e. invalidated by a more recent request).

Within the loadContentWithBlock: block, you'll kick off your async loading task with callbacks for completion. In this case we're using another object (self.colorsLoader) to do the heavy lifting. In our completion blocks, we check the loadingState to determine if it is still current. If it isn't, we ignore this response by returning immediately. If it's still current, then we'll update our internal model (e.g. self.colors = colors;) and then notify our loadingCoordinator of success or failure via loadContentDidFinishWithError:.

Appearance Styling

PJFDataSource provides for limited appearance styling via the UIAppearance mechanism. See the properties marked with UI_APPEARANCE_SELECTOR in PJFLoadingView and PJFContentWrapperView. Also see the demo app's AppAppearance class, whose sole purpose is to set up the appearance styling.

Missing Features

We want to keep PJFDataSource simple, but there are some things we know we'd like to add:

If you'd like to help, see "Contributing" below.

Requirements

Contributing

We’re glad you’re interested in PJFDataSource, and we’d love to see where you take it. Please read our contributing guidelines prior to submitting a Pull Request.

Fry Meme wondering about PJFDataSource's name prefix