From e8e2b7d448fe8feb477543f9f55100a49dbd6edb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zo=C3=AB=20Smith?= Date: Thu, 26 Sep 2024 08:57:21 +0100 Subject: [PATCH 1/2] Copy changes --- _source/ios/01_getting_started.md | 2 +- _source/ios/02_path_configuration.md | 14 +++++--------- _source/ios/04_native_screens.md | 10 +++++----- _source/ios/05_configuration.md | 2 +- _source/overview/02_basic_navigation.md | 4 ++-- _source/overview/03_path_configuration.md | 2 +- _source/overview/05_native_screens.md | 2 +- 7 files changed, 16 insertions(+), 20 deletions(-) diff --git a/_source/ios/01_getting_started.md b/_source/ios/01_getting_started.md index af3d131..5668e31 100644 --- a/_source/ios/01_getting_started.md +++ b/_source/ios/01_getting_started.md @@ -28,7 +28,7 @@ Select where to save the project and click Create. ## Integrate Hotwire Native Next, add the Hotwire Native package via File → Add Packages Dependencies... and enter `https://github.com/hotwired/hotwire-native-ios` in the search field. -Make sure the “Dependency Rule“ is set to “Branch“ pointing to main and your project is correctly set under “Add to Project“ and click Add Package. +Make sure your project is correctly set under “Add to Project“ and click Add Package. Configure Xcode project diff --git a/_source/ios/02_path_configuration.md b/_source/ios/02_path_configuration.md index 5f43d75..4fc7aff 100644 --- a/_source/ios/02_path_configuration.md +++ b/_source/ios/02_path_configuration.md @@ -55,14 +55,10 @@ let pathConfiguration = PathConfiguration(sources: [ let navigator = Navigator(pathConfiguration: pathConfiguration) ``` - -`PathConfiguration` will always load locally available configurations first. When providing both a bundled file and a server location, load order is as follows: - -1. The bundled file -2. The cached server file (if a successful download has previously occurred) -3. The downloaded server file - -Providing a bundled file and a server location will cause the path configuration to immediately load from the bundled version and – if it exists – a cached version of the server file. Then it will begin downloading the server file. Once the server file is successfully downloaded, it is loaded and cached for further use. +If you provide both a file and a server location, the path configuration will be loaded asynchronously in the following order: +1. The local file bundled with your app. +2. A locally cached copy of the server configuration (if a successful download occurred on a previous app launch). +3. A newly downloaded copy of the server configuration. (Once this has downloaded successfully, it will be cached and used in step 2 on the next app launch.) ## Query String Matching @@ -85,4 +81,4 @@ Disable query string matching via: Hotwire.config.pathConfiguration.matchQueryStrings = false ``` -The [path configuration reference](/reference/path-configuration) provides more information including all the behavior Hotwire Native provides out of the box. +The [path configuration reference](/reference/path-configuration) provides more information, including all the behavior Hotwire Native provides out of the box. diff --git a/_source/ios/04_native_screens.md b/_source/ios/04_native_screens.md index 809cb20..7ffa1ca 100644 --- a/_source/ios/04_native_screens.md +++ b/_source/ios/04_native_screens.md @@ -7,9 +7,9 @@ description: "Integrate fully native Swift screens in your Hotiwre Native app." # Native Screens -If you need to go fully native, we've got you covered: it's easy to integrate native screens to Hotwire Native's navigation flow. Even though you may be tempted to get a reference to Hotwire Native's navigation controller and push/present yourself, we strongly advice against it. It's better to leverage the power of Hotwire Native's [Path Configuration](/ios/path-configuration), even for native screens. +If you need to go fully native, we've got you covered: it's easy to integrate native screens to Hotwire Native's navigation flow. Even though you may be tempted to get a reference to Hotwire Native's navigation controller and push/present yourself, we strongly advise against it. It's better to leverage the power of Hotwire Native's [Path Configuration](/ios/path-configuration), even for native screens. -First, conform your controller to `PathConfigurationIdentifiable` and provide a matching `pathConfigurationIdentifier`. This identifier is used so you can easily identify that a native view controller was requested after a link interception. +First, conform your view controller to `PathConfigurationIdentifiable` and provide a matching `pathConfigurationIdentifier`. When Hotwire Native intercepts a link, the identifier is used to quickly work out that a native view controller was requested. ```swift class NumbersViewController: UITableViewController, PathConfigurationIdentifiable { @@ -23,7 +23,7 @@ class NumbersViewController: UITableViewController, PathConfigurationIdentifiabl } ``` -Next, match a URL path pattern and set the `view_controller` property. This path configuration routes all URLs ending in `/numbers`. +Next, create a URL path pattern to match against, and set its `view_controller` property. This path configuration routes all URLs ending in `/numbers`: ```json { @@ -43,7 +43,7 @@ Next, match a URL path pattern and set the `view_controller` property. This path When a link is intercepted by Hotwire Native, it will go through its usual process of matching the link's URL path to all rules in the app's Path Configuration. When it matches the above rule, it will create a `VisitProposal` and will set this `view_controller` property to `"numbers"`. -You can inspect this property when `handle(proposal:)` is called on `Navigator`'s delegate and create your own view controller there. That's it! Hotwire Native will handle presentation (push/replace and animations) as if it were a web view controller. +You can inspect this property when `handle(proposal:)` is called on `Navigator`'s delegate and instantiate your own view controller there. That's it! Hotwire Native will handle presentation (push/replace and animations) as if it were a web view controller. ```swift class SceneDelegate: UIResponder { @@ -69,7 +69,7 @@ extension SceneDelegate: NavigatorDelegate { In a purely native app, if a new screen presented an issue you'd be unable to react immediately. The usual process would be to rush out bug fixes and hope for a quick review. If the bug was severe or your team needed more time to fix a critical issue, you'd have to rollback to a previous app version and submit that to the App Store, probably with an expedited review. -Since even native screens are routed through Hotwire Native, the Path Configuration is a powerful ally when it comes to rolling out your native screens. If you were to find a critical issue with your native screen, you could easily update your remote Path Configuration and either point to your web-content so users don't lose functionality, or immediately disable the screen altogether – no app review required for these measures. +Since even native screens are routed through Hotwire Native, the Path Configuration is a powerful ally when it comes to rolling out your native screens. If you were to find a critical issue with your native screen, you could easily update your remote Path Configuration and either point to your web content so users don't lose functionality, or immediately disable the screen altogether – no app store review required. Simply remove the `"view_controller"` property and Hotwire Native will stop using your native screen, instead presenting a web view controller which loads `"/numbers"`: a web page you fully control. diff --git a/_source/ios/05_configuration.md b/_source/ios/05_configuration.md index a4a8657..9084457 100644 --- a/_source/ios/05_configuration.md +++ b/_source/ios/05_configuration.md @@ -18,7 +18,7 @@ Hotwire.config.debugLoggingEnabled = true ## General * `debugLoggingEnabled` - Enable or disable debug logging for Turbo visits and bridge elements connecting, disconnecting, receiving/sending messages, and more. -* `userAgent` - Override to set a custom user agent for your app's requests. Make sure to include "Hotwire Native" or "Turbo Native" to use `turbo_native_app?` on your Rails server. +* `userAgent` - Override to set a custom user agent for your app's requests. Make sure to include "Hotwire Native" or "Turbo Native" to use `turbo_native_app?` on your [Rails server](https://github.com/hotwired/turbo-rails/blob/1aa7ba9d38dee1e1b4078a74404131122b907176/app/controllers/turbo/native/navigation.rb#L14). * `showDoneButtonOnModals` - When enabled, adds a `UIBarButtonItem` of type `.done` to the left navigation bar button item on screens presented modally. * `backButtonDisplayMode` - Sets the back button display mode of `HotwireWebViewController`. diff --git a/_source/overview/02_basic_navigation.md b/_source/overview/02_basic_navigation.md index 5a66c23..c35c702 100644 --- a/_source/overview/02_basic_navigation.md +++ b/_source/overview/02_basic_navigation.md @@ -24,11 +24,11 @@ When a user taps on a link, here's what's happening: By default, every tapped link _pushes_ a new screen onto the native stack. Hotwire Native uses platform-specific animations and native components so interactions feel smooth. To users, it feels like a native app because it _is_ a native app! -The framework also applies a few sane defaults. Navigating to the _current_ page's URL path (again) will _replace_ the screen on the stack. You can also manually trigger a _replace_ action by adding `data-turbo-action="replace"` to links and forms. This will cause the visited page to replace the current screen (not push a new one) and load the new contents. +The framework also applies a few sane defaults. Navigating to the _current_ page's URL path (again) will _replace_ the screen on the stack. You can also manually trigger a _replace_ action by adding `data-turbo-action="replace"` to links and forms. This will cause the visited page to replace the current screen (rather than pushing a new one) and load the new contents. ## Caching - Navigating to the _previous_ page's URL path will _pop_ the screen off the stack back to the previous screen. This animation uses a cached screenshot further blending the gap to native screens. On iOS, the interactive pop gesture - dragging your finger from the far left of the screen - is also supported and feels great. + Navigating to the _previous_ page's URL path will _pop_ the screen off the stack back to the previous screen. This animation uses a cached screenshot, further blending the gap to native screens. On iOS, the interactive pop gesture – dragging your finger from the far left of the screen – is also supported and feels great. ## External Links diff --git a/_source/overview/03_path_configuration.md b/_source/overview/03_path_configuration.md index 2041ea1..5806466 100644 --- a/_source/overview/03_path_configuration.md +++ b/_source/overview/03_path_configuration.md @@ -18,7 +18,7 @@ Advanced navigation in Hotwire Native apps can be configured via a JSON file cal `settings` contains app-level configuration items. These settings can be read when the *path configuration* is first loaded; common use cases include feature-flags or custom app information that you want to control remotely. -`rules` contains entries that define navigation within the Hotwire app. Each entry contains regex patterns used to identify URLs and then apply the specified behavior on navigation. In the following example, all URLs that match regex `/new$` will open up in a modal screen instead of being pushed onto the default navigation stack. +`rules` contains entries that define navigation within the Hotwire app. Each entry contains regex patterns used to identify URLs and then apply the specified behavior on navigation. In the following example, all URLs matching the regex `/new$` will open up in a modal screen, rather than being pushed onto the default navigation stack: ```json { diff --git a/_source/overview/05_native_screens.md b/_source/overview/05_native_screens.md index 1b0939f..cea1b29 100644 --- a/_source/overview/05_native_screens.md +++ b/_source/overview/05_native_screens.md @@ -13,7 +13,7 @@ There are a few things to note: - It's strongly encouraged that each native screen has a corresponding URL, so it's easier to integrate into Hotwire Native's built-in navigation. - Purely native screens will likely take specialized experience from iOS and Android developers. -- You'll need to write a version for every platform and go through the app store review process for any future changes +- You'll need to write a version for every platform and go through the app store review process for any future changes. Leveraging Hotwire Native allows you to build full products with smaller development teams. You can focus on high fidelity native development where it matters most and leverage your existing web app for everything else. From 2d3513d283a7ae7daad1a4a6451733f563950e3a Mon Sep 17 00:00:00 2001 From: Jay Ohms Date: Thu, 26 Sep 2024 15:04:10 -0400 Subject: [PATCH 2/2] Bring Android parity to the copy changes --- _source/android/02_path_configuration.md | 11 +++++------ _source/android/04_native_screens.md | 6 +++--- _source/ios/02_path_configuration.md | 1 + _source/ios/04_native_screens.md | 2 +- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/_source/android/02_path_configuration.md b/_source/android/02_path_configuration.md index 096de21..c2df223 100644 --- a/_source/android/02_path_configuration.md +++ b/_source/android/02_path_configuration.md @@ -56,12 +56,11 @@ Hotwire.loadPathConfiguration( ) ``` -`Path Configuration` will always load locally available configurations first. When providing both a bundled file and a server location, load order is as follows: - -1. The bundled file -2. The cached server file (if a successful download has previously occurred) -3. The downloaded server file +If you provide both a file and a server location, the path configuration will be loaded asynchronously in the following order: +1. The local file bundled with your app. +2. A locally cached copy of the server configuration (if a successful download occurred on a previous app launch). +3. A newly downloaded copy of the server configuration. (Once this has downloaded successfully, it will be cached and used in step 2 on the next app launch.) Providing a bundled file and a server location will cause the path configuration to immediately load from the bundled version and – if it exists – a cached version of the server file. Then it will begin downloading the server file. Once the server file is successfully downloaded, it is loaded and cached for further use. -The [path configuration reference](/reference/path-configuration) provides more information including all the behavior Hotwire Native provides out of the box. +The [path configuration reference](/reference/path-configuration) provides more information, including all the behavior Hotwire Native provides out of the box. diff --git a/_source/android/04_native_screens.md b/_source/android/04_native_screens.md index d21bee2..1262613 100644 --- a/_source/android/04_native_screens.md +++ b/_source/android/04_native_screens.md @@ -9,7 +9,7 @@ description: "Integrate fully native Kotlin screens in your Hotiwre Native app." To render a native screen on Android you need match an identifier in the [path configuration](/overview/path-configuration) with your fragment. -First, match a URL path pattern and set the `uri` property. This path configuration routes all URLs ending in `/numbers`. You can also set a `title` to set the native title when the fragment is presented. +First, create a URL path pattern and set its `uri` property. This path configuration routes all URLs ending in `/numbers`. You can also set a `title` to set the native title when the fragment is presented. ```json { @@ -28,7 +28,7 @@ First, match a URL path pattern and set the `uri` property. This path configurat } ``` -When a link is intercepted by Hotwire Native, it will go through its usual process of matching the link's URL path to all rules in the app's Path Configuration. When it matches the above rule, it will propose a `visit` and will find the matching `HotwireDestination` whose `uri` matches `"hotwire://fragment/numbers"`. +When a link is intercepted by Hotwire Native, it will go through its usual process of matching the link's URL path to all rules in the app's Path Configuration. When it matches the above rule, it will propose a `visit` and resolve the matching `HotwireDestination` whose `uri` matches `"hotwire://fragment/numbers"`. Create a new fragment and provide a matching `HotwireDestination` annotation. @@ -51,7 +51,7 @@ Hotwire.registerFragmentDestinations( In a purely native app, if a new screen presented an issue you'd be unable to react immediately. The usual process would be to rush out bug fixes and hope for a quick review. If the bug was severe or your team needed more time to fix a critical issue, you'd have to rollback to a previous app version and submit that to the Play Store for review. -Since even native screens are routed through Hotwire Native, the Path Configuration is a powerful ally when it comes to rolling out your native screens. If you were to find a critical issue with your native screen, you could easily update your remote Path Configuration and either point to your web-content so users don't lose functionality, or immediately disable the screen altogether – no app review required for these measures. +Since even native screens are routed through Hotwire Native, the Path Configuration is a powerful ally when it comes to rolling out your native screens. If you were to find a critical issue with your native screen, you could easily update your remote Path Configuration and either point to your web content so users don't lose functionality, or immediately disable the screen altogether – no app store review required. Simply remove the `"uri"` property and Hotwire Native will stop using your native screen, instead presenting a web view controller which loads `"/numbers"`: a web page you fully control. diff --git a/_source/ios/02_path_configuration.md b/_source/ios/02_path_configuration.md index 4fc7aff..8a4a3c6 100644 --- a/_source/ios/02_path_configuration.md +++ b/_source/ios/02_path_configuration.md @@ -55,6 +55,7 @@ let pathConfiguration = PathConfiguration(sources: [ let navigator = Navigator(pathConfiguration: pathConfiguration) ``` + If you provide both a file and a server location, the path configuration will be loaded asynchronously in the following order: 1. The local file bundled with your app. 2. A locally cached copy of the server configuration (if a successful download occurred on a previous app launch). diff --git a/_source/ios/04_native_screens.md b/_source/ios/04_native_screens.md index 7ffa1ca..d64fb6a 100644 --- a/_source/ios/04_native_screens.md +++ b/_source/ios/04_native_screens.md @@ -9,7 +9,7 @@ description: "Integrate fully native Swift screens in your Hotiwre Native app." If you need to go fully native, we've got you covered: it's easy to integrate native screens to Hotwire Native's navigation flow. Even though you may be tempted to get a reference to Hotwire Native's navigation controller and push/present yourself, we strongly advise against it. It's better to leverage the power of Hotwire Native's [Path Configuration](/ios/path-configuration), even for native screens. -First, conform your view controller to `PathConfigurationIdentifiable` and provide a matching `pathConfigurationIdentifier`. When Hotwire Native intercepts a link, the identifier is used to quickly work out that a native view controller was requested. +First, conform your view controller to `PathConfigurationIdentifiable` and provide a matching `pathConfigurationIdentifier`. When Hotwire Native intercepts a link, the identifier is used to resolve that a native view controller was requested. ```swift class NumbersViewController: UITableViewController, PathConfigurationIdentifiable {