Need documentation

[plm75]

Hello, first of all thanks for your fantastic work with RxSwift.

For someone like me who's learning RxSwift, I feel like RxDataSources could use a little more documentation in order to provide some sort of general understanding of how things work. I'm all for reading source code/trying examples, but sometimes it can be quite overwhelming without some sort of general understanding/mental framework...

In addition, DataSource binding is quite specific to RxSwift and its not possible to get more info from other Rx implementations.

Thanks

[kzaher]

Hi @plm75 ,

yeah, I agree. We need helpful feedback from people to understand how to best present this. Could you provide a list of questions you would like to be answered so we can write up some kind of FAQ?

[plm75]

Hi @kzaher ,

Following up on your suggestion, the following is a quick and dirty list that summarizes what I currently understand of RxDataSources after literally only a few hours of playing with the examples and questions that I currently have.

Again, I've just started learning Rx so I may/probably have missed some obvious stuff so apologies in advance. Hope you or someone else will find time to review it and provide guidance for the questions.

• How to implement dataSources the 'default' way without RxDataSources:
  Four methods are available:
  rx_itemsWithCellIdentifier(:String)
rx_itemsWithCellIdentifier(:String:Cell.Type)
rx_itemsWithCellFactory(:ObservableType)
rx_itemsWithDataSource(:protocol<RxTableViewDataSourceType, UITableViewDataSource>)

  simplest example:

  let dataSource = Observable<[String]>.just(["first", "second", "third"])
  
  dataSource.bindTo(tableView.rx_itemsWithCellIdentifier("Cell")) { index, model, cell in
    cell.textLabel?.text = model
  }
  .addDisposableTo(disposeBag)

  [ Question:
  examples of when and how to use the other methods (withCellFactory, withDataSource)?
  ]

• Why use RxDataSources vs default method ?
  The default method deals with very simple use cases.
  RxDataSources are required when the data is structured into different sections with potentially different item types.
  RxDataSources are required to perform animations on insert/modify/delete

  [ Question: is the above correct ? What did I miss ?]

• How to use RxDataSources [no animations]
  1- Define a struct that conforms to the SectionModelType protocol (MySection)

  • Define Item, the type of items that the section will contain
  • Declare items property as an array of Item elements

  2- Create a dataSource object as an instance of either:

  • RxCollectionViewSectionedReloadDataSource

  • RxTableViewSectionedReloadDataSource

    and pass it MySection as generic type

  3- customize closures on the dataSource as needed:

  • configureCell
  • titleForHeaderInSection
  • titleForFooterInSection
  • etc

  4- Define actual data as an Observable stream of MySection objects

  5- Bind actual data to tableView with rx_itemsWithDataSource(dataSource)

  6- If needed, set delegate with `tableView.rx_setDelegate(self)``

  [ Question: is the above correct ? What did I miss ?]

• How to use RxDataSources [with animations]
  Same as static sections, except MySection needs to conform to AnimatableSectionModelType
  and dataSource object needs to be an instance of either:

  • RxCollectionViewSectionedAnimatedDataSource
  • RxTableViewSectionedAnimatedDataSource

  [ Question: is the above correct ? What did I miss ?]

[kzaher]

Hi @plm75 ,

everything you've said is correct.

rx_itemsWithCellIdentifier(:String)
rx_itemsWithCellIdentifier(:String:Cell.Type)
rx_itemsWithCellFactory(:ObservableType)

... are just conveniences for rx_itemsWithDataSource(:protocol<RxTableViewDataSourceType, UITableViewDataSource>)

I think we can improve the docs in both the main repo and this repo. Feel free to create a PR with that FAQ, or I'll create it in a couple of days.