Phoenix.LiveView.Helpers (Phoenix LiveView v0.15.7) View Source

A collection of helpers to be imported into your views.

Link to this section Summary

Functions

Renders a component defined by the given function.

Builds a file input tag for a LiveView upload.

Returns the flash message from the LiveView flash assign.

Generates an image preview on the client for a selected file.

Generates a link that will patch the current LiveView.

Generates a link that will redirect to a new LiveView.

Renders a LiveView within an originating plug request or within a parent LiveView.

Renders a title tag with automatic prefix/suffix on @page_title updates.

Renders the @inner_block assign of a component with the given argument.

Provides ~L sigil with HTML safe Live EEx syntax inside source files.

Returns the entry errors for an upload.

Returns the entry errors for an upload.

Link to this section Functions

Link to this macro

component(func, assigns \\ [], do_block \\ [])

View Source (macro)

Renders a component defined by the given function.

It takes two optional arguments, the assigns to pass to the given function and a do-block - which will be converted into a @inner_block assign (see render_block/3 for more information).

The given function must expect one argument, which are the assigns as a map.

Examples

The function can be either local:

<%= component(&weather_component/1, city: "Kraków") %>

Or remote:

<%= component(&MyApp.Weather.component/1, city: "Kraków") %>
Link to this macro

live_component(component, assigns \\ [], do_block \\ [])

View Source (macro)

Renders a Phoenix.LiveComponent within a parent LiveView.

While LiveViews can be nested, each LiveView starts its own process. A LiveComponent provides similar functionality to LiveView, except they run in the same process as the LiveView, with its own encapsulated state.

LiveComponent comes in two shapes, stateful and stateless. See Phoenix.LiveComponent for more information.

Examples

All of the assigns given are forwarded directly to the live_component:

<%= live_component(MyApp.WeatherComponent, id: "thermostat", city: "Kraków") %>

Note the :id won't necessarily be used as the DOM ID. That's up to the component. However, note that the :id has a special meaning: whenever an :id is given, the component becomes stateful. Otherwise, :id is always set to nil.

Link to this macro

live_component(socket, component, assigns, do_block)

View Source (macro)
Link to this function

live_file_input(conf, opts \\ [])

View Source

Builds a file input tag for a LiveView upload.

Options may be passed through to the tag builder for custom attributes.

Drag and Drop

Drag and drop is supported by annotating the droppable container with a phx-drop-target attribute pointing to the DOM ID of the file input. By default, the file input ID is the upload ref, so the following markup is all that is required for drag and drop support:

<div class="container" phx-drop-target="<%= @uploads.avatar.ref %>">
    ...
    <%= live_file_input @uploads.avatar %>
</div>

Examples

<%= live_file_input @uploads.avatar %>

Returns the flash message from the LiveView flash assign.

Examples

<p class="alert alert-info"><%= live_flash(@flash, :info) %></p>
<p class="alert alert-danger"><%= live_flash(@flash, :error) %></p>
Link to this function

live_img_preview(entry, opts \\ [])

View Source

Generates an image preview on the client for a selected file.

Examples

<%= for entry <- @uploads.avatar.entries do %>
  <%= live_img_preview entry, width: 75 %>
<% end %>

Generates a link that will patch the current LiveView.

When navigating to the current LiveView, Phoenix.LiveView.handle_params/3 is immediately invoked to handle the change of params and URL state. Then the new state is pushed to the client, without reloading the whole page while also maintaining the current scroll position. For live redirects to another LiveView, use live_redirect/2.

Options

  • :to - the required path to link to.
  • :replace - the flag to replace the current history or push a new state. Defaults false.

All other options are forwarded to the anchor tag.

Examples

<%= live_patch "home", to: Routes.page_path(@socket, :index) %>
<%= live_patch "next", to: Routes.live_path(@socket, MyLive, @page + 1) %>
<%= live_patch to: Routes.live_path(@socket, MyLive, dir: :asc), replace: false do %>
  Sort By Price
<% end %>
Link to this function

live_redirect(text, opts)

View Source

Generates a link that will redirect to a new LiveView.

