mirror of
https://github.com/Instagram/IGListKit
synced 2026-05-23 09:18:29 +00:00
Proof guides for consisntency and name changes
Summary: Part of #707 Closes https://github.com/Instagram/IGListKit/pull/730 Differential Revision: D5039060 Pulled By: rnystrom fbshipit-source-id: d54259b2dddbaba0fe2e69c6dd08a37fd17fbc4a
This commit is contained in:
Ryan Nystrom
Facebook Github Bot
parent
d1cd23b3d0
commit
b6217a6709
5 changed files with 29 additions and 29 deletions
|
|
@ -95,12 +95,12 @@ class WeatherSectionModel {
|
|||
Just don't forget to make your models diffable using the data in the contained models:
|
||||
|
||||
```swift
|
||||
extension WeatherSectionModel: IGListDiffable {
|
||||
extension WeatherSectionModel: ListDiffable {
|
||||
func diffIdentifier() -> NSObjectProtocol {
|
||||
return location.identifier
|
||||
}
|
||||
|
||||
func isEqual(toDiffableObject object: IGListDiffable?) -> Bool {
|
||||
func isEqual(toDiffableObject object: ListDiffable?) -> Bool {
|
||||
guard self !== object else { return true }
|
||||
guard let object = object as? WeatherSectionModel else { return false }
|
||||
return location == object.location && forecast == object.forecast && conditions == object.conditions
|
||||
|
|
@ -118,9 +118,9 @@ We recommend using dependency injection and announcing changes, demonstrated in
|
|||
|
||||
#### Should I reuse my section controllers between models?
|
||||
|
||||
No! IGListKit is designed to have a 1:1 instance mapping between objects and section controllers. IGListKit does not reuse section controllers, and if you do unintended behaviors will occur.
|
||||
No! `IGListKit` is designed to have a 1:1 instance mapping between objects and section controllers. `IGListKit` does not reuse section controllers, and if you do unintended behaviors will occur.
|
||||
|
||||
IGListKit _does_ still use `UICollectionView`'s cell reuse, so you shouldn't be concerned about performance.
|
||||
`IGListKit` _does_ still use `UICollectionView`'s cell reuse, so you shouldn't be concerned about performance.
|
||||
|
||||
#### Why does `UICollectionViewFlowLayout` put everything in a new row?
|
||||
|
||||
|
|
@ -139,7 +139,7 @@ Use [`IGListBindingSectionController`](https://github.com/Instagram/IGListKit/bl
|
|||
We recommend creating a model that owns an array to the items that power `numberOfItems`. Checkout our [Post example](https://github.com/Instagram/IGListKit/blob/master/Examples/Examples-iOS/IGListKitExamples/SectionControllers/PostSectionController.m#L32) that has dynamic comment cells. Just be sure to check when your array changes:
|
||||
|
||||
```swift
|
||||
class Forecast: IGListDiffable {
|
||||
class Forecast: ListDiffable {
|
||||
let day: Date
|
||||
let hourly: [HourlyForecast]
|
||||
|
||||
|
|
@ -147,7 +147,7 @@ class Forecast: IGListDiffable {
|
|||
return day
|
||||
}
|
||||
|
||||
func isEqual(toDiffableObject object: IGListDiffable?) -> Bool {
|
||||
func isEqual(toDiffableObject object: ListDiffable?) -> Bool {
|
||||
guard self !== object else { return true }
|
||||
guard let object = object as? Forecast else { return false }
|
||||
return hourly == object.hourly // compare elements in the arrays
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ Creating a new section controller is simple. Subclass `IGListSectionController`
|
|||
Take a look at [LabelSectionController](https://raw.githubusercontent.com/Instagram/IGListKit/master/Examples/Examples-iOS/IGListKitExamples/SectionControllers/LabelSectionController.swift) for an example section controller that handles a `String` and configures a single cell with a `UILabel`.
|
||||
|
||||
```swift
|
||||
class LabelSectionController: IGListSectionController {
|
||||
class LabelSectionController: ListSectionController {
|
||||
override func sizeForItem(at index: Int) -> CGSize {
|
||||
return CGSize(width: collectionContext!.containerSize.width, height: 55)
|
||||
}
|
||||
|
|
@ -32,8 +32,8 @@ After creating at least one section controller, you must create a `UICollectionV
|
|||
let layout = UICollectionViewFlowLayout()
|
||||
let collectionView = UICollectionView(frame: .zero, collectionViewLayout: layout)
|
||||
|
||||
let updater = IGListAdapterUpdater()
|
||||
let adapter = IGListAdapter(updater: updater, viewController: self, workingRangeSize: 0)
|
||||
let updater = ListAdapterUpdater()
|
||||
let adapter = ListAdapter(updater: updater, viewController: self, workingRangeSize: 0)
|
||||
adapter.collectionView = collectionView
|
||||
```
|
||||
|
||||
|
|
@ -44,12 +44,12 @@ adapter.collectionView = collectionView
|
|||
The last step is the `IGListAdapter`'s data source and returning some data.
|
||||
|
||||
```swift
|
||||
func objects(for listAdapter: IGListAdapter) -> [IGListDiffable] {
|
||||
func objects(for listAdapter: ListAdapter) -> [ListDiffable] {
|
||||
// this can be anything!
|
||||
return [ "Foo", "Bar", 42, "Biz" ]
|
||||
}
|
||||
|
||||
func listAdapter(_ listAdapter: IGListAdapter, sectionControllerFor object: Any) -> IGListSectionController {
|
||||
func listAdapter(_ listAdapter: ListAdapter, sectionControllerFor object: Any) -> ListSectionController {
|
||||
if object is String {
|
||||
return LabelSectionController()
|
||||
} else {
|
||||
|
|
@ -57,7 +57,7 @@ func listAdapter(_ listAdapter: IGListAdapter, sectionControllerFor object: Any)
|
|||
}
|
||||
}
|
||||
|
||||
func emptyView(for listAdapter: IGListAdapter) -> UIView? {
|
||||
func emptyView(for listAdapter: ListAdapter) -> UIView? {
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
|
@ -126,7 +126,7 @@ The algorithm will skip updating two `User` objects that have the same `primaryK
|
|||
If you want to use the diffing algorithm outside of `IGListAdapter` and `UICollectionView`, you can! The diffing algorithm was built with the flexibility to be used with any models that conform to `IGListDiffable`.
|
||||
|
||||
```swift
|
||||
let result = IGListDiff(oldUsers, newUsers, .equality)
|
||||
let result = ListDiff(oldArray: oldUsers, newArray: newUsers, .equality)
|
||||
```
|
||||
|
||||
With this you have all of the deletes, reloads, moves, and inserts! There's even a function to generate `NSIndexPath` results.
|
||||
|
|
@ -140,9 +140,9 @@ A *working range* is a range of section controllers who aren't yet visible, but
|
|||
The `IGListAdapter` must be initialized with a range value in order to work. This value is a multiple of the visible height or width, depending on the scroll-direction.
|
||||
|
||||
```swift
|
||||
let adapter = IGListAdapter(updater: IGListAdapterUpdater(),
|
||||
viewController: self,
|
||||
workingRangeSize: 1) // 1 before/after visible objects
|
||||
let adapter = ListAdapter(updater: ListAdapterUpdater(),
|
||||
viewController: self,
|
||||
workingRangeSize: 1) // 1 before/after visible objects
|
||||
```
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ This guide provides details for how to migration between major versions of `IGLi
|
|||
|
||||
## From 1.x to 2.x
|
||||
|
||||
For details on all changes in IGListKit 2.0.0, please see the [release notes](https://github.com/Instagram/IGListKit/releases/tag/2.0.0).
|
||||
For details on all changes in `IGListKit` 2.0.0, please see the [release notes](https://github.com/Instagram/IGListKit/releases/tag/2.0.0).
|
||||
|
||||
### IGListDiffable Conformance
|
||||
|
||||
|
|
@ -33,12 +33,12 @@ If you relied on the default `NSObject<IGListDiffable>` category, you will need
|
|||
```swift
|
||||
import IGListKit
|
||||
|
||||
extension MyModel: IGListDiffable {
|
||||
extension MyModel: ListDiffable {
|
||||
func diffIdentifier() -> NSObjectProtocol {
|
||||
return self
|
||||
}
|
||||
|
||||
func isEqual(toDiffableObject object: IGListDiffable?) -> Bool {
|
||||
func isEqual(toDiffableObject object: ListDiffable?) -> Bool {
|
||||
return isEqual(object)
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,20 +1,20 @@
|
|||
# Vision
|
||||
|
||||
This document serves to outline the long term goals of IGListKit and act as a guidance when making decisions about features and issues.
|
||||
This document serves to outline the long term goals of `IGListKit` and act as a guidance when making decisions about features and issues.
|
||||
|
||||
## Prioritizing Features & Fixes
|
||||
|
||||
IGListKit is a data-driven, list-building framework built, owned, and maintained by the engineering team at Instagram. Because IGListKit powers parts of the Instagram iOS app, we prioritize features and bugs towards those that effect Instagram. However the team recognizes the wide range of use-cases for IGListKit and wants to serve as broad an audience as possible without sacrificing our own needs.
|
||||
`IGListKit` is a data-driven, list-building framework built, owned, and maintained by the engineering team at Instagram. Because `IGListKit` powers parts of the Instagram iOS app, we prioritize features and bugs towards those that effect Instagram. However the team recognizes the wide range of use-cases for `IGListKit` and wants to serve as broad an audience as possible without sacrificing our own needs.
|
||||
|
||||
## Goals & Scope
|
||||
|
||||
The core goal of IGListKit is to build fast, stable, and data-driven lists in iOS applications. That scope includes things like:
|
||||
The core goal of `IGListKit` is to build fast, stable, and data-driven lists in iOS applications. That scope includes things like:
|
||||
|
||||
- `UICollectionView` and `UITableView` integrations
|
||||
- Data and state management
|
||||
- Diffing algorithms
|
||||
|
||||
While IGListKit uses specific tools, we do want to limit the reach of how we use those tools. We highly encourage people to explore solutions that fit their needs and will try to assist when possible. Examples of things beyond the scope of IGListKit:
|
||||
While `IGListKit` uses specific tools, we do want to limit the reach of how we use those tools. We highly encourage people to explore solutions that fit their needs and will try to assist when possible. Examples of things beyond the scope of `IGListKit`:
|
||||
|
||||
- Advanced/custom `UICollectionViewLayout`s
|
||||
- Sizing and layout (e.g. auto layout, estimated sizes)
|
||||
|
|
@ -23,7 +23,7 @@ While IGListKit uses specific tools, we do want to limit the reach of how we use
|
|||
|
||||
## Collaboration & Community
|
||||
|
||||
While IGListKit is an Instagram project, we want to give as much ownership and responsibility to the community as possible. We welcome everyone to become a collaborator on the project with whatever level of contribution you feel comfortable with.
|
||||
While `IGListKit` is an Instagram project, we want to give as much ownership and responsibility to the community as possible. We welcome everyone to become a collaborator on the project with whatever level of contribution you feel comfortable with.
|
||||
|
||||
We recognize that maintaining open source projects can be demanding, and often done in addition to other responsibilities. We have no expectation for the amount or frequency of contribution from anyone.
|
||||
|
||||
|
|
@ -31,4 +31,4 @@ We also ask that you help keep our community welcoming and open.
|
|||
|
||||
## Communication
|
||||
|
||||
GitHub Issues serve as the "source of truth" for all communication and decision-making about IGListKit. This keeps everything open and centralized. We will consider other forms of communication (Slack, Facebook Group, etc) once the scale of the project and/or community demands it.
|
||||
GitHub Issues serve as the "source of truth" for all communication and decision-making about `IGListKit`. This keeps everything open and centralized. We will consider other forms of communication (Slack, Facebook Group, etc) once the scale of the project and/or community demands it.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ The main difference in the setup and architecture of a Core Data and `IGListKit`
|
|||
|
||||
`IGListKit` requires an immutable model in order to correctly calculate the diffing between model snapshots and to correctly animate the `UICollectionView`.
|
||||
|
||||
In order to satisfy these prerequisites, Core Data `NSManagedObject`s should not be used directly as `IGListDiffable` objects. Instead, a view model (or some sort of token object) should be used to mimic (or act as a placeholder for) the data that will be displayed in the collection view.
|
||||
In order to satisfy these prerequisites, Core Data `NSManagedObject`s should not be used directly as `ListDiffable` objects. Instead, a view model (or some sort of token object) should be used to mimic (or act as a placeholder for) the data that will be displayed in the collection view.
|
||||
|
||||
## Further discussion
|
||||
|
||||
|
|
@ -58,13 +58,13 @@ extension UserViewModel {
|
|||
The `IGListDiffable` protocol is implemented on the `ViewModel` layer:
|
||||
|
||||
```swift
|
||||
extension UserViewModel: IGListDiffable {
|
||||
extension UserViewModel: ListDiffable {
|
||||
|
||||
public func diffIdentifier() -> NSObjectProtocol {
|
||||
return NSString(string: firstName + lastName)
|
||||
}
|
||||
|
||||
public func isEqual(toDiffableObject object: IGListDiffable?) -> Bool {
|
||||
public func isEqual(toDiffableObject object: ListDiffable?) -> Bool {
|
||||
guard let toObject = object as? UserViewModel else { return false }
|
||||
|
||||
return self.firstName == toObject.firstName
|
||||
|
|
@ -149,7 +149,7 @@ extension UserProvider: NSFetchedResultsControllerDelegate {
|
|||
The data source retrieves ViewModels and configures the `IGListSectionController` with them:
|
||||
|
||||
```swift
|
||||
func objects(for listAdapter: IGListAdapter) -> [IGListDiffable] {
|
||||
func objects(for listAdapter: ListAdapter) -> [ListDiffable] {
|
||||
return self.userProvider.getUsers()
|
||||
}
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue