Here's an example how this might look like:

import Imperio
import UIKit

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    var window: UIWindow?
    var initialFlowController: InitialFlowController?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        window = UIWindow(frame: UIScreen.main.bounds)
        window?.makeKeyAndVisible()

        initialFlowController = MainFlowController()
        initialFlowController?.start(from: window!)

        return true
    }
}

Note that you need to call makeKeyAndVisible() on the window. Otherwise you might just see a black screen. Also make sure you are subclassing InitialFlowController instead of FlowController. Refer to the InitialFlowController section above on how to do this.

There are two different cases here:

• passing data into a flow controller
• passing data back to a super flow controller

The first case is simple: Add a property to the flow controller to pass into and add a parameter to its init method. Or in other words: Just use Swift. For example:

class EditProfileFlowController: FlowController {
    private let profile: Profile

    init(profile: Profile) {
        self.profile = profile
        super.init()
    }
}

The second case is a little more work. Add a property to the flow controller to pass back from and add a parameter to its init method. Or in other words: Do the exact same thing as above. But this time, it's a closure. For example:

class ImagePickerFlowController: FlowController {
    typealias ResultClosure = (UIImage) -> Void

    let resultCompletion: ResultClosure

    init(resultCompletion: @escaping ResultClosure) {
        self.resultCompletion = resultCompletion
        super.init()
    }

    // ...
}

Since the ResultClosure parameter is @escaping, you would usually use a [weak self] or [unowned self] when calling the initializer and then map to something like strongSelf to prevent retain cycles & memory leaks. Imperio has a better way to deal with this situation, simply change your code to this:

class ImagePickerFlowController: FlowController {
    let resultCompletion: SafeResultClosure<UIImage>

    init(resultCompletion: SafeResultClosure<UIImage>) {
        self.resultCompletion = resultCompletion
        super.init()
    }

    // ...
}

The usage side then would look like this:

func imagePickerStartButtonPressed() {
    let resultCompletion = SafeResultClosure<UIImage>(weak: self) { (self, pickedImage) in
	       // do something with the result
    }

    let imagePickerFlowCtrl = ImagePickerFlowController(resultCompletion: resultCompletion)
    add(subFlowController: imagePickerFlowCtrl)
    imagePickerFlowCtrl.start(from: mainViewController!)
}

The SafeResultClosure is a wrapper which you pass a strong reference of self to and get a strong reference of self back from as the first parameter. The closure will only be called if self is not nil. This way you can prevent writing [weak self] or [unowned self] in the closure parameters list so – you get safety by default.

SafeResultClosure is part of Imperio and is an implementation of the Delegated pattern described here.

There are two different cases here:

• passing data into view controllers
• passing data back to the flow controller

For passing data into view controllers we recommend using structs that represent the view state. We call them ViewModels. Here's a simple view model:

struct MainViewModel {
    let backgroundColor: UIColor
    var pickedImage: ObservableProperty<UIImage?>
}

Note that for properties that don't change we are simply using a let and the type directly. For properties that might change over time we are using the ObservableProperty wrapper. It's part of Imperio and allows the view controller to subscribe to any changes of the property and react accordingly. Just put your view model into your view controller like so:

class MainViewController: UIViewController {
    // ...
    var viewModel: MainViewModel?
    // ...
}

Now in your viewDidLoad() method you can use the constant properties directly and observe the variable ones like so:

@IBOutlet private var pickedImageView: UIImageView!

override func viewDidLoad() {
    super.viewDidLoad()

    view.backgroundColor = viewModel?.backgroundColor

    viewModel?.pickedImage.didSet(weak: self) { (self, pickedImage) in
        self.pickedImageView.image = pickedImage
    }
}

