|
| 1 | +# Hotwire Native |
| 2 | + |
| 3 | +[TOC] |
| 4 | + |
| 5 | +## Introduction |
| 6 | + |
| 7 | +Hotwire also has a [mobile side](https://native.hotwired.dev/) and Turbo Laravel provides some helpers to help integrating with that. |
| 8 | + |
| 9 | +Turbo visits made by a Hotwire Native client should send a custom `User-Agent` header. Using that header, we can detect in the backend that a request is coming from a Hotwire Native client instead of a regular web browser. |
| 10 | + |
| 11 | +This is useful if you want to customize the behavior a little bit different based on that information. For instance, |
| 12 | +you may want to include some elements for mobile users, like a mobile-only CSS file include, for instance. To do that, you may use the `@hotwirenative` Blade directive in your Blade views: |
| 13 | + |
| 14 | +```blade |
| 15 | +@hotwirenative |
| 16 | + <link rel="stylesheet" href="mobile.css"> |
| 17 | +@endhotwirenative |
| 18 | +``` |
| 19 | + |
| 20 | +Alternatively, you may want to include some elements only if the client requesting it is _NOT_ a Hotwire Native client using the `@unlesshotwirenative` Blade helpers: |
| 21 | + |
| 22 | +```blade |
| 23 | +@unlesshotwirenative |
| 24 | + <h1>Hello, Non-Hotwire Native Users!</h1> |
| 25 | +@endunlesshotwirenative |
| 26 | +``` |
| 27 | + |
| 28 | +You may also check if the request was made from a Hotwire Native visit using the request macro: |
| 29 | + |
| 30 | +```php |
| 31 | +if (request()->wasFromHotwireNative()) { |
| 32 | + // ... |
| 33 | +} |
| 34 | +``` |
| 35 | + |
| 36 | +Or the Turbo Facade directly, like so: |
| 37 | + |
| 38 | +```php |
| 39 | +use HotwiredLaravel\TurboLaravel\Facades\Turbo; |
| 40 | + |
| 41 | +if (Turbo::isHotwireNativeVisit()) { |
| 42 | + // ... |
| 43 | +} |
| 44 | +``` |
| 45 | + |
| 46 | +## Interacting With Hotwire Native Navigation |
| 47 | + |
| 48 | +Hotwire Native will hook into Turbo's visits so it displays them on mobile mimicking the mobile way of stacking screens instead of just replace elements on the same screen. This helps the native feel of our hybrid app. |
| 49 | + |
| 50 | +However, sometimes we may need to customize the behavior of form request handler to avoid a weird screen jumping effect happening on the mobile client. Instead of regular redirects, we can send some signals by redirecting to specific routes that are detected by the Hotwire Native client. |
| 51 | + |
| 52 | +For instance, if a form submission request came from a Hotwire Native client, the form was probably rendered on a native modal, which is not part of the screen stack, so we can just tell Turbo to `refresh` the current screen it has on stack instead. There are 3 signals we can send to the Hotwire Native client: |
| 53 | + |
| 54 | +| Signal | Route| Description| |
| 55 | +|---|---|---| |
| 56 | +| `recede` | `/recede_historical_location` | Go back to previous screen | |
| 57 | +| `resume` | `/resume_historical_location` | Stay on the current screen as is | |
| 58 | +| `refresh`| `/refresh_historical_location` | Stay on the current screen but refresh | |
| 59 | + |
| 60 | +Sending these signals is a matter of detecting if the request came from a Hotwire Native client and, if so, redirect the user to these signal URLs instead. The Hotwire Native client should detect the redirect was from one of these special routes and trigger the desired behavior. |
| 61 | + |
| 62 | +You may use the `InteractsWithHotwireNativeNavigation` trait on your controllers to achieve this behavior and fallback to a regular redirect if the request wasn't from a Hotwire Native client: |
| 63 | + |
| 64 | +```php |
| 65 | +use HotwiredLaravel\TurboLaravel\Http\Controllers\Concerns\InteractsWithHotwireNativeNavigation; |
| 66 | + |
| 67 | +class TraysController extends Controller |
| 68 | +{ |
| 69 | + use InteractsWithHotwireNativeNavigation; |
| 70 | + |
| 71 | + public function store() |
| 72 | + { |
| 73 | + // Tray creation... |
| 74 | + |
| 75 | + return $this->recedeOrRedirectTo(route('trays.show', $tray)); |
| 76 | + } |
| 77 | +} |
| 78 | +``` |
| 79 | + |
| 80 | +In this example, when the request to create trays comes from a Hotwire Native client, we're going to redirect to the `/recede_historical_location` URL instead of the `trays.show` route. However, if the request was made from your web app, we're going to redirect the client to the `trays.show` route. |
| 81 | + |
| 82 | +There are a couple of redirect helpers available: |
| 83 | + |
| 84 | +```php |
| 85 | +$this->recedeOrRedirectTo(string $url); |
| 86 | +$this->resumeOrRedirectTo(string $url); |
| 87 | +$this->refreshOrRedirectTo(string $url); |
| 88 | +$this->recedeOrRedirectBack(string $fallbackUrl, array $options = []); |
| 89 | +$this->resumeOrRedirectBack(string $fallbackUrl, array $options = []); |
| 90 | +$this->refreshOrRedirectBack(string $fallbackUrl, array $options = []); |
| 91 | +``` |
| 92 | + |
| 93 | +It's common to flash messages using the `->with()` method of the Redirect response in Laravel. However, since a Hotwire Native request will never actually redirect somewhere where the flash message will be rendered, the behavior of the `->with()` method was slightly modified too. |
| 94 | + |
| 95 | +If you're setting flash messages like this after a form submission: |
| 96 | + |
| 97 | +```php |
| 98 | +use HotwiredLaravel\TurboLaravel\Http\Controllers\Concerns\InteractsWithHotwireNativeNavigation; |
| 99 | + |
| 100 | +class TraysController extends Controller |
| 101 | +{ |
| 102 | + use InteractsWithHotwireNativeNavigation; |
| 103 | + |
| 104 | + public function store() |
| 105 | + { |
| 106 | + // Tray creation... |
| 107 | + |
| 108 | + return $this->recedeOrRedirectTo(route('trays.show', $tray)) |
| 109 | + ->with('status', __('Tray created.')); |
| 110 | + } |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +If a request was sent from a Hotwire Native client, the flashed messages will be added to the query string instead of flashed into the session like they'd normally be. In this example, it would redirect like this: |
| 115 | + |
| 116 | +``` |
| 117 | +/recede_historical_location?status=Tray%20created. |
| 118 | +``` |
| 119 | + |
| 120 | +In the Hotwire Native client, you should be able to intercept these redirects, retrieve the flash messages from the query string and create native toasts, if you'd like to. |
| 121 | + |
| 122 | +If the request wasn't from a Hotwire Native client, the message would be flashed into the session as normal, and the client would receive a redirect to the `trays.show` route in this case. |
| 123 | + |
| 124 | +If you don't want these routes enabled, feel free to disable them by commenting out the feature on your `config/turbo-laravel.php` file (make sure the Turbo Laravel configs are published): |
| 125 | + |
| 126 | +```php |
| 127 | +return [ |
| 128 | + 'features' => [ |
| 129 | + // Features::hotwireNativeRoutes(), |
| 130 | + ], |
| 131 | +]; |
| 132 | +``` |
| 133 | + |
| 134 | +[Continue to Testing...](/docs/{{version}}/testing) |
0 commit comments