From 67c37ffd3b095593349404574e6d18fb249d7f16 Mon Sep 17 00:00:00 2001 From: Jay Ohms Date: Wed, 25 Sep 2024 09:36:07 -0400 Subject: [PATCH] Update the reference and configuration documentation --- _source/android/01_getting_started.md | 13 ++--- _source/android/02_path_configuration.md | 2 +- _source/android/04_native_screens.md | 4 +- _source/android/05_configuration.md | 60 ++++++++++++------------ _source/android/06_reference.md | 32 ++++++++++++- _source/ios/02_path_configuration.md | 2 +- _source/reference/navigation.md | 15 ++++++ 7 files changed, 85 insertions(+), 43 deletions(-) diff --git a/_source/android/01_getting_started.md b/_source/android/01_getting_started.md index 077ade3..7829c37 100644 --- a/_source/android/01_getting_started.md +++ b/_source/android/01_getting_started.md @@ -23,11 +23,12 @@ Then select API 28 or higher for the minimum SDK and Kotlin DSL for the build co ## Integrate Hotwire Native -Add the Hotwire Native dependency to your app's module (not top-level) `build.gradle.kts` file: +Add the Hotwire Native dependencies to your app's module (not top-level) `build.gradle.kts` file: ```kotlin dependencies { implementation("dev.hotwire:core:") + implementation("dev.hotwire:navigation-fragments:") } ``` @@ -49,7 +50,7 @@ Set up the app's layout by opening `activity_main.xml` and replace the entire fi @@ -60,12 +61,6 @@ Set up the app's layout by opening `activity_main.xml` and replace the entire fi Finally, open `MainActivity.kt` and replace the entire file with this code: ```kotlin -package com.example.myapplication - -import android.os.Bundle -import dev.hotwire.core.navigation.activities.HotwireActivity -import dev.hotwire.core.navigation.navigator.NavigatorConfiguration - class MainActivity : HotwireActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) @@ -76,7 +71,7 @@ class MainActivity : HotwireActivity() { NavigatorConfiguration( name = "main", startLocation = "https://hotwire-native-demo.dev", - navigatorHostId = R.id.main_nav_host + navigatorHostId = R.id.main_navigator_host ) ) } diff --git a/_source/android/02_path_configuration.md b/_source/android/02_path_configuration.md index 45f57fc..096de21 100644 --- a/_source/android/02_path_configuration.md +++ b/_source/android/02_path_configuration.md @@ -51,7 +51,7 @@ Hotwire.loadPathConfiguration( context = this, location = PathConfiguration.Location( assetFilePath = "json/configuration.json", - remoteFileUrl = "https://example.com/your-path-config.json" + remoteFileUrl = "https://example.com/configurations/android_v1.json" ) ) ``` diff --git a/_source/android/04_native_screens.md b/_source/android/04_native_screens.md index 6b56c43..d21bee2 100644 --- a/_source/android/04_native_screens.md +++ b/_source/android/04_native_screens.md @@ -42,9 +42,9 @@ class NumbersFragment : HotwireFragment() { Finally, register this fragment with Hotwire Native to use it when the URL path matches. See the [configuration](/android/configuration) docs for a recommendation on where to register fragments in your code. ```kotlin -Hotwire.registerFragmentDestinations(listOf( +Hotwire.registerFragmentDestinations( NumbersFragment::class -)) +) ``` ## Progressive Rollout diff --git a/_source/android/05_configuration.md b/_source/android/05_configuration.md index d3624c3..8cb1cc4 100644 --- a/_source/android/05_configuration.md +++ b/_source/android/05_configuration.md @@ -7,6 +7,32 @@ description: "How to customize a Hotwire Native Android app." # Configuration +## Create an Application Instance + +Customize your app by configuring options before your `HotwireActivity` instance is created by the system. We recommend using an `Application` instance to place the configuration code. + + +```kotlin +class MyApplication : Application() { + override fun onCreate() { + super.onCreate() + + // Set configuration options + } +} +``` + +To ensure this invoked when the app starts, add the name of your `Application` instance to `AndroidManifest.xml` via the `android:name` property on the `` node. +p + +```xml + + + +``` + +## Options + Enable debugging in debug builds: ```kotlin @@ -23,17 +49,17 @@ Hotwire.defaultFragmentDestination = WebFragment::class Register fragment destinations: ```kotlin -Hotwire.registerFragmentDestinations(listOf( +Hotwire.registerFragmentDestinations( MyCustomFragment::class -)) +) ``` Register bridge components, where the first argument is the component name to match in Stimulus: ```kotlin -Hotwire.registerBridgeComponents(listOf( +Hotwire.registerBridgeComponents( BridgeComponentFactory("my-custom", ::MyCustomComponent) -)) +) ``` Set the JSON converter used for bridge components: @@ -45,29 +71,5 @@ Hotwire.config.jsonConverter = KotlinXJsonConverter() Customize the user agent: ```kotlin -Hotwire.config.userAgent = "Hotwire Demo; ${Hotwire.config.userAgentSubstring()}" -``` - -## Create an Application Instance - -Customize your app by configuring options before your `HotwireActivity` instance is created by the system. We recommend using an `Application` instance to place the configuration code. - - -```kotlin -class MyApplication : Application() { - override fun onCreate() { - super.onCreate() - - // Set configuration options - } -} -``` - -To ensure this invoked when the app starts, add the name of your `Application` instance to `AndroidManifest.xml` via the `android:name` property on the `` node. -p - -```xml - - - +Hotwire.config.userAgent = "My Application; ${Hotwire.config.userAgentSubstring()}" ``` diff --git a/_source/android/06_reference.md b/_source/android/06_reference.md index c66b43b..31efe36 100644 --- a/_source/android/06_reference.md +++ b/_source/android/06_reference.md @@ -7,4 +7,34 @@ description: "An reference guide to the Hotwire Native Android library." # Reference -> Coming soon... +## Navigator + +The `Navigator` is the central coordinator in a Hotwire Native Android application. Each `NavigatorHost` in your Activity maintains a `Navigator` instance, which manages the stack of `HotwireFragment` screens with a single, shared `WebView` instance. It lets your app choose how to handle link taps, present new screens, and deal with errors. + +## Custom WebView + +You can customize and subclass the `HotwireWebView` class to provide custom behaviors in your app: + +```kotlin +Hotwire.config.makeCustomWebView = { context + MyCustomWebView(context, null) +} +``` + +## Handling URL routes + +By default, all external urls outside of your app's domain are opened in the default browser on the device. This is easily customizable, though. Out-of-the-box, Hotwire Native provides three route decision handlers for you to use to control how urls are routed: +- `AppNavigationRouteDecisionHandler`: Routes all internal urls through your app (enabled by default). +- `BrowserRouteDecisionHandler`: Routes all external urls to the device's default browser (enabled by default). +- `BrowserTabRouteDecisionHandler`: Routes all external urls to a [Custom Tab](https://developer.chrome.com/docs/android/custom-tabs) in your app (disabled by default). + +If you'd like to customize this behavior, it's easy to do. For example, if you'd like to route external urls to Custom Tabs instead of the default browser, you can register the relevant decision handlers in order of importance: + +```kotlin +Hotwire.registerRouteDecisionHandlers( + AppNavigationRouteDecisionHandler(), + BrowserTabRouteDecisionHandler() +) +``` + +You can also implement your own `Router.RouteDecisionHandler` classes and register them the same way. diff --git a/_source/ios/02_path_configuration.md b/_source/ios/02_path_configuration.md index 2313ecc..5f43d75 100644 --- a/_source/ios/02_path_configuration.md +++ b/_source/ios/02_path_configuration.md @@ -46,7 +46,7 @@ Path configuration has an array of `sources`. You can configure the source to be ```swift let localPathConfigURL = Bundle.main.url(forResource: "path-configuration", withExtension: "json")! -let remotePathConfigURL = URL(string: "https://example.com/your-path-config.json")! +let remotePathConfigURL = URL(string: "https://example.com/configurations/ios_v1.json")! let pathConfiguration = PathConfiguration(sources: [ .file(localPathConfigURL), diff --git a/_source/reference/navigation.md b/_source/reference/navigation.md index c35b044..93777ea 100644 --- a/_source/reference/navigation.md +++ b/_source/reference/navigation.md @@ -216,3 +216,18 @@ navigator?.pop() // Clear the navigation backstack to the start destination. navigator?.clearAll() ``` + +Inside of a `HotwireFragment` class: + +```kotlin +val location = "https://..." + +// Visit a new page. +navigator.route("$location/foo") + +// Pop the backstack to the previous destination. +navigator.pop() + +// Clear the navigation backstack to the start destination. +navigator.clearAll() +```