laubengaier/swordinator

Swordinator is a simple way of integrating an iOS Coordinator pattern.

Swordinator is a minimal, lightweight and easy customizable navigation framework for iOS applications.

Requirements

iOS 13.0+, Swift 5.0+

Installation

Swift Package Manager

dependencies: [
    .package(url: "https://github.com/laubengaier/Swordinator.git", .upToNextMajor(from: "1.0.0"))
]

Use Swordinator

These steps should provide a simple way of getting started. If something is not clear please take a look at the demo provided or create an issue.

Quicknote:

The simplest way is to go forward with implementing Step and using handle(step: Step) which simplifies the coordination but if you want even more control or don't like steps there is a delegate example in the demo (NoStepCoordinator).

1. Define Steps

Create a new class called AppStep or anything you like that will define the steps your application can do.

enum AppStep: Step 
{
    // task list
    case taskList
    
    // task detail
    case taskDetail
    case taskDetailCompleted
    
    // auth
    case auth
    case authCompleted
    case logout
}

2. Setup AppCoordinator

Create a new class called AppCoordinator or similar that defines the entry point to your app.

class AppCoordinator: Coordinator 
{
    let window: UIWindow
    var rootCoordinator: Coordinator?
    var childCoordinators: [Coordinator] = []
    
    let services: AppServices
    
    init(window: UIWindow, services: AppServices, step: AppStep) {
        self.window = window
        self.services = services
        start(step: step)
    }
    
    func start(step: Step) {
        if services.isAuthenticated {
            handle(step: .dashboard)
        } else {
            handle(step: .auth)
        }
    }
    
    func handle(step: Step) {
        guard let step = step as? AppStep else { return }
        switch step {
        case .auth:
            showLogin()
        case .taskList:
            showTaskList()
        default:
            return
        }
    }
}

extension AppCoordinator 
{
    private func showLogin() {
        // show login
    }
    
    private func showTaskList() {
        let nvc = UINavigationController()
        let coordinator = TaskListCoordinator(navigationController: nvc, services: services)
        coordinator.parent = self
        rootCoordinator = coordinator
        window.rootViewController = nvc
    }
}

3. AppDelegate / Scene

class SceneDelegate: UIResponder, UIWindowSceneDelegate 
{

    var window: UIWindow?
    var appCoordinator: AppCoordinator?
    let appServices = AppServices()

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        if let windowScene = scene as? UIWindowScene {
            let window = UIWindow(windowScene: windowScene)
            appCoordinator = AppCoordinator(window: window, services: appServices)
            self.window = window
            window.makeKeyAndVisible()
        }
    }
    
    // ...
}

Deeplinks

If you want to support deeplinks in your application you just need to let your Coordinator classes adapt to Deeplinkable as following:

class AppCoordinator: Coordinator, Deeplinkable {

    //...
    var rootCoordinator: (Coordinator & Deeplinkable)?
    
    //...
    
    func handle(deepLink: DeeplinkStep) {
        if let root = rootCoordinator {
            root.handle(deepLink: deepLink)
        }
    }
}

This comes in pretty handy when dealing with Universal Links or Push Notifications. The rootCoordinator should be seen as the current active Coordinator so if there is a event then it can be forwarded to the top most active coordinator or handled anywhere in between.

In the Demo application there is a taskDetail deeplink that will be forwarded to either the TaskList or Profile and handled there.

Illustrated here Demo Flow

Important Notice

Memory Leaks

To avoid memory leaks you should pay attention to releasing the Coordinators from childCoordinators when they are not used anymore.

For Example:

func handle(step: Step) {
    guard let step = step as? AppStep else { return }
    switch step {
    case .taskDetailCompleted:
        childCoordinators.removeAll { $0 is TaskDetailCoordinator }
    }
}

Demo Application

A demo is provided to show the core mechanics and how to apply the coordinator pattern.

Login	Dashboard	Profile

Deeplinks

Run the following commands in your terminal to test deeplinks with the simulator

# lazy load and show a task
xcrun simctl openurl booted swordinator://tasks/1
# taskList, switch tab
xcrun simctl openurl booted swordinator://tasks
# profile, switch tab
xcrun simctl openurl booted swordinator://profile
# profile settings, switch tab to profile and open settings
xcrun simctl openurl booted swordinator://settings
# logout
xcrun simctl openurl booted swordinator://logout

Pattern

Demo Flow

This is an illustration of how the pattern is used in the demo application

Mentions

RxFlow This project is inspired by RxFlow which is a great way to use Coordinators in a reactive manner but imho it's not always clear what is happening behind the scenes so this project should provide a more simplified way to integrate and gain more control.

License

This code is distributed under the MIT license. See the LICENSE file for more info.