Simple stateful collection views for iOS in Swift.
StatefulCollections is a small and lightweight Swift framework that allows to create UITableviews and UICollectionViews that support empty, loading and error states as easy as possible.
It can be partially customized to allow greater flexibility while keeping things simple. It has a nice balance between view customization and ease of use.
CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate StatefulCollections into your Xcode project using CocoaPods, specify it in your Podfile
:
pod 'StatefulCollections'
The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift
compiler.
Once you have your Swift package set up, adding StatefulCollections as a dependency is as easy as adding it to the dependencies
value of your Package.swift
.
dependencies: [
.package(url: "https://github.com/GuillemEspejo/StatefulCollections.git", .upToNextMajor(from: "1.0.2"))
]
Import StatefulCollections module wherever you have a reference to a UITableView or UICollectionView that will be used as stateful. Set your collection style view classes to its matching subclass, StatefulTableView or StatefulCollectionView
import StatefulCollections
// Other imports ...
class ViewController: UIViewController {
@IBOutlet weak var tableview: StatefulTableView!
@IBOutlet weak var collectionview: StatefulCollectionView!
// ...
}
Set the class and the import module in storyboard if needed.
When you want to set the state of the view, set it using setStateTo
:
tableview.setState(to: .loading)
collectionview.setState(to: .empty)
Both views support four different states:
State | View | Image | Text | Use |
---|---|---|---|---|
.normal | Standard view appearance. | N/A | N/A | Used as default state, when there is content to show. |
.loading | Removes cell separator, shows activity indicator and the default text. | N/A | 'Loading...' | Used when loading or processing data (Core Data, networking, file parsing, etc). |
.emtpy | Removes cell separator, shows SF Image and the default text. | 'text.badge.xmark' | 'No results' | Used when there are no results to show. |
.error | Removes cell separator, shows SF Image and the default text. | 'xmark.octagon' | 'There was an unknown error' | Used when the process of obtaining data for the collection has failed (I/O errors, networking,etc). |
StatefulCollections allow a certain degree of customization but tries to keep things as simple as possible.
Although you can't add or remove the basic view components of each state, the ones shown can be customized. Images, labels and separator styles can be freely modified.
For example:
tableview.setState(to: .error)
will give your tableview the following appearance:
However, you can set the image and the text to another values:
let errorImage = UIImage(systemName: "clear")
tableview.setImage(to: errorImage, forState: .error)
tableview.setText(to: "Network error", forState: .error)
// ...
tableview.setState(to: .error)
Besides setting custom images and text, you can also set custom tints and colors. The colors are applied to the views itself and are not dependant on the state.
tableview.setImageTint(to: .red)
tableview.setTextColor(to: .blue)
If you want to reset any state appearance to its original settings, just use resetState
or resetAllStates
:
tableview.setText(to: "Server error", forState: .error)
tableview.setText(to: "Loading data from disk...", forState: .loading)
tableview.setText(to: "There were no results for your query", forState: .empty)
// ...
tableview.reset(state: .error) // Only error state will be reset
// ...
tableview.resetAllStates() // Every state will be reset to default values
Due to the colors being independent of the state, when you need custom colors for a single one, you must set them every time you set that state, and reset them when another one is shown.
tableview.setImageTint(to: .red)
tableview.setTextColor(to: .yellow)
tableview.setState(to: .error)
// ...
tableview.resetTextColor()
tableview.resetImageTint()
tableview.setState(to: .empty)
If you want to contribute to StatefulCollections, check the LICENSE
file for more info.
Guillem Espejo – [email protected]
Distributed under the MIT license. See LICENSE
for more information.
link |
Stars: 1 |
Last commit: 3 years ago |
Added full version of code after refactoring. Added example project to repository.
Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics