View Source Phoenix.Template (phoenix_template v1.0.0)

Templates are markup languages that are compiled to Elixir code.

This module provides functions for loading and compiling templates from disk. A markup language is compiled to Elixir code via an engine. See Phoenix.Template.Engine.

In practice, developers rarely use Phoenix.Template directly. Instead, libraries such as Phoenix.View and Phoenix.LiveView use it as a building block.

custom-template-engines

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

format-encoders

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 a string. For example, when rendering JSON, your templates may return a regular Elixir map. Then the JSON format encoder is invoked to convert it to JSON.

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

Link to this section Summary

Functions

Compiles a function for each template in the given root.

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.

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

Renders template from module.

Renders the template and returns iodata.

Renders the template to string.

Link to this section Types

Link to this section Functions

Link to this macro

compile_all(converter, root, pattern \\ "*", engines \\ nil)

View Source (macro)

Compiles a function for each template in the given root.

converter is an anonymous function that receives the template path and returns the function name (as a string).

For example, to compile all .eex templates in a given directory, you might do:

Phoenix.Template.compile_all(
  &(&1 |> Path.basename() |> Path.rootname(".eex")),
  __DIR__,
  "*.eex"
)

If the directory has templates named foo.eex and bar.eex, they will be compiled into the functions foo/1 and bar/1 that receive the template assigns as argument.

You may optionally pass a keyword list of engines. If a list is given, we will lookup and compile only this subset of engines. If none is passed (nil), the default list returned by engines/0 is used.

@spec 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
@spec find_all(root(), pattern :: String.t(), %{required(atom()) => module()}) :: [
  path()
]

Returns all template paths in a given template root.

@spec format_encoder(format :: String.t()) :: module() | nil

Returns the format encoder for the given template.

Link to this function

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

View Source
@spec 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
This function is deprecated. Use Phoenix.View.module_to_template_root/3.
Link to this function

render(module, template, format, assigns)

View Source

Renders template from module.

For a module called MyApp.FooHTML and template "index.html.heex", it will:

  • First attempt to call MyApp.FooHTML.index(assigns)

  • Then fallback to MyApp.FooHTML.render("index.html", assigns)

  • Raise otherwise

It expects the HTML module, the template as a string, the format, and a set of assigns.

Notice that this function returns the inner representation of a template. If you want the encoded template as a result, use render_to_iodata/4 instead.

examples

Examples

Phoenix.Template.render(YourApp.UserView, "index", "html", name: "John Doe")
#=> {:safe, "Hello John Doe"}

assigns

Assigns

Assigns are meant to be user data that will be available in templates. However, there are keys under assigns that are specially handled by Phoenix, they are:

  • :layout - tells Phoenix to wrap the rendered result in the given layout. See next section

layouts

Layouts

Templates can be rendered within other templates using the :layout option. :layout accepts a tuple of the form {LayoutModule, "template.extension"}.

To template that goes inside the layout will be placed in the @inner_content assign:

<%= @inner_content %>
Link to this function

render_to_iodata(module, template, format, assign)

View Source

Renders the template and returns iodata.

Link to this function

render_to_string(module, template, format, assign)

View Source

Renders the template to string.

Link to this function

template_path_to_name(path, root)

View Source
This function is deprecated. Use Phoenix.View.template_path_to_name/3.