Presentation

Control how a page lands in your app. A modal page slides up over the current screen, and a root page replaces everything behind it.

#Modals Advanced Mode

In Advanced Mode, any URL ending in /new or /edit slides up as a modal. Any other page can too, declared in one of two places.

Mark a link to open its page as a modal:

<%= link_to "Add player", add_player_path, data: { native_presentation: "modal" } %>

Or add the tag to the page itself:

<%= native_presentation_tag :modal %>

Which one you need depends on how people get to the page:

Arrival Declare it with
Tapping a link The attribute on the link
Submitting a form, or a redirect after one The tag on the page
A deep link or a notification tap Not supported

The difference comes down to timing. The app decides where a tapped link lands before it loads the page, so the tag arrives too late. After a form submission, the page has already loaded by the time the app decides, so the tag is all you need.

A page reached both ways, like a details page you open from a list and also reach after creating a record, needs both.

#Multi-step flows

A flow often reaches its later screens by a form submit or a redirect, not a link. Add the tag to each of those views so they stay in the same modal:

<%# app/views/players/search.html.erb %>
<%= native_presentation_tag :modal %>

The declaration belongs to the page, not the form, so a controller can redirect wherever it needs to. A page with the tag stays in the modal, and a page without it closes the modal and lands on the screen behind it. Links between steps inside the modal need the attribute too.

#Finishing a flow

Any of these close the modal from its last step:

  • redirect_to a page without the tag, like the record you just created. The modal closes and the page lands behind it.
  • refresh_or_redirect_to closes the modal and reloads the page that opened it.
  • recede_or_redirect_to closes the modal and also goes back from the page that opened it, unless that page is the first one in its tab. That's how Hotwire Native defines recede on both platforms. To land back on the page that opened the modal, use refresh_or_redirect_to.

#Modals people can't close

Some modals have to stay put, like a paywall or a sign-in page. Add dismissible: false and the modal has no close button, no swipe down, and no back:

<%= native_presentation_tag :modal, dismissible: false %>

Only your server moves people on, by redirecting to a page without it.

Builds made before 0.21 ignore dismissible: false and show the page with a back button. Keep the server-side check that sends people back to the page, the same one that protects it on the web, until your users have updated.

#The close button

Android draws a close button on modals and iOS doesn't. Set modal_dismiss_button under appearance in config/ruby_native.yml to true or false to pick one behavior for both platforms. A single page can override it with dismiss_button: on the tag:

<%= native_presentation_tag :modal, dismiss_button: false %>

A modal that isn't dismissible never shows one.

Modals declared this way require Ruby Native 0.21.0 and a build made with it. On older builds, marked links and modal pages push like any other page.

#Root pages

Force a page to appear as the first and only screen on the navigation stack, with no back button:

<%= native_presentation_tag :root %>
import { NativePresentation } from "@ruby-native/react"

export default function Account() {
  return (
    <>
      <NativePresentation intent="root" />
      ...
    </>
  )
}
<script setup>
import { NativePresentation } from "@ruby-native/vue"
</script>

<template>
  <NativePresentation intent="root" />
  ...
</template>

The tag covers every way of reaching the page, so links need nothing. A page reached by a tapped link corrects itself once it renders.

Builds made before 0.21 read the first data-native-presentation they find in the page, and a link marked as a modal counts. If one of those links comes before the root tag in the HTML, those builds miss the tag and keep the back button. Until your users have updated, render the tag above any marked link, like at the top of <body>:

<%# app/views/layouts/application.html.erb %>
<body>
  <%= yield :native_presentation %>
  ...
</body>
<%# app/views/accounts/show.html.erb %>
<% content_for :native_presentation, native_presentation_tag(:root) %>

A form can't land as a root. When a form should send people to a fresh start, put the tag on the page the form redirects to, not on the form itself.

#Caching

Do not put the tag inside a cache block:

<%# Don't do this %>
<% cache @account do %>
  <%= native_presentation_tag :root %>
<% end %>

The tag uses a response header to signal to the native app. Caching this call would render the HTML element but not set the header. If you need the page cached, set the header from the controller instead:

class AccountsController < ApplicationController
  after_action -> { response.headers["Native-Presentation"] = "root" }, only: :show
end