Skip to content

Reference

There are a few main types in Hotwire Native iOS, most notably Navigator and Visitable.

The Navigator is the central coordinator in a Hotwire Native iOS application. Each Navigator manages the stack of screens via a UINavigationController with a single, shared WKWebView instance. It lets your app choose how to handle link taps, present view controllers, and deal with errors.

﹟ Creating a Navigator

Create with no parameters to use the default configuration:

let navigator = Navigator()

Provide optional path configuration to configure settings and path rules:

let navigator = Navigator(pathConfiguration: pathConfiguration)

Provide an optional delegate to configure how different URLs, errors, and external links are handled:

let navigator = Navigator(delegate: delegate)

extension SceneController: NavigatorDelgate {
    // ...
}

Customize the underlying WKWebView and configuration with a block. For example, to use a custom WKProcessPool to share cookies from web views outside of Hotwire Native:

Hotwire.config.makeCustomWebView = { config in
    config.processPool = processPool
    return WKWebView(frame: .zero, configuration: config)
}

The delegate is an optional interface you can implement to customize behavior of the Navigator.

﹟ Handling Proposals

Hotwire Native iOS calls the handle(proposal:) method before every visit, such as when you tap a Turbo-enabled link or call Turbo.visit(...) in your web application. Implement this function to choose how to handle the specified URL and action. This is called a proposal since your application is not required to complete the visit.

Return one of the following three ProposalResult cases:

﹟ Handling External URLs

Implement handle(externalURL:) to customize the behavior when an external URL is visited. URLs are considered “external” if they do not match the same domain as the first visited link. By default, this will present a SFSafariViewController modally.

﹟ Handling Errors

Network errors and responses with HTTP status codes outside of the 200 range are considered errors. By default a native screen with the error’s localized description and a Retry button is presented.

Customize this behavior by implementing visitableDidFailRequest(_:error:retryHandler:). Call retryHandler() to attempt the network request again.

﹟ HotwireWebViewController

A HotwireWebViewController is a UIViewController that can be visited by a Navigator. Each view controller provides a VisitableView instance, which acts as a container for the shared WKWebView. The VisitableView optionally has a pull-to-refresh control and an activity indicator. It also automatically displays a screenshot of its contents when the web view moves to another VisitableView.

Most applications will probably need want to subclass HotwireWebViewController to customize its layout or add additional views. If your application’s design prevents you from subclassing HotwireWebViewController, you can implement the Visitable and BridgeDestination protocols yourself.

Note: Custom Visitable view controllers must notify their delegate of their viewWillAppear and viewDidAppear methods through the VisitableDelegate’s visitableViewWillAppear and visitableViewDidAppear methods. The Navigator uses these hooks to know when it should move the WKWebView from one VisitableView to another.