Swiftpack.co - Package - GenericDataSource/GenericDataSource

GenericDataSource

Swift Version

Version

Build Status Coverage Status Documentation

A generic small reusable components for data source implementation for UITableView/UICollectionView written in Swift.

Features

  • BasicDataSource easily bind model to cells with automatic dequeuing.
  • SegmentedDataSource easily build segmented controls or for empty state of your UICollectionView/UITableView data source.
  • CompositeDataSource builds complex cells/models structure with easy to use components (BasicDataSource SegmentedDataSource or other CompositeDataSource).
  • UICollectionView supplementary, UITableView header, and footer views support.
  • ☑ Ability to override any data source method from UIKit classes.
  • ☑ Comprehensive Unit Test Coverage.
  • Complete Documentation

Requirements

  • iOS 8.0+
  • Xcode 10
  • Swift 4.0+

Installation

CocoaPods

To integrate GenericDataSource into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'GenericDataSources'

IMPORTANT: The pod name is GenericDataSources with "s" at the end.

Carthage

To integrate GenericDataSource into your Xcode project using Carthage, specify it in your Cartfile:

github "GenericDataSource/GenericDataSource"

Manually

Add GenericDataSource.xcodeproj to your project file by drag and drop.

You can then consult to Adding an Existing Framework to a Project.


Example

Basic Data Source Example

UITableView

Create a basic data source and bind it to to a table view.

let dataSource = BasicBlockDataSource<Example, BasicTableViewCell>() { (item: Example, cell: BasicTableViewCell, indexPath) -> Void in
    cell.titleLabel?.text = item.title
}

// Need to keep a strong reference to our data source.
self.dataSource = dataSource

// register the cell
tableView.ds_register(cellClass: BasicTableViewCell.self)
// bind the data source to the table view
tableView.ds_useDataSource(dataSource)

dataSource.items =  <<retrieve items>> // Can be set and altered at anytime

That's it! Your first data source is implemented. No dequeuing! no casting! simple and smart.

UICollectionView

Let's now take it to the next level. Suppose after we implemented it, the requirements changed and we need to implement it using UICollectionView.

let dataSource = BasicBlockDataSource<Example, BasicCollectionViewCell>() { (item: Example, cell: BasicCollectionViewCell, indexPath) -> Void in
    cell.titleLabel?.text = item.title
}

// Need to keep a strong reference to our data source.
self.dataSource = dataSource

// register the cell
collectionView.ds_register(cellClass: BasicCollectionViewCell.self)
// bind the data source to the collection view
collectionView.ds_useDataSource(dataSource)

dataSource.items =  <<retrieve items>> // Can be set and altered at anytime

All you need to do is change the cell class and of course the table view to collection view.

Actually this opens the door for so much possibilities. You can inherit from BasicDataSource and implement your custom generic data source that is based on a protocol implemented by the cell and you don't need to repeat the configuration part. You would create data source like that.

let dataSource1 = CustomDataSource<BasicTableViewCell>() // for table view
let dataSource2 = CustomDataSource<BasicCollectionViewCell>() // for collection view

App store Featured Example

Suppose we want to implement the following screen, the App Store featured tab.

App Store Example Screenshot

If you want to have a look at the complete source code, it is under Example project -> AppStoreViewController.swift.

  1. We will create cells as we do normally.
  2. Now we need to think about DataSources.
  3. It's simple, one data source for each cell type (BasicDataSource).
  4. CompositeDataSource(sectionType: .single) for the table view rows. Since these rows are of different cell types.
  5. SegmentedDataSource for switching between loading and data views.
  6. Bind the SegmentedDataSource data source to the table view and that's it.
  7. See how we think structurally about our UI and data sources instead of one big cell.

One thing we didn't talk about is the UICollectionView of the featured section cells. It's very simple, just BasicDataSource.

See how we can implement the screen in the following code:

  1. Create the cells.
