Declarative type-safe manager for UITableView & UICollectionView

Register Adapters (TableAdapter/CollectionAdapter)

Once you have a director you need to tell to it what kind of data you are about to render: you can have an etherogeneus collection of Models and View (cells) in your scroller but a single Model can be rendered to a single type of View.

Suppose you want to render two types of models:

• Contact instances using ContactCell view
• ContactGroup instances using ContactGroupCell view

You will need two adapters:

let contactAdpt = TableAdapter<Contact,ContactGroup>()
let groupAdpt = TableAdapter<ContactGroup,ContactGroupCell>()
tableView.director.register(adapters: [contactAdpt, groupAdpt])

Now you are ready to present your data.

Create Data Models (ModelProtocol)

In order to render your data each object of the scroller must be conform to ModelProtocol which includes:

• Must be conform to Hashable protocol (this is used to perform built-in automatic animations we'll see later)
• Must implement a simple identifier property (used above)

This is an example implementation of Contact model:

public class Contact: ModelProtocol, Hashable {
	public var name: String
	public var GUID: String = NSUUID().uuidString

	public var identifier: Int {
		return GUID.hashValue
	}
	
	public static func == (lhs: Contact, rhs: Contact) -> Bool {
		return lhs.GUID == rhs.GUID
	}
		
	public init(_ name: String) {
		self.name = name
	}
}

Create Cells (UITableViewCell/UICollectionViewCell)

Both UITableViewCell and UICollectionViewCell and its subclasses are automatically conforms to CellProtocol.

The only constraint is about reuseIdentifier: cells must havereuseIdentifier (Identifier in Interface Builder) the name of the class itself..

If you need you can override this behaviour by overrinding the reuseIdentifier: String property of your cell and returing your own identifier.

Cell can be loaded in three ways:

• Cells from Storyboard: This is the default behaviour; you don't need to do anything, cells are registered automatically.
• Cells from XIB files: Be sure your xib files have the same name of the class (ie. ContactCell.xib) and the cell as root item.
• Cells from initWithFrame: Override CellProtocol's registerAsClass to return true.

This is a small example of the ContactCell:

public class ContactCell: UITableViewCell {
	@IBOutlet public var labelName: UILabel?
	@IBOutlet public var labelSurname: UILabel?
	@IBOutlet public var icon: UIImageView?
}

Add Sections (TableSection/CollectionSection)

Each Table/Collection must have at least one section to show something.
TableSection/CollectionSection instances hold the items to show (into .models property) and optionally any header/Footer you can apply.

In order to manage sections of your table you need to use the following methods of the parent Director:

• set(models:) change the section of the table/collection.
• section(at:) return section at index.
• firstSection() return first section, if any.
• lastSection() return last section, if any.
• add(section:at:) add or insert a new section.
• add(sections:at:) add an array of sections.
• add(models:) create a new section with given models inside and add it.
• removeAll(keepingCapacity:) remove all sections.
• remove(section:) remove section at given index.
• remove(sectionsAt:) remove sections at given indexes set.
• move(swappingAt:with:) swap section at given index with destination index.
• move(from:to) combo remove/insert of section at given index to destination index.

The following example create a new TableSection with some items inside, a String based header, then append it a the end of the table.

let section = TableSection(headerTitle: "The Strangers", items: [mrBrown,mrGreen,mrWhite])
table.director.add(section: section)

Manage Models/Items in Section

As for section the same add/remove/move function are also available for models array which describe the content (rows/items) inside each section (TableSection/CollectionSection instances).

This is the complete list:

• set(models:) change models array.
• add(model:at:) add model at given index, if nil is append at the bottom.
• add(models:at:) add models starting at given index; if nil models are append at the bottom.
• remove(at:) remove model at given index.
• remove(atIndexes:) remove models at given index set.
• removeAll(keepingCapacity:) remove all models of the section.
• move(swappingAt:with:) Swap model at given index to another destination index.
• move(from:to:) Remove model at given index and insert at destination index.

After any change you must call the director.reloadData() function from main thread to update the UI.

This is an example of items management:

let section = self.tableView.director.firstSection()

let newItems = [Contact("Daniele","Margutti"),Contact("Fabio","Rossi")]
section.add(models: newItems) // add two new contacts
section.remove(at: 0) // remove first item

// ...
self.tableView.director.reloadData() // reload data

Setup Headers & Footers (TableSectionView/CollectionSectionView)

Simple Header/Footer

Section may have or not headers/footers; these can be simple String (as you seen above) or custom views.

Setting simple headers is pretty straightforward, just set the headerTitle/footerTitle:

section.headerTitle = "New Strangers"
section.footerTitle = "\(contacts.count) contacts")

