ml-archive/paginator
This package currently offers support for offset pagination on `Array` and `QueryBuilder`.
📦 Installation
Add Paginator to the package dependencies (in your Package.swift file):
dependencies: [
...,
.package(url: "https://github.com/nodes-vapor/paginator.git", from: "4.0.0")
]as well as to your target (e.g. "App"):
targets: [
...
.target(
name: "App",
dependencies: [... "Paginator" ...]
),
...
]Next, copy/paste the Resources/Views/Paginator folder into your project in order to be able to use the provided Leaf tags. These files can be changed as explained in the Leaf Tags section, however it's recommended to copy this folder to your project anyway. This makes it easier for you to keep track of updates and your project will work if you decide later on to not use your own customized leaf files.
Getting started 🚀
First make sure that you've imported Paginator everywhere it's needed:
import PaginatorAdding the Leaf tag
In order to do pagination in Leaf, please make sure to add the Leaf tag:
public func configure(_ config: inout Config, _ env: inout Environment, _ services: inout Services) throws {
services.register { _ -> LeafTagConfig in
var tags = LeafTagConfig.default()
tags.use([
"offsetPaginator": OffsetPaginatorTag(templatePath: "Paginator/offsetpaginator")
])
return tags
}
}If you want to fully customize the way the pagination control are being generated, you are free to override the template path.
QueryBuilder
To return a paginated result from QueryBuilder, you can do the following:
router.get("galaxies") { (req: Request) -> Future<OffsetPaginator<Galaxy>> in
return Galaxy.query(on: req).paginate(on: req)
}Array
For convenience, Paginator also comes with support for paginating Array:
router.get("galaxies") { (req: Request) -> Future<OffsetPaginator<Galaxy>> in
let galaxies = [Galaxy(), Galaxy(), Galaxy()]
return galaxies.paginate(on: req)
}RawSQL
Paginator also comes with support for paginating raw SQL queries for complex expressions not compatible with Fluent.
Simple example using PostgreSQL:
router.get("galaxies") { (req: Request) -> Future<OffsetPaginator<Galaxy>> in
return req.withPooledConnection(to: .psql) { conn -> Future<OffsetPaginator<Galaxy>> in
let rawBuilder = RawSQLBuilder<PostgreSQLDatabase, Galaxy>(
query: """
SELECT *
FROM public."Galaxy"
""", countQuery: """
SELECT COUNT(*) as "count"
FROM public."Galaxy"
""", connection: conn)
return try rawBuilder.paginate(on: req)
}
}Note: the count query is expected to have a result with one column named count and with the total columns value in the first row
Transforming
The data in an OffsetPaginator can be transformed by mapping over the paginator and transforming each element at a time:
Galaxy.query(on: req).paginate(on: req).map { paginator in
paginator.map { (galaxy: Galaxy) -> GalaxyViewModel in
GalaxyViewModel(galaxy: galaxy)
}
}You can also transform a whole page of results at once:
Galaxy.query(on: req).paginate(on: req).map { paginator in
paginator.map { (galaxies: [Galaxy]) -> [GalaxyViewModel] in
galaxies.map(GalaxyViewModel.init)
}
}In case the transformation requires async work you can do:
Galaxy.query(on: req).paginate(on: req).map { paginator in
paginator.flatMap { (galaxies: [Galaxy]) -> Future<[GalaxyViewModel]> in
galaxies.someAsyncMethod()
}
}Configuration
The OffsetPaginator has a configuration file (OffsetPaginatorConfig) that can be overwritten if needed. This can be done in configure.swift:
public func configure(_ config: inout Config, _ env: inout Environment, _ services: inout Services) throws {
// ..
services.register(OffsetPaginatorConfig(
perPage: 1,
defaultPage: 1
))
}🏆 Credits
This package is developed and maintained by the Vapor team at Nodes.
📄 License
This package is open-sourced software licensed under the MIT license
Package Metadata
Repository: ml-archive/paginator
Default branch: master
README: README.md