class AppStoreFeaturedSectionTableViewCell: UITableViewCell { ... }
class AppStoreQuickLinkLabelTableViewCell: UITableViewCell { ... }
class AppStoreQuickLinkTableViewCell: UITableViewCell { ... }
class AppStoreFooterTableViewCell: UITableViewCell { ... }
class AppStoreLoadingTableViewCell: UITableViewCell { ... }
  1. Create BasicDataSources.
class AppStoreLoadingDataSource: BasicDataSource<Void, AppStoreLoadingTableViewCell> {
    // loading should take full screen size.
    override func ds_collectionView(_ collectionView: GeneralCollectionView, sizeForItemAt indexPath: IndexPath) -> CGSize {
        return collectionView.size
    }
}
class AppStoreFooterDataSource: BasicDataSource<Void, AppStoreFooterTableViewCell> { ... }
class AppStoreQuickLinkDataSource: BasicDataSource<FeaturedQuickLink, AppStoreQuickLinkTableViewCell> { ...  }
class AppStoreFeaturedAppsDataSource: BasicDataSource<FeaturedApp, AppStoreFeaturedAppCollectionViewCell> { ... }
class AppStoreFeaturedAppsSectionDataSource: BasicDataSource<FeaturedSection, AppStoreFeaturedSectionTableViewCell> { ... }
class AppStoreQuickLinkLabelDataSource: BasicDataSource<String, AppStoreQuickLinkLabelTableViewCell> { ... }
  1. Create CompositeDataSource that holds the featured page.
class AppStoreFeaturedPageDataSource: CompositeDataSource {
    init() { super.init(sectionType: .single)] }

    var page: FeaturedPage? {
        didSet {
            // remove all existing data sources
            removeAllDataSources()

            guard let page = page else {
                return
            }

            // add featured apps
            let featuredApps = AppStoreFeaturedAppsSectionDataSource()
            featuredApps.setSelectionHandler(UnselectableSelectionHandler())
            featuredApps.items = page.sections
            add(featuredApps)

            // add quick link label
            let quickLinkLabel = AppStoreQuickLinkLabelDataSource()
            quickLinkLabel.setSelectionHandler(UnselectableSelectionHandler())
            quickLinkLabel.items = [page.quickLinkLabel]
            add(quickLinkLabel)

            // add quick links
            let quickLinks = AppStoreQuickLinkDataSource()
            quickLinks.items = page.quickLinks
            add(quickLinks)

            // add footer
            let footer = AppStoreFooterDataSource()
            footer.setSelectionHandler(UnselectableSelectionHandler())
            footer.items = [Void()] // we add 1 element to show the footer, 2 elements will show it twice. 0 will not show it.
            add(footer)
        }
    }
}
  1. Create the outer most data source.
class AppStoreDataSource: SegmentedDataSource {

    let loading = AppStoreLoadingDataSource()
    let page = AppStoreFeaturedPageDataSource()

    // reload data on index change
    override var selectedDataSourceIndex: Int {
        didSet {
            ds_reusableViewDelegate?.ds_reloadData()
        }
    }

    override init() {
        super.init()
        loading.items = [Void()] // we add 1 element to show the loading, 2 elements will show it twice. 0 will not show it.

        add(loading)
        add(page)
    }
}
  1. Register cells.
tableView.ds_register(cellNib: AppStoreFeaturedSectionTableViewCell.self)
tableView.ds_register(cellNib: AppStoreQuickLinkLabelTableViewCell.self)
tableView.ds_register(cellNib: AppStoreQuickLinkTableViewCell.self)
tableView.ds_register(cellNib: AppStoreFooterTableViewCell.self)
tableView.ds_register(cellNib: AppStoreLoadingTableViewCell.self)
  1. Set data sources to the collection view.
tableView.ds_useDataSource(dataSource)
  1. Finally set the data when it is available.
  // show loading indicator
  dataSource.selectedDataSourceIndex = 0

  // get the data from the service
  service.getFeaturedPage { [weak self] page in

    // update the data source model
    self?.dataSource.page.page = page

    // show the page
    self?.dataSource.selectedDataSourceIndex = 1
}