Custom View Header/Footer

To use custom view as header/footer you need to create a custom xib file with a UITableViewHeaderFooterView (for table) or UICollectionReusableView (for collection) view subclass as root item.

The following example shows a custom header and how to set it:

// we also need of TableExampleHeaderView.xib file
// with TableExampleHeaderView view as root item
public class TableExampleHeaderView: UITableViewHeaderFooterView {
	@IBOutlet public var titleLabel: UILabel?
}

// create the header container (will receive events)
let header = TableSectionView<TableExampleHeaderView>()
// hooks any event. You need at least the `height` as below
header.on.height = { _ in
	return 150
}

// Use it
let section = TableSection(headerView: header, items: [mrBrown,mrGreen,mrWhite])
table.director.add(section: section)

Reload Data with/out Animations

Each change to the data model must be done by calling the add/remove/move function available both at sections and items levels.
After changes you need to call the director's reloadData() function to update the UI.

The following example update a table after some changes:

// do some changes
tableView.director.remove(section: 0)
tableView.director.add(section: newSection, at: 2)
...
tableView.director.firstSection().remove(at: 0)

// then reload
tableView.director.reloadData()

If you need to perform an animated reload just make your changes to the model inside the callback available into the method.
Animations are evaluated and applied for you!

tableView.director.reloadData(after: { _ in
	tableView.director.remove(section: 0)
	tableView.director.add(section: newSection, at: 2)
	
	return TableReloadAnimations.default()
})

For TableDirector you must provide a TableReloadAnimations configuration which defines what kind of UITableViewRowAnimation must be applied for each type of change (insert/delete/reload/move). TableReloadAnimations.default() just uses .automatic for each type.

For CollectionDirector you don't need to return anything; evaluation is made for you based upon the layout used.

Listen for Events

All events are hookable from their respective objects starting from .on property. All standard table & collections events are available from FlowKit; name of the events is similar to the their standard corrispettive in UIKit (see the official documentation for more info abou any specific event).

Sizing Cells

FlowKit support easy cell sizing using autolayout.
You can set the size of the cell by adapter or collection based. For autolayout driven cell sizing set the rowHeight (for TableDirector) or itemSize (for CollectionDirector/FlowCollectionDirector) to the autoLayout value, then provide an estimated value.

Accepted values are:

• default: you must provide the height (table) or size (collection) of the cell
• autoLayout: uses autolayout to evaluate the height of the cell; for Collection Views you can also provide your own calculation by overriding preferredLayoutAttributesFitting() function in cell instance.
• fixed: provide a fixed height for all cell types (faster if you plan to have all cell sized same)

Installation

Install via CocoaPods

CocoaPods is a dependency manager which automates and simplifies the process of using 3rd-party libraries like FlowKit in your projects. You can install it with the following command:

$ sudo gem install cocoapods

CocoaPods 1.0.1+ is required to build FlowKit.

Install via Podfile

To integrate FlowKit into your Xcode project using CocoaPods, specify it in your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'

target 'TargetName' do
use_frameworks!
pod 'FlowKitManager'
end

Then, run the following command:

$ pod install

Carthage

Requirements

FlowKit is compatible with Swift 4.x.

• iOS 9.0+

GitHub