A library that adds additional Kotlin/Multiplatform targets to AndroidX Paging, and provides UI components to use Paging on iOS.
As with AndroidX Paging, the primary modules of Multiplatform Paging are:
-
paging-common
– encompasses the repository layer and the view model layer -
paging-runtime
– encompasses the UI layer
Unlike AndroidX Paging that has a limited number of targets for paging-common
and makes paging-runtime
Android-specific,
Multiplatform Paging adds many more targets to paging-common
and provides paging-runtime-uikit
, a UIKit-specific runtime for iOS.
Therefore, pagination logic between many more targets can be shared,
and the provided UI components can be used to render the paged items on Android and iOS.
For a holistic view of Multiplatform Paging, check out the GitHub Repository Search sample project, where there's an Android, Desktop, and iOS app, along with shared pagination logic.
The API of paging-common
in Multiplatform Paging is identical to that of paging-common
in AndroidX Paging
(with the exception that: the namespace has changed from androidx.paging
to app.cash.paging
;
there are some minor API discrepancies due to limitations in the Kotlin compiler).
Therefore, to see how to use paging-common
, consult the official documentation of AndroidX Paging.
Like AndroidX Paging, all targets except for the JVM include the Paging 3 APIs only from AndroidX Paging. There are no plans to add support for Paging 2 APIs beyond the JVM.
app.cash.paging:paging-common
on these targets delegate to androidx.paging:paging-common
via type aliases.
To understand what this means in practice, see the section Interoperability with AndroidX Paging.
app.cash.paging:paging-common
on these targets delegate to our fork of AndroidX Paging.
The API of paging-compose-common
in Multiplatform Paging is identical to that of paging-compose
in AndroidX Paging
(with the exception that the namespace has changed from androidx.paging
to app.cash.paging
).
To see how to use paging-compose-common
, consult the official documentation of AndroidX Paging.
app.cash.paging:paging-compose-common
on Android delegates to androidx.paging:paging-compose
via type aliases.
To understand what this means in practice, see the section Interoperability with AndroidX Paging.
app.cash.paging:paging-compose-common
on the these targets delegate to our fork of AndroidX Paging.
See the Interoperability with AndroidX Paging section below.
The PagingCollectionViewController
allows a PagingData
to be rendered via a UICollectionView
.
The PagingCollectionViewController
mimics the UICollectionViewController
,
providing: the cell count; and item retrieval via IndexPath
.
Here's an example in Swift:
final class FooViewController: UICollectionViewController {
private let delegate = Paging_runtime_uikitPagingCollectionViewController<Foo>()
private let presenter = …
required init(coder: NSCoder) {
super.init(coder: coder)!
presenter.pagingDatas
.sink { pagingData in
self.delegate.submitData(pagingData: pagingData, completionHandler: …)
}
}
override func collectionView(
_ collectionView: UICollectionView,
numberOfItemsInSection section: Int
) -> Int {
return Int(delegate.collectionView(collectionView: collectionView, numberOfItemsInSection: Int64(section)))
}
override func collectionView(
_ collectionView: UICollectionView,
cellForItemAt indexPath: IndexPath
) -> UICollectionViewCell {
let cell = collectionView.dequeueReusableCell(withReuseIdentifier: "FooCell", for: indexPath) as! FooCell
let item = delegate.getItem(position: Int32(indexPath.row))!
// …
return cell
}
}
The API of paging-testing
in Multiplatform Paging is identical to that of paging-testing
in AndroidX Paging
(with the exception that the namespace has changed from androidx.paging
to app.cash.paging
).
Therefore, to see how to use paging-testing
, consult the official documentation of AndroidX Paging.
app.cash.paging:paging-testing
on these targets delegate to androidx.paging:paging-testing
via type aliases.
To understand what this means in practice, see the section Interoperability with AndroidX Paging.
app.cash.paging:paging-common
on these targets delegate to our fork of AndroidX Paging.
As app.cash.paging:paging-common
on the JVM, iOS, Linux X64, and macOS type alias to androidx.paging:paging-common
,
some useful side effects occur:
- The implementation of
app.cash.paging:paging-common
on the JVM, iOS, Linux X64, and macOS is identical toandroidx.paging:paging-common
. This means that it is impossible for there to be a behavioral discrepancy when usingapp.cash.paging:paging-common
on the JVM, iOS, Linux X64, or macOS. - All libraries that depend on
androidx.paging:paging-common
can continue to be used. Some JVM-specific examples includeandroidx.paging:paging-runtime
,androidx.paging:paging-compose
, andandroidx.paging:paging-rxjava3
. This is why there aren't additionalpaging-runtime
artifacts to support Android's UI toolkit, as you can instead depend on the official AndroidX artifact. - If you're already using AndroidX Paging, you don't need to refactor your existing codebase to begin using Multiplatform Paging.
The use of Multiplatform Paging is only necessary if you wish to share pagination logic on targets that AndroidX Paging don't yet support, or you want to use pagination UI bindings on platforms like iOS via
paging-runtime-uikit
.
A similar argument can be made for app.cash.paging:paging-compose-common
and app.cash.paging:paging-testing
.
The versioning scheme is of the form X-Y
where:
-
X
is the AndroidX Paging version that is being tracked. -
Y
is the Multiplatform Paging version.
For example, if AndroidX Paging is on 3.3.0-alpha02
and Multiplatform Paging is on 0.5.1
,
the artifact for a release of paging-common
will be app.cash.paging:paging-common:3.3.0-alpha02-0.5.1
.
implementation("app.cash.paging:paging-common:3.3.0-alpha02-0.5.1")
implementation("app.cash.paging:paging-compose-common:3.3.0-alpha02-0.5.1")
implementation("app.cash.paging:paging-runtime-uikit:3.3.0-alpha02-0.5.1")
implementation("app.cash.paging:paging-testing:3.3.0-alpha02-0.5.1")
Use the official AndroidX Paging dependencies.
implementation("androidx.paging:paging-runtime:3.3.0-alpha02")
implementation("androidx.paging:paging-compose:3.3.0-alpha02")
implementation("androidx.paging:paging-rxjava3:3.3.0-alpha02")
// etc.
Copyright 2022 Block, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.