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.
: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 handlersHere 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
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 }
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
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.
name() :: binary()
path() :: binary()
root() :: binary()
engines() :: %{required(atom()) => module()}
Returns a keyword list with all template engines extensions followed by their modules.
find_all(root(), pattern :: String.t(), %{required(atom()) => module()}) :: [ path() ]
Returns all template paths in a given template root.
format_encoder(name()) :: module() | nil
Returns the format encoder for the given template name.
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.
Converts a module, without the suffix, to a template root.
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") ""
template_path_to_name(path(), root()) :: name()
Converts the template path into the template name.
iex> Phoenix.Template.template_path_to_name( ...> "lib/templates/admin/users/show.html.eex", ...> "lib/templates") "admin/users/show.html"
© 2014 Chris McCord
Licensed under the MIT License.
https://hexdocs.pm/phoenix/Phoenix.Template.html