getting-started.md

QRoute

QRoute /'kyoo•root/ - n - Declarative walking router for UI navigation.

Getting Started

This guide will help you get started with using QRoute, and assumes you already know your way around Xcode and/or the Swift Package Manager.

1) Install the package

Either add it as a submodule (for use with Xcode), otherwise use SwiftPM ...

Using Xcode

When importing the library for use in an Xcode project (such as for an iOS or OSX app), then the thing to do is add it as a git submodule:

    mkdir -p submodule
    git submodule add https://github.com/quickthyme/qroute.git submodule/qroute

Next, link the QRoute.xcodeproj as a dependency of your project by dragging it from the Finder into your open project or workspace.

Once you have the project linked, it's build scheme and products will be selectable from drop-downs in your Xcode project. Just add QRoute to your target's dependencies and libQRoute.a to the linking phase, and you're all set!

Using the Swift Package Manager

QRoute supports the Swift Package Manager. It works fine in any Swift project on any Swift platform, including OSX and Linux. Just add the dependency to your Package.swift file:

• package: QRoute
• url: https://github.com/quickthyme/qroute.git

Then just ...

    swift build

That's it, nothing else to do except start using it.

2) Compose a route plan

    import QRoute

    let plan =
        QRoute(id.Root,

	        QRoute(id.ToDo,
	            QRoute(id.ToDoDetail,
	                    dependencies: ["toDoId"])),

	        QRoute(id.Help,
	            QRoute(id.ContactUs),
	            QRoute(id.MessageCenter)))

3) Implement your routables:

    class RoutableViewController: UIViewController, QRoutable {
        var routeInput: QRoutableInput?
        var routeResolver: QRouteResolving?
    }

4) Implement your custom resolvers:

    func resolveRouteToParent(from: QRoutable,
	                          input: QRoutableInput,
	                          completion: @escaping QRoutableCompletion) {

        (from as? UIViewController)?
            .navigationController?
            .popViewController(animated: true) {
                if let parent = navController.topViewController as? QRoutable {
                    mergeInputDependencies(target: parent, input: input)
                    completion(parent)
                }}
	}

5) Invoke the driver:

    var routeDriver: QRouteDriving?

    @IBAction func dismissAction(_ sender: AnyObject?) {
        routeDriver?.driveParent(from: self, input: nil,
                                 animated: true,
                                 completion: nil)
        }
    }

6) Write some tests:

    when("making selection") {
        mockRouteDriver.reset()
        subject.toDoTableViewManager(ToDoTableViewManager(), didSelectId: 36)

        then("it should drive to ToDoDetail with toDoId input") {
            XCTAssertEqual(mockRouteDriver.timesCalled_driveTo, 1)
            XCTAssertEqual(mockRouteDriver.valueFor_driveTo_targetId, AppRoute.id.ToDoDetail)
            XCTAssertEqual(mockRouteDriver.valueFor_driveTo_input?["toDoId"] as? Int, 36)
        }
    }