PagedLists

What is it?

PagedLists gives you custom UITableView and UICollectionView classes that supports pagination. All the logic and tracking of loading states, current page and when to actually request next pages is handled by these components.

Features:

• Customizable number of elements per page.
• Multiple scrolling directions are supported(i.e: You can load new pages of messages at the top of a chat.)
• Supports paged scrolling in UICollectionView.
• Uses delegation to load content from your desired source.

Installation

1. Cocoapods

PagedLists is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'PagedLists', '~> 1.0.0'

2. Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. Add the following line to your Cartfile and follow the installation instructions.

github "rootstrap/PagedLists" ~> 1.0.0

3. Swift Package Manager

• In XCode 11, go to File -> Swift Packages -> Add Package Dependency.
• Enter the repo URL(https://github.com/rootstrap/PagedLists) and click Next.
• Select the version rule desired(you can specify a version number, branch or commit) and click Next. This library supports SPM starting from the version 1.0.0.
• Finally, select the target where you want to use the framework.

That should be it. PagedLists should appear in the navigation panel as a dependency and the framework will be linked automatically to your target.

Note: It is always recommended to lock your external libraries to a specific version.

Usage

You can add a PagedTableView or PagedCollectionView programmatically or via Storyboards by specifying the class in the attributes inspector.

let tableView = PagedTableView(frame: <some CGRect>)

Configuration

Set the number of elements per page you are expecting from your data source.

tableView.elementsPerPage = 20

The pagination delegate

tableView.updateDelegate = self

By conforming to the pagination protocol, PagedTableView and PagedCollectionView gives you an opportunity to load the data from your desired source. You must then send the element count back or the error in case of failure.

extension ViewController: PagedTableViewDelegate {

  func tableView(
    _ tableView: PagedTableView,
    needsDataForPage page: Int,
    completion: (Int, NSError?) -> Void
  ) {
    // Load data from a network request and communicate results
    // back to the PagedTableView
    viewModel.getItems(
      page: page,
      success: { [weak self] newItemsCount in
        tableView.reloadData()
        completion(newItemsCount, nil)
      },
      failure: { [weak self] error in
        self?.showErrorToTheUser()
        completion(0, error)
      }
    )
  }
}

Custom pagination data

In the example above, we are letting PagedTableView to automatically detect if a new page request is necessary based on the number of elements loaded.

If your datasource provides data on pagination you can use that information to control when the table view loads new pages.

tableView.hasMore = requestData.isNextPageAvailable

Restart pagination

You can reset all pagination data on a table or collection view, for example, if you have a pull to refresh control.

dataSource.items = []
tableView.reloadData()
// Resets pagination
tableView.reset()

Example

To run the example project, clone the repo, and run pod install from the Example directory first.

Credits

PagedLists is maintained by Rootstrap and German López with the help of our contributors.

License

PagedLists is available under the MIT license. See the LICENSE file for more info.