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 "APP_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"

  def render(template, assigns) do
    render_template(template, assigns)
  end
end

Phoenix.Template will define a private function named render_template/2 with one clause per file system template. You are responsible to expose it appropriately, as shown above.

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

Options

• :root - the root template path to find templates
• :pattern - the wildcard pattern to apply to the root when finding templates. Default "*"
• :template_engines - a map of template engines extensions to template engine handlers

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_view, :template_engines,
  eex: Phoenix.Template.EExEngine,
  exs: Phoenix.Template.ExsEngine

If you want to support a given engine only on a certain template, you can pass it as an option on use Phoenix.Template:

use Phoenix.Template, template_engines: %{
  foo: Phoenix.Template.FooEngine
}

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_view, :format_encoders,
  html: Phoenix.HTML.Engine