The strong self which is passed into the didSet() is safely returned back as a strong self as the parameter of the closure. (It's converted to a weak self automatically by Imperio internally.)

Whenever you want to change the pickedImage property, simply use the setValue() method of the ObservableProperty like so:

mainViewController.viewModel.pickerImage.setValue(pickedImage)

As for the second case – passing data back to the flow controller – simply add parameters to your flow delegate methods. For example:

protocol AddressListFlowDelegate: class {
    func didSelectEntry(at index: NSIndexPath)
    func searchFieldTextChanged(to text: String)
}

If you followed our suggestion and created a view model that defines the view state of your view controller, then here's how:

• Initialize a view controller.
• Set its viewModel property to a state you want to test.
• Take a snapshot of the view controllers view property and verify that it didn't change.

The last step is done using the framework FBSnapshotTestCase. Here's a complete example from the demo project:

import Bond
import FBSnapshotTestCase
@testable import Imperio_Demo
import UIKit

class MainViewControllerTests: FBSnapshotTestCase {
    override func setUp() {
        super.setUp()
        self.recordMode = false
    }

    func testRedBackgroundWithHogwartsImage() {
        let mainViewController = UIStoryboard(name: "Main", bundle: nil).instantiateInitialViewController() as? MainViewController
        mainViewController?.viewModel = MainViewModel(backgroundColor: .red, pickedImage: ObservableProperty(#imageLiteral(resourceName: "hogwarts")))
        FBSnapshotVerifyView(mainViewController!.view)
    }
}

If you happen to come across types which already encapsulate some portion of the screen flow, don't try to force-fit them into the structure suggested here. Also don't create view controllers as wrappers just to get handling their delegates out of the flow controller. It is absolutely valid to deviate from the way of passing data or the separation of responsibilities in some circumstances. For example, this is valid:

class ImagePickerFlowController: FlowController {
    override func start(from presentingViewController: UIViewController) {
        presentingViewController.present(instantiateSourceChooser(from: presentingViewController), animated: true)
    }

    func instantiateSourceChooser(from viewController: UIViewController) -> UIAlertController {
        let alertCtrl = UIAlertController(title: "Choose source.", message: "How do you want to choose your image?", preferredStyle: .actionSheet)

        alertCtrl.addAction(UIAlertAction(title: "Camera", style: .default) { [unowned self] _ in
            self.startCamera(from: viewController)
        })

        alertCtrl.addAction(UIAlertAction(title: "Albums", style: .default) { [unowned self] _ in
            self.startImagePicker(from: viewController)
        })

        alertCtrl.addAction(UIAlertAction(title: "Cancel", style: .cancel) { [unowned self] _ in
            self.removeFromSuperFlowController()
        })

        return alertCtrl
    }
}

The UIAlertViewController class is already one that encapsulates how it is rendered. We are simply passing some data here and can't create a view model for it, as the API of the controller is defined differently (with addAction methods). Or another example:

class ImagePickerFlowController: FlowController {
    // ...

    func startCamera(from viewController: UIViewController) {
        let imagePicker = UIImagePickerController()
        imagePicker.sourceType = .camera

        imagePicker.delegate = self
        viewController.present(imagePicker, animated: true)
    }

    func startImagePicker(from viewController: UIViewController) {
        let imagePicker = UIImagePickerController()
        imagePicker.sourceType = .savedPhotosAlbum

        imagePicker.delegate = self
        viewController.present(imagePicker, animated: true)
    }
}

extension ImagePickerFlowController: UIImagePickerControllerDelegate, UINavigationControllerDelegate {
    func imagePickerControllerDidCancel(_ picker: UIImagePickerController) {
        picker.dismiss(animated: true) {
            self.removeFromSuperFlowController()
        }
    }

    func imagePickerController(_ picker: UIImagePickerController, didFinishPickingMediaWithInfo info: [String : Any]) {
        if let pickedImage = info[UIImagePickerControllerOriginalImage] as? UIImage {
            resultCompletion.reportResult(result: pickedImage)
            picker.dismiss(animated: true) {
                self.removeFromSuperFlowController()
            }
        }
    }
}

The reportResult() method is part of SafeResultClosure and must be used to report the result once it is available.

We are dealing with the image picker source types and its delegates methods directly in the flow controller. It is not needed to create extra types to get them out of the flow controller. The UIImagePickerController is already a well tested view controller, we just need to comply to its interface. The same is true for UITabBarController, UINavigationController and UISplitViewController.

Letting your ViewControllers only deal with view logic by moving the flow control to FlowControllers is an important first step. But you might find yourself in a situation, where much of the code which was previously part of your ViewControllers now just moved to your FlowController or where your ViewController is still massive due to complex UI handling.

To prevent these issues, we can apply an idea from the Lotus pattern: ModelControllers.

ModelControllers can take the responsibility of bringing the data to the view controllers off the FlowControllers. There are two kinds of ModelControllers: Shared and View-specific ones.

Typical responsibilities for shared ModelControllers are:

• managing network requests (API, Logger, Analytics)
• accessing storage systems (Files, Core Data, UserDefaults)
• reading sensor data (GPS, gyroscope, accelerometer)

Typical responsibilities for specific ModelControllers are:

• implementing UITableViewDataSource & UICollectionViewDataSource
• state machines for complex view controller logic

Shared ModelControllers are typically globally reachable and could use the Singleton pattern. Both your ViewControllers and FlowControllers could therefore use them. View-specific ModelControllers are typically only needed for more complex ViewControllers and are created by them as well as hold a strong reference to them.

So, use ModelControllers wherever you might need them to prevent the Massive Flow/View Controller problem.