The current LiveView will be shut down and a new one will be mounted in its place, without reloading the whole page. This can also be used to remount the same LiveView, in case you want to start fresh. If you want to navigate to the same LiveView without remounting it, use live_patch/2 instead.

Options

  • :to - the required path to link to.
  • :replace - the flag to replace the current history or push a new state. Defaults false.

All other options are forwarded to the anchor tag.

Examples

<%= live_redirect "home", to: Routes.page_path(@socket, :index) %>
<%= live_redirect "next", to: Routes.live_path(@socket, MyLive, @page + 1) %>
<%= live_redirect to: Routes.live_path(@socket, MyLive, dir: :asc), replace: false do %>
  Sort By Price
<% end %>
Link to this function

live_render(conn_or_socket, view, opts \\ [])

View Source

Renders a LiveView within an originating plug request or within a parent LiveView.

Options

  • :session - the map of extra session data to be serialized and sent to the client. Note that all session data currently in the connection is automatically available in LiveViews. You can use this option to provide extra data. Also note that the keys in the session are strings keys, as a reminder that data has to be serialized first.
  • :container - an optional tuple for the HTML tag and DOM attributes to be used for the LiveView container. For example: {:li, style: "color: blue;"}. By default it uses the module definition container. See the "Containers" section below for more information.
  • :id - both the DOM ID and the ID to uniquely identify a LiveView. An :id is automatically generated when rendering root LiveViews but it is a required option when rendering a child LiveView.
  • :router - an optional router that enables this LiveView to perform live navigation. Only a single LiveView in a page may have the :router set. LiveViews defined at the router with the live macro automatically have the :router option set.

Examples

# within eex template
<%= live_render(@conn, MyApp.ThermostatLive) %>

# within leex template
<%= live_render(@socket, MyApp.ThermostatLive, id: "thermostat") %>

Containers

When a LiveView is rendered, its contents are wrapped in a container. By default, said container is a div tag with a handful of LiveView specific attributes.

The container can be customized in different ways:

  • You can change the default container on use Phoenix.LiveView:

    use Phoenix.LiveView, container: {:tr, id: "foo-bar"}
  • You can override the container tag and pass extra attributes when calling live_render (as well as on your live call in your router):

    live_render socket, MyLiveView, container: {:tr, class: "highlight"}
Link to this function

live_title_tag(title, opts \\ [])

View Source

Renders a title tag with automatic prefix/suffix on @page_title updates.

Examples

<%= live_title_tag assigns[:page_title] || "Welcome", prefix: "MyApp – " %>

<%= live_title_tag assigns[:page_title] || "Welcome", suffix: " – MyApp" %>
Link to this macro

render_block(inner_block, argument \\ [])

View Source (macro)

Renders the @inner_block assign of a component with the given argument.

<%= render_block(@inner_block, value: @value)
Link to this macro

sigil_L(arg, list)

View Source (macro)

Provides ~L sigil with HTML safe Live EEx syntax inside source files.

iex> ~L"""
...> Hello <%= "world" %>
...> """
{:safe, ["Hello ", "world", "\n"]}

Returns the entry errors for an upload.

The following errors may be returned:

  • :too_many_files - The number of selected files exceeds the :max_entries constraint

Examples

def error_to_string(:too_many_files), do: "You have selected too many files"

<%= for err <- upload_errors(@uploads.avatar) do %>
  <div class="alert alert-danger">
    <%= error_to_string(err) %>
  </div>
<% end %>
Link to this function

upload_errors(conf, entry)

View Source

Returns the entry errors for an upload.

The following errors may be returned:

  • :too_large - The entry exceeds the :max_file_size constraint
  • :not_accepted - The entry does not match the :accept MIME types

Examples

def error_to_string(:too_large), do: "Too large"
def error_to_string(:not_accepted), do: "You have selected an unacceptable file type"

<%= for entry <- @uploads.avatar.entries do %>
  <%= for err <- upload_errors(@uploads.avatar, entry) do %>
    <div class="alert alert-danger">
      <%= error_to_string(err) %>
    </div>
  <% end %>
<% end %>