Phoenix.View

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.