@spec assign_errors(Plug.Conn.t(), data :: Ecto.Changeset.t() | map()) ::
  Plug.Conn.t()

Assigns errors to the Inertia page data. This helper accepts an Ecto.Changeset (and automatically serializes its errors into a shape compatible with Inertia), or a bare map of errors.

If you are serializing your own errors, they should take the following shape:

%{
  "name" => "Name is required",
  "password" => "Password must be at least 5 characters",
  "team.name" => "Team name is required",
}

When assigning a changeset, you may optionally pass a message-generating function to use when traversing errors. See Ecto.Changeset.traverse_errors/2 for more information about the message function.

defp default_msg_func({msg, opts}) do
  Enum.reduce(opts, msg, fn {key, value}, acc ->
    String.replace(acc, "%{#{key}}", fn _ -> to_string(value) end)
  end)
end

This default implementation performs a simple string replacement for error message containing variables, like count. For example, given the following error:

{"should be at least %{count} characters", [count: 3, validation: :length, min: 3]}

The generated description would be "should be at least 3 characters". If you would prefer to use the Gettext module for pluralizing and localizing error messages, you can override the message function:

conn
|> assign_errors(changeset, fn {msg, opts} ->
  if count = opts[:count] do
    Gettext.dngettext(MyAppWeb.Gettext, "errors", msg, msg, count, opts)
  else
    Gettext.dgettext(MyAppWeb.Gettext, "errors", msg, opts)
  end
end)

@spec assign_prop(Plug.Conn.t(), atom(), any()) :: Plug.Conn.t()

Assigns a prop value to the Inertia page data.

@spec camelize_props(Plug.Conn.t()) :: Plug.Conn.t()

Enable (or disable) automatic conversion of prop keys from snake case (e.g. inserted_at), which is conventional in Elixir, to camel case (e.g. insertedAt), which is conventional in JavaScript.

Examples

Using camelize_props here will convert first_name to firstName in the response props.

conn
|> assign_prop(:first_name, "Bob")
|> camelize_props()
|> render_inertia("Home")

You may also pass a boolean to the camelize_props function (to override any previously-set or globally-configured value):

conn
|> assign_prop(:first_name, "Bob")
|> camelize_props(false)
|> render_inertia("Home")

@spec clear_history(Plug.Conn.t()) :: Plug.Conn.t()

Instuct the client-side to clear the history.

@spec encrypt_history(Plug.Conn.t()) :: Plug.Conn.t()

Instuct the client-side to encrypt history for this page.

@spec inertia_always(value :: any()) :: always()

Marks a prop value as "always included", which means it will be included in the props on initial page load and subsequent partial loads (even when it's not explicitly requested).

@spec inertia_defer(fun :: (... -> any())) :: defer()

Marks that a prop should fetched immediately after the page is loaded on the client-side.

@spec inertia_merge(value :: any()) :: merge()

Marks that a prop should be merged with existing data on the client-side.

@spec inertia_optional(fun :: (... -> any())) :: optional()

Marks a prop value as optional, which means it will only get evaluated if explicitly requested in a partial reload.

Optional props will only be included the when explicitly requested in a partial reload. If you want to include the prop on first visit, you'll want to use a bare anonymous function or named function reference instead.

conn
# ALWAYS included on first visit...
# OPTIONALLY included on partial reloads...
# ALWAYS evaluated...
|> assign_prop(:cheap_thing, cheap_thing())

# ALWAYS included on first visit...
# OPTIONALLY included on partial reloads...
# ONLY evaluated when needed...
|> assign_prop(:expensive_thing, fn -> calculate_thing() end)
|> assign_prop(:another_expensive_thing, &calculate_another_thing/0)

# NEVER included on first visit...
# OPTIONALLY included on partial reloads...
# ONLY evaluated when needed...
|> assign_prop(:super_expensive_thing, inertia_optional(fn -> calculate_thing() end))

@spec render_inertia(Plug.Conn.t(), component :: String.t()) :: Plug.Conn.t()

Renders an Inertia response.

Options

• ssr: whether to server-side render the response (see the docs on "Server-side rendering" in the README for more information on setting this up). Defaults to the globally-configured value, or false if no global config is specified.

Examples

conn
|> assign_prop(:user_id, 1)
|> render_inertia("SettingsPage")

You may pass additional props as map for the third argument:

conn
|> assign_prop(:user_id, 1)
|> render_inertia("SettingsPage", %{name: "Bob"})

You may also pass options for the last positional argument:

conn
|> assign_prop(:user_id, 1)
|> render_inertia("SettingsPage", ssr: true)

conn
|> assign_prop(:user_id, 1)
|> render_inertia("SettingsPage", %{name: "Bob"}, ssr: true)