There are many benefits of doing that:

  1. Lightweight view controllers.
  2. You don't need to think about indexes anymore, all is handled for us. Only think about how you can structure your cells into smaller data sources.
  3. We can switch between UITableView and UICollectionView without touching data sources or models. Only change the cells to inherit from UITableViewCell or UICollectionViewCell and everything else works.
  4. We can add/delete/update cells easily. For example we decided to add more blue links. We can do it by just adding new item to the array passed to the data source.
  5. We can re-arrange cells as we want. Just move around the add of data sources calls.
  6. Most importantly no if/else in our code.

Check the Examples application for complete implementations.

Attribution

The main idea comes from [WWDC 2014 Advanced User Interfaces with Collection Views] (https://developer.apple.com/videos/play/wwdc2014/232/) written in swift with generics.

Author

Mohamed Afifi, mohamede1945@gmail.com

License

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

Github

link
Stars: 122

Dependencies

Used By

Total: 0

Releases

3.0.3 - 2018-09-23 22:43:06

  • Support for Swift 4 & 4.2.
  • Upgrade to Xcode 10.

3.0.2 - 2018-04-24 16:49:32

  • Upgrade to Xcode 9.3.

3.0.0 - 2017-10-30 01:24:35

  • Swift 4.0 Support.

3.0.1 - 2017-10-30 01:24:17

  • Fix a crash in CompositeSupplementaryViewCreator.

2.4.3 - 2017-04-20 14:43:20

  • Fix registering header/footer class method name to be func ds_register(headerFooterClass view: UITableViewHeaderFooterView.Type) instead of incorrect old name func ds_register(headerFooterNib view: UITableViewHeaderFooterView.Type).

2.4.4 - 2017-04-20 14:42:45

  • Added the ability for CompositeDataSource and SegmentedDataSource to automatically ds_responds(to selector: DataSourceSelector) if the subclass implemented the selector.

2.4.5 - 2017-04-20 14:42:27

  • Adding onItemsUpdated to basic data sources to monitor changes to items property.
  • Adding most non-essential APIs to be DataSourceSelector so that, it's delegate methods is not called by default.

2.4.2 - 2017-04-05 14:05:56

  • Adding asCollectionView() and asTableView() methods to GeneralCollectionView to convert it to UICollectionView and UITableView respectively.
  • Adding size property to GeneralCollectionView to get the size of the underlying UICollectionView/UITableView.

2.4.1 - 2017-03-31 07:17:43

  • @autoclosure of casting fatal message. Improves performance since there is string manipulation.

2.4.0 - 2017-03-30 13:31:35

  • ds_shouldConsumeItemSizeDelegateCalls is unavailable, instead use ds_responds(to selector: DataSourceSelector) -> Bool, It takes an enum, with .size it act the same as ds_shouldConsumeItemSizeDelegateCalls.
  • Fixes a bug that makes all table view cells editable by default.
  • New ds_responds(to selector: DataSourceSelector) -> Bool to make it so easy to make some implementations of DataSource methods optional (e.g. we used it to fix the editable table view cells bug).

2.3.1 - 2017-03-30 13:31:15

  • Fixed a critical crash for ds_collectionView(_:didEndDisplaying:forItemAt:) in CompositeDataSource.

2.3.0 - 2017-03-23 10:11:42

  • Adding SegmentedDataSource.

2.2.1 - 2017-03-04 18:09:50

  • Making Supplementary view optional as a workaround for the UITableView with .grouped style as it asks for the header/footer view even if the size is set as 0.

2.2.0 - 2017-03-04 11:21:25

  • UITableView Header/Footer support.
  • UICollectionView Supplmentary view support.

2.1.0 - 2016-10-12 19:35:12

  • Renaming methods to match Swift 3.0 conventions.

2.0.0 - 2016-10-12 19:10:35

Swift 3 Support

- 2016-08-01 21:36:36

  • Deprecating useDelegateForItemSize in favor of automatic detection if the user implemented ds_collectionView(_:sizeForItemAtIndexPath:) or not.
  • Adding more code documentation and enhancing the readme file.