StatefulCollections 1.0.2

StatefulCollections 1.0.2

Maintained by Guillem Espejo.



  • By
  • Guillem Espejo

StatefulCollections

Simple stateful collection views for iOS in Swift.

Swift Version Build Status License Cocoapods Compatible Platform PRs Welcome

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.

Features

  • Simple to use
  • Customizable
  • Supports empty, loading and error states

Requirements

  • iOS 13.0+
  • Xcode 11.3

Installation

CocoaPods

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'

Basic Usage

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).

Customization

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)

Reset states and colors

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)

Contribute

If you want to contribute to StatefulCollections, check the LICENSE file for more info.

Meta

Guillem Espejo – [email protected]

Distributed under the MIT license. See LICENSE for more information.

https://github.com/GuillemEspejo/github-link