View Source Phoenix.Template (phoenix_view v1.1.2)

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

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"