Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/joemasilotti/TurboNavigator
A drop-in class for Turbo Native apps to handle common navigation flows.
https://github.com/joemasilotti/TurboNavigator
hotwire ios turbo-native
Last synced: about 2 months ago
JSON representation
A drop-in class for Turbo Native apps to handle common navigation flows.
- Host: GitHub
- URL: https://github.com/joemasilotti/TurboNavigator
- Owner: joemasilotti
- License: mit
- Created: 2023-03-02T18:45:06.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-12-11T17:24:38.000Z (10 months ago)
- Last Synced: 2024-07-04T09:30:21.174Z (3 months ago)
- Topics: hotwire, ios, turbo-native
- Language: Swift
- Homepage:
- Size: 1010 KB
- Stars: 200
- Watchers: 13
- Forks: 12
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Turbo Navigator
A drop-in class for [Turbo Native](https://github.com/hotwired/turbo-ios) apps to handle common navigation flows.
> [!IMPORTANT]
> This package is currently being upstreamed into turbo-ios! All future development is happening on the [turbo-navigator branch](https://github.com/hotwired/turbo-ios/pull/158).
## 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](https://masilotti.com/services/) 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](https://github.com/hotwired/turbo-ios/blob/main/Docs/PathConfiguration.md), 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.
```json
{
"patterns": [
"/new$",
"/edit$"
],
"properties": {
"context": "modal"
}
}
```
To hook into the "refresh" [turbo-rails native route](https://github.com/hotwired/turbo-rails/blob/main/app/controllers/turbo/native/navigation.rb), 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.
```json
{
"patterns": [
"/refresh_historical_location"
],
"properties": {
"presentation": "refresh"
}
}
```
## Getting started
First, create a new Xcode project using the iOS App template.
Then add the Turbo Navigator Swift package.
1. In Xcode, File → Add Packages…
1. Enter the following URL in the upper right: `https://github.com/joemasilotti/TurboNavigator`
1. Click Add Package
1. Click Add Package again
Replace `SceneDelegate.swift` with the following.
```swift
import TurboNavigator
import UIKit
let rootURL = URL(string: "http://localhost:3000")!
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
var window: UIWindow?
private let navigationController = UINavigationController()
private lazy var navigator = TurboNavigator(delegate: self, navigationController: navigationController)
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
window?.rootViewController = navigationController
navigator.route(rootURL)
}
}
extension SceneDelegate: TurboNavigationDelegate {}
```
Start the [demo Rails server](Demo/Server) then run the iOS app in Xcode via Product → Run.
## 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. You may inspect the provided proposal and decide routing based on any of its properties. For custom native screens, you may also include a `"view-controller"` property that will be passed along.
```json
{
"patterns": [
"/numbers$"
],
"properties": {
"view-controller": "numbers"
}
}
```
```swift
class MyCustomClass: TurboNavigationDelegate {
let navigator = TurboNavigator(delegate: self)
func handle(proposal: VisitProposal) -> ProposalResult {
if proposal.viewController == "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
}
}
}
```
If you're relying on the `"view-controller"` property, we recommend your view controllers conform to `PathConfigurationIdentifiable`. You should also avoid using the class name as identifier, as you might rename your controller in the future.
```swift
class NumbersViewController: UIViewController, PathConfigurationIdentifiable {
static var pathConfigurationIdentifier: String { "numbers" }
}
class MyCustomClass: TurboNavigationDelegate {
let navigator = TurboNavigator(delegate: self)
func handle(proposal: VisitProposal) -> ProposalResult {
if proposal.viewController == NumbersViewController.pathConfigurationIdentifier {
// Let Turbo Navigator route this custom controller.
return .acceptCustom(NumbersViewController())
} else ...
...
}
}
}
```
## Custom configuration
Customize the configuration via `TurboConfig`.
### Override the user agent
Keep "Turbo Native" to use `turbo_native_app?` on your Rails server.
```swift
TurboConfig.shared.userAgent = "Custom (Turbo Native)"
```
### Customize the web view and web view configuration
A closure is used because a new instance is needed for each web view. The closure has a `WKWebViewConfiguration` argument that's pre-built and ready to be customized and assigned to a new web view.
```swift
TurboConfig.shared.makeCustomWebView = { (configuration: WKWebViewConfiguration) in
// Customize the WKWebViewConfiguration instance
// ...
return WKWebView(frame: .zero, configuration: configuration)
}
```
### Customize behavior for external URLs
Turbo cannot navigate across domains because page visits are done via JavaScript. A tapped link that points to a different domain is considered external.
By default, web URLs (`http://` and `https://`) are presented via the in-app browser, `SFSafariViewController`. Everything else is opened natively. For example, `tel:` and `sms:` links are opened, when possible, in Phone.app or Messages.app.
If you want to register _additional_ URL schemes you need to follow the [steps outlined here](https://developer.apple.com/documentation/uikit/uiapplication/1622952-canopenurl#discussion) to add an entry in your Info.plist.
This behavior can be overridden by implementing the following delegate method.
```swift
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.
}
}
```
### Customized error handling
By default, Turbo Navigator will automatically handle any errors that occur when performing visits. The error's localized description and a button to retry the request is displayed.
You can customize the error handling by overriding the following delegate method.
```swift
extension MyCustomClass: TurboNavigationDelegate {
func visitableDidFailRequest(_ visitable: Visitable, error: Error, retry: @escaping RetryBlock) {
if case let TurboError.http(statusCode) = error, statusCode == 401 {
// Custom error handling for 401 responses.
} else if let errorPresenter = visitable as? ErrorPresenter {
errorPresenter.presentError(error) {
retry()
}
}
}
}
```