Phoenix.Template (Phoenix v1.5.6) View Source

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. We expose this private function via render/2, which can be invoked as:

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

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

Link to this section Summary

Functions

Returns a keyword list with all template engines extensions followed by their modules.

Returns all template paths in a given template root.

Returns the format encoder for the given template name.

Returns the hash of all template paths in the given root.

Converts a module, without the suffix, to a template root.

Converts the template path into the template name.

Link to this section Types

Link to this section Functions

Specs

engines() :: %{required(atom()) => module()}

Returns a keyword list with all template engines extensions followed by their modules.

Link to this function

find_all(root, pattern \\ "*", engines \\ engines())

View Source

Specs

find_all(root(), pattern :: String.t(), %{required(atom()) => module()}) :: [
  path()
]

Returns all template paths in a given template root.

Link to this function

format_encoder(template_name)

View Source

Specs

format_encoder(name()) :: module() | nil

Returns the format encoder for the given template name.

Link to this function

hash(root, pattern \\ "*", engines \\ engines())

View Source

Specs

hash(root(), pattern :: String.t(), %{required(atom()) => module()}) :: binary()

Returns the hash of all template paths in the given root.

Used by Phoenix to check if a given root path requires recompilation.

Link to this function

module_to_template_root(module, base, suffix)

View Source

Converts a module, without the suffix, to a template root.

Examples

iex> Phoenix.Template.module_to_template_root(MyApp.UserView, MyApp, "View")
"user"

iex> Phoenix.Template.module_to_template_root(MyApp.Admin.User, MyApp, "View")
"admin/user"

iex> Phoenix.Template.module_to_template_root(MyApp.Admin.User, MyApp.Admin, "View")
"user"

iex> Phoenix.Template.module_to_template_root(MyApp.View, MyApp, "View")
""

iex> Phoenix.Template.module_to_template_root(MyApp.View, MyApp.View, "View")
""
Link to this function

template_path_to_name(path, root)

View Source

Specs

template_path_to_name(path(), root()) :: name()

Converts the template path into the template name.

Examples

iex> Phoenix.Template.template_path_to_name(
...>   "lib/templates/admin/users/show.html.eex",
...>   "lib/templates")
"admin/users/show.html"