Merge pull request #42 from hotwired/android-reference

Update the reference and configuration documentation

_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:<latest-version>")
+    implementation("dev.hotwire:navigation-fragments:<latest-version>")
 }
 ```
 
@@ -49,7 +50,7 @@ Set up the app's layout by opening `activity_main.xml` and replace the entire fi
 
     <androidx.fragment.app.FragmentContainerView
         android:id="@+id/main_nav_host"
-        android:name="dev.hotwire.core.navigation.navigator.NavigatorHost"
+        android:name="dev.hotwire.navigation.navigator.NavigatorHost"
         android:layout_width="match_parent"
         android:layout_height="match_parent"
         app:defaultNavHost="false" />
@@ -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
         )
     )
 }

_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"
     )
 )
 ```

_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

_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 `<application>` node.
+p
+
+```xml
+<application android:name=".MyApplication">
+    <!-- ... -->
+</application>
+```
+
+## 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 `<application>` node.
-p
-
-```xml
-<application android:name=".MyApplication">
-    <!-- ... -->
-</application>
+Hotwire.config.userAgent = "My Application; ${Hotwire.config.userAgentSubstring()}"
 ```

_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.

_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),

_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()
+```