Home

Awesome

QuickTableViewController

GitHub Actions Codecov Carthage compatible CocoaPods Compatible Platform Swift 5

A simple way to create a table view for settings, including:

<img src="https://raw.githubusercontent.com/bcylin/QuickTableViewController/gh-pages/img/screenshots.png" width="80%"></img>

Usage

Set up tableContents in viewDidLoad:

import QuickTableViewController

final class ViewController: QuickTableViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    tableContents = [
      Section(title: "Switch", rows: [
        SwitchRow(text: "Setting 1", switchValue: true, action: { _ in }),
        SwitchRow(text: "Setting 2", switchValue: false, action: { _ in })
      ]),

      Section(title: "Tap Action", rows: [
        TapActionRow(text: "Tap action", action: { [weak self] in self?.showAlert($0) })
      ]),

      Section(title: "Navigation", rows: [
        NavigationRow(text: "CellStyle.default", detailText: .none, icon: .named("gear")),
        NavigationRow(text: "CellStyle", detailText: .subtitle(".subtitle"), icon: .named("globe")),
        NavigationRow(text: "CellStyle", detailText: .value1(".value1"), icon: .named("time"), action: { _ in }),
        NavigationRow(text: "CellStyle", detailText: .value2(".value2"))
      ], footer: "UITableViewCellStyle.Value2 hides the image view."),

      RadioSection(title: "Radio Buttons", options: [
        OptionRow(text: "Option 1", isSelected: true, action: didToggleSelection()),
        OptionRow(text: "Option 2", isSelected: false, action: didToggleSelection()),
        OptionRow(text: "Option 3", isSelected: false, action: didToggleSelection())
      ], footer: "See RadioSection for more details.")
    ]
  }

  // MARK: - Actions

  private func showAlert(_ sender: Row) {
    // ...
  }

  private func didToggleSelection() -> (Row) -> Void {
    return { [weak self] row in
      // ...
    }
  }

}

NavigationRow

Detail Text Styles

NavigationRow(text: "UITableViewCellStyle.default", detailText: .none)
NavigationRow(text: "UITableViewCellStyle", detailText: .subtitle(".subtitle")
NavigationRow(text: "UITableViewCellStyle", detailText: .value1(".value1")
NavigationRow(text: "UITableViewCellStyle", detailText: .value2(".value2"))

Subtitle and the initializers with title/subtitle are deprecated and will be removed in v2.0.0.

Accessory Type

var accessoryType: UITableViewCell.AccessoryType {
  switch (action, accessoryButtonAction) {
  case (nil, nil):      return .none
  case (.some, nil):    return .disclosureIndicator
  case (nil, .some):    return .detailButton
  case (.some, .some):  return .detailDisclosureButton
  }
}

Images

enum Icon {
  case named(String)
  case image(UIImage)
  case images(normal: UIImage, highlighted: UIImage)
}

SwitchRow

TapActionRow

OptionRow

let didToggleSelection: (Row) -> Void = { [weak self] in
  if let option = $0 as? OptionRowCompatible, option.isSelected {
    // to exclude the event where the option is toggled off
  }
}

RadioSection

Customization

Rows

All rows must conform to Row and RowStyle. Additional interface to work with specific types of rows are represented as different protocols:

Cell Classes

A customized table view cell type can be specified to rows during initialization.

// Default is UITableViewCell.
NavigationRow<CustomCell>(text: "Navigation", detailText: .none)

// Default is SwitchCell.
SwitchRow<CustomSwitchCell>(text: "Switch", switchValue: true, action: { _ in })

// Default is TapActionCell.
TapActionRow<CustomTapActionCell>(text: "Tap", action: { _ in })

// Default is UITableViewCell.
OptionRow<CustomOptionCell>(text: "Option", isSelected: true, action: { _ in })

Since the rows carry different cell types, they can be matched using either the concrete types or the related protocol:

let action: (Row) -> Void = {
  switch $0 {
  case let option as OptionRow<CustomOptionCell>:
    // only matches the option rows with a specific cell type
  case let option as OptionRowCompatible:
    // matches all option rows
  default:
    break
  }
}

Overwrite Default Configuration

You can use register(_:forCellReuseIdentifier:) to specify custom cell types for the table view to use. See CustomizationViewController for the cell reuse identifiers of different rows.

Table view cell classes that conform to Configurable can take the customization during tableView(_:cellForRowAt:):

protocol Configurable {
  func configure(with row: Row & RowStyle)
}

Additional setups can also be added to each row using the customize closure:

protocol RowStyle {
  var customize: ((UITableViewCell, Row & RowStyle) -> Void)? { get }
}

The customize closure overwrites the Configurable setup.

UIAppearance

As discussed in issue #12, UIAppearance customization works when the cell is dequeued from the storyboard. One way to work around this is to register nib objects to the table view. Check out AppearanceViewController for the setup.

tvOS Differences

Limitation

When to use QuickTableViewController?

QuickTableViewController is good for presenting static table contents, where the sections and rows don't change dynamically after viewDidLoad.

It's possible to update the table contents by replacing a specific section or row. Using different styles on each row requires additional configuration as described in the Customization section.

When not to use it?

QuickTableViewController is not designed for inserting and deleting rows. It doesn't handle table view reload animation either. If your table view needs to update dynamically, you might want to consider other solutions such as IGListKit.

Documentation

Requirements

<details><summary><b>Pre 1.0 versions</b></summary>
QuickTableViewControlleriOStvOSXcodeSwift
~> 0.1.08.0+-6.41.2
~> 0.2.08.0+-7.02.0
~> 0.3.08.0+-7.32.2
~> 0.4.08.0+-8.02.3
~> 0.5.08.0+-8.03.0
~> 0.6.08.0+-8.33.1
~> 0.7.08.0+-9.03.2
~> 0.8.08.0+-9.14.0
~> 0.9.08.0+-9.34.1
</details><br>
QuickTableViewControlleriOStvOSXcodeSwift
~> 1.0.08.0+9.0+9.44.1
~> 1.1.08.0+9.0+10.14.2
~> 1.2.08.0+9.0+10.25.0
~> 1.3.09.0+9.0+11.75.2

Installation

Use Swift Package Manager

Follow the instructions at Adding Package Dependencies to Your App and use version v1.2.1 or later. (requires Xcode 11)

Use CocoaPods

Create a Podfile with the following specification and run pod install.

platform :ios, '9.0'
use_frameworks!

pod 'QuickTableViewController'

Use Carthage

Create a Cartfile with the following specification and run carthage update QuickTableViewController. Follow the instructions to add the framework to your project.

github "bcylin/QuickTableViewController"

Xcode 12 workaround Guide: https://github.com/Carthage/Carthage/blob/master/Documentation/Xcode12Workaround.mdx

Use Git Submodule

git submodule add -b master git@github.com:bcylin/QuickTableViewController.git Dependencies/QuickTableViewController

License

QuickTableViewController is released under the MIT license. See LICENSE for more details. Image source: iconmonstr.