Phoenix.Template (Phoenix v1.5.9) 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
Returns a keyword list with all template engines extensions followed by their modules.
Specs
Returns all template paths in a given template root.
Specs
Returns the format encoder for the given template name.
Specs
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.
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")
""
Specs
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"