Phoenix v0.14.0 → Overview → Phoenix → View

Phoenix.View

Summary
Functions
Macros

Defines the view layer of a Phoenix application.

This module is used to define the application main view, which serves as the base for all other views and templates in the application.

The view layer also contains conveniences for rendering templates, including support for layouts and encoders per format.

Examples

Phoenix defines the view template at web/web.ex:

defmodule YourApp.Web do
  def view do
    quote do
      use Phoenix.View, root: "web/templates"

      # Import common functionality
      import YourApp.Router.Helpers

      # Use Phoenix.HTML to import all HTML functions (forms, tags, etc)
      use Phoenix.HTML
    end
  end

  # ...
end

We can use the definition above to define any view in your application:

defmodule YourApp.UserView do
  use YourApp.Web, :view
end

Because we have defined the template root to be “web/template”, Phoenix.View will automatically load all templates at “web/template/user” and include them in the YourApp.UserView. For example, imagine we have the template:

# web/templates/user/index.html.eex
Hello <%= @name %>

The .eex extension is called a template engine which tells Phoenix how to compile the code in the file into actual Elixir source code. After it is compiled, the template can be rendered as:

Phoenix.View.render(YourApp.UserView, "index.html", name: "John Doe")
#=> {:safe, "Hello John Doe"}

We will discuss rendering in detail next.

Rendering

The main responsibility of a view is to render a template.

A template has a name, which also contains a format. For example, in the previous section we have rendered the “index.html” template:

Phoenix.View.render(YourApp.UserView, "index.html", name: "John Doe")
#=> {:safe, "Hello John Doe"}

When a view renders a template, the result returned is an inner representation specific to the template format. In the example above, we got: {:safe, "Hello John Doe"}. The safe tuple annotates that our template is safe and that we don’t need to escape its contents because all data was already encoded so far. Let’s try to inject custom code:

Phoenix.View.render(YourApp.UserView, "index.html", name: "John<br />Doe")
#=> {:safe, "Hello John<br />Doe"}

This inner representation allows us to render and compose templates easily. For example, if you want to render JSON data, we could do so by adding a “show.json” entry to render/2 in our view:

defmodule YourApp.UserView do
  use YourApp.View

  def render("show.json", %{user: user}) do
    %{name: user.name, address: user.address}
  end
end

Notice that in order to render JSON data, we don’t need to explicitly return a JSON string! Instead, we just return data that is encodable to JSON.

Both JSON and HTML formats will be encoded only when passing the data to the controller via the render_to_iodata/3 function. The render_to_iodata/3 uses the notion of format encoders to convert a particular format to its string/iodata representation.

Phoenix ships with some template engines and format encoders, which can be further configured in the Phoenix application. You can read more about format encoders in Phoenix.Template documentation.

Source

Summary↑

__using__(options)	When used, defines the current module as a main view module
render(module, template, assigns)	Renders a template
render_existing(module, template, assigns \\ [])	Renders a template only if it exists
render_many(collection, template)	See `render_many/4`
render_many(collection, template, assigns)	See `render_many/4`
render_many(collection, view, template, assigns)	Renders a collection
render_one(model, template)	See `render_one/4`
render_one(model, template, assigns)	See `render_one/4`
render_one(model, view, template, assigns)	Renders a single item if not nil
render_to_iodata(module, template, assign)	Renders the template and returns iodata
render_to_string(module, template, assign)	Renders the template and returns a string

Functions

render(module, template, assigns)

(function) # ↑

Renders a template.

It expects the view module, the template as a string, and a set of assigns.

Notice this function returns the inner representation of a template. If you want the encoded template as a result, use render_to_iodata/3 instead.

Examples

Phoenix.View.render(YourApp.UserView, "index.html", name: "John Doe")
#=> {:safe, "Hello John Doe"}

Assigns

Assigns are meant to be user data that will be available in templates. However there are keys under assigns that are specially handled by Phoenix, they are:

:layout - tells Phoenix to wrap the rendered result in the given layout. See next section.

Layouts

Templates can be rendered within other templates using the :layout option. :layout accepts a tuple of the form {LayoutModule, "template.extension"}.

When a template is rendered, the layout template will have an @inner assign containing the rendered contents of the sub-template. For HTML templates, @inner will be always marked as safe.

Phoenix.View.render(YourApp.UserView, "index.html",
                    layout: {YourApp.LayoutView, "app.html"})
#=> {:safe, "<html><h1>Hello!</h1></html>"}

Source

render_existing(module, template, assigns \\ [])

(function) # ↑

Renders a template only if it exists.

Same as render/3, but returns nil instead of raising. Useful for dynamically rendering templates in the layout that may or may not be implemented by the @inner view.

Examples

Consider the case where the application layout allows views to dynamically render a section of script tags in the head of the document. Some views may wish to inject certain scripts, while others will not.

<head>
  <%= render_existing view_module(@conn), "scripts.html", assigns %>
</head>

Then the module for the @inner view can decide to provide scripts with either a precompiled template, or by implementing the function directly, ie:

def render("scripts.html", _assigns) do
  "<script src="...">"
end

To use a precompiled template, create a scripts.html.eex file in the templates directory for the corresponding view you want it to render for. For example, for the UserView, create the scripts.html.eex file at web/templates/user/.

Rendering based on controller template

In some cases, you might need to render based on the template from the controller. For these cases, Phoenix.Controller.controller_template/1 can pair with render_existing/3 for per-template based content, ie:

<head>
  <%= render_existing view_module(@conn), "scripts." <> controller_template(@conn), assigns %>
</head>

def render("scripts.show.html", _assigns) do
  "<script src="...">"
end
def render("scripts.index.html", _assigns) do
  "<script src="...">"
end

Source

render_many(collection, template)

(function) # ↑

See render_many/4.

Source

render_many(collection, template, assigns)

(function) # ↑

See render_many/4.

Source

render_many(collection, view, template, assigns)

(function) # ↑

Renders a collection.

A collection is any enumerable of structs. This function returns the rendered collection in a list:

render_many users, "show.html"

is roughly equivalent to:

Enum.map(users, fn user ->
  render(UserView, "show.html", user: user)
end)

When a view is not given, it is automatically inflected from the given struct. The underlying user is passed to the view and template as :user, which is inflected from the view name. The name of the key in assigns can be customized with the :as option:

render_many users, "show.html", as: :data

is roughly equivalent to:

Enum.map(users, fn user ->
  render(UserView, "show.html", data: user)
end)

Overall, this function has four signatures:

render_many(collection, template)
render_many(collection, template, assigns)
render_many(collection, view, template)
render_many(collection, view, template, assigns)

Source

render_one(model, template)

(function) # ↑

See render_one/4.

Source

render_one(model, template, assigns)

(function) # ↑

See render_one/4.

Source

render_one(model, view, template, assigns)

(function) # ↑

Renders a single item if not nil.

The following:

render_one user, "show.html"

is roughly equivalent to:

if user != nil do
  render(UserView, "show.html", user: user)
end

render_one user, "show.html", as: :data

is roughly equivalent to:

if user != nil do
  render(UserView, "show.html", data: user)
end

Overall, this function has four signatures:

render_one(model, template)
render_one(model, template, assigns)
render_one(model, view, template)
render_one(model, view, template, assigns)

Source

render_to_iodata(module, template, assign)

(function) # ↑

Renders the template and returns iodata.

Source

render_to_string(module, template, assign)

(function) # ↑

Renders the template and returns a string.

Source

Macros

__using__(options)

(macro) # ↑

When used, defines the current module as a main view module.

Options

:root - the template root to find templates
:namespace - the namespace to consider when calculating view paths

The :root option is required while the :namespace defaults to the first nesting in the module name. For instance, both MyApp.UserView and MyApp.Admin.UserView have namespace MyApp.

The namespace is used to calculate paths. For example, if you are in MyApp.UserView and the namespace is MyApp, templates are expected at Path.join(root, "user"). On the other hand, if the view is MyApp.Admin.UserView, the path will be Path.join(root, "admin/user") and so on.

Setting the namespace to MyApp.Admin in the second example will force the template to also be looked up at Path.join(root, "user").

Source