Templates are used by Phoenix when rendering responses.

Since many views render significant content, for example a whole HTML file, it is common to put these files into a particular directory, typically “web/templates”.

This module provides conveniences for reading all files from a particular directory and embedding them into a single module. Imagine you have a directory with templates:

# templates/foo.html.eex
Hello <%= @name %>

# templates.ex
defmodule Templates do
  use Phoenix.Template, root: "templates"
end

Now the template foo can be directly rendered with:

Templates.render("foo.html", %{name: "John Doe"})

Options

• :root - the root template path to find templates
• :pattern - the wildcard pattern to apply to the root when finding templates. Default "*"

Rendering

In some cases, you will want to override the render/2 clause to compose the assigns for the template before rendering. In such cases, you can render the template directly by calling the generated private function render_template/2. For example:

# templates/foo.html.eex
Hello <%= @name %>

# templates.ex
defmodule Templates do
  use Phoenix.Template, root: "templates"

  def render("foo.html", %{name: name}) do
    render_template("foo.html", %{name: String.upcase(name)})
  end
end

In practice, developers rarely use Phoenix.Template directly. Instead they use Phoenix.View which wraps the template functionality and adds some extra conveniences.

Terminology

Here is a quick introduction into Phoenix templates terms:

• template name - is the name of the template as given by the user, without the template engine extension, for example: “users.html”

• template path - is the complete path of the template in the filesystem, for example, “path/to/users.html.eex”

• template root - the directory where templates are defined

• template engine - a module that receives a template path and transforms its source code into Elixir quoted expressions.

Custom Template Engines

Phoenix supports custom template engines. Engines tell Phoenix how to convert a template path into quoted expressions. See Phoenix.Template.Engine for more information on the API required to be implemented by custom engines.

Once a template engine is defined, you can tell Phoenix about it via the template engines option:

config :phoenix, :template_engines,
  eex: Phoenix.Template.EExEngine,
  exs: Phoenix.Template.ExsEngine

Format encoders

Besides template engines, Phoenix has the concept of format encoders. Format encoders work per format and are responsible for encoding a given format to string once the view layer finishes processing.

A format encoder must export a function called encode_to_iodata!/1 which receives the rendering artifact and returns iodata.

New encoders can be added via the format encoder option:

config :phoenix, :format_encoders,
  html: Phoenix.Template.HTML,
  json: Poison