Turbo Navigator

A drop-in class for Turbo Native apps to handle common navigation flows.

Note: This package is still being actively developed and subject to breaking changes without warning.

Why use this?

Turbo Native apps require a fair amount of navigation handling to create a decent experience.

Unfortunately, not much of this is built into turbo-ios. A lot of boilerplate is required to have anything more than basic pushing/popping of screens.

This package abstracts that boilerplate into a single class. You can drop it into your app and not worry about handling every flow manually.

I've been using something a version of this on the dozens of Turbo Native apps I've built over the years.

Handled flows

When a link is tapped, turbo-ios sends a VisitProposal to your application code. Based on the Path Configuration, different PathProperties will be set.

Current context - What state the app is in.
- modal - a modal is currently presented
- default - otherwise
Given context - Value of context on the requested link.
- modal or default/blank
Given presentation - Value of presentation on the proposal.
- replace, pop, refresh, clear_all, replace_root, none, default/blank
Navigation - The behavior that the navigation controller provides.

Current Context	Given Context	Given Presentation	New Presentation
`default`	`default`	`default`	Push on main stack (or) Replace if visiting same page (or) Pop (and visit) if previous controller is same URL
`default`	`default`	`replace`	Replace controller on main stack
`default`	`modal`	`default`	Present a modal with only this controller
`default`	`modal`	`replace`	Present a modal with only this controller
`modal`	`default`	`default`	Dismiss then Push on main stack
`modal`	`default`	`replace`	Dismiss then Replace on main stack
`modal`	`modal`	`default`	Push on the modal stack
`modal`	`modal`	`replace`	Replace controller on modal stack
`default`	(any)	`pop`	Pop controller off main stack
`default`	(any)	`refresh`	Pop on main stack then
`modal`	(any)	`pop`	Pop controller off modal stack (or) Dismiss if one modal controller
`modal`	(any)	`refresh`	Pop controller off modal stack then Refresh last controller on modal stack (or) Dismiss if one modal controller then Refresh last controller on main stack
(any)	(any)	`clearAll`	Dismiss if modal controller then Pop to root then Refresh root controller on main stack
(any)	(any)	`replaceRoot`	Dismiss if modal controller then Pop to root then Replace root controller on main stack
(any)	(any)	`none`	Nothing

Examples

To present forms (URLs ending in /new or /edit) as a modal, add the following to the rules key of your Path Configuration.

{
  "patterns": [
    "/new$",
    "/edit$"
  ],
  "properties": {
    "context": "modal"
  }
}

To hook into the "refresh" turbo-rails native route, add the following to the rules key of your Path Configuration. You can then call refresh_or_redirect_to in your controller to handle Turbo Native and web-based navigation.

{
  "patterns": [
    "/refresh_historical_location"
  ],
  "properties": {
    "presentation": "refresh"
  }
}

Getting started

Check out the Demo app for an example on how to use Turbo Navigator.

More detailed instructions are coming soon. PRs are welcome!

Demo project

The Demo/ directory includes an iOS app and Ruby on Rails server to demo the package.

It shows off most of the navigation flows outlined above. There is also an example CRUD resource for more real world applications of each.

Custom controller and routing overrides

You can also implement an optional method on the TurboNavigationDelegate to handle custom routing.

This is useful to break out of the default behavior and/or render a native screen.

class MyCustomClass: TurboNavigationDelegate {
    let navigator = TurboNavigator(delegate: self)

    func controller(_ controller: VisitableViewController, forProposal proposal: VisitProposal) -> UIViewController? {
        if proposal.url.path == "/numbers" {
            // Let Turbo Navigator route this custom controller.
            return NumbersViewController()
        } else if proposal.presentation == .clearAll {
            // Return nil to tell Turbo Navigator stop processing the request.
            return nil
        } else {
            // Return the given controller to continue with default behavior.
            // Optionally customize the given controller.
            controller.view.backgroundColor = .orange
            return controller
        }
    }
}

Custom configuration

Customize the configuration via TurboConfig.

Override the user agent

Keep "Turbo Native" to use turbo_native_app? on your Rails server.

TurboConfig.shared.userAgent = "Custom (Turbo Native)"

Customize the web view and web view configuration

A block is used because a new instance is needed for each web view.

Don't forget to set user agent and use a shared process pool on the configuration.

TurboConfig.shared.makeCustomWebView = {
    let configuration = WKWebViewConfiguration()
    // Customize configuration.

    let webView = WKWebView(frame: .zero, configuration: configuration)
    // Customize web view.

    return webView
}

Customize behavior for external URLs

Turbo cannot navigate across domains because page visits are done via JavaScript. A clicked link that points to a different domain is considered external.

By default, a SFSafariViewController is presented. This can be overridden by implementing the following delegate method.

class MyCustomClass: TurboNavigationDelegate {
    func openExternalURL(_ url: URL, from controller: UIViewController) {
        // Do something custom with the external URL.
        // The controller is provided to present on top of.
    }
}

arusa/TurboNavigator