Mjml (mjml v5.1.1)

View Source

Provides functions for transpiling MJML email templates to HTML.

Summary

Functions

Converts an MJML string to HTML content.

Functions

to_html(mjml, opts \\ [])

Converts an MJML string to HTML content.

Returns a result tuple:

  • {:ok, html} for a successful MJML transpiling
  • {:error, message} for a failed MJML transpiling

You can pass the following options to customize the parsing of the MJML template and rendering of the final HTML:

  • keep_comments – when false, removes the comments from the rendered HTML. Defaults to true.

  • social_icon_path – when given, uses this base path to generate social icon URLs. E.g. social_icon_path: "https://example.com/icons/" will generate a social icon URL, like "https://example.com/icons/github.png"

  • fonts – a Map of font names and their URLs to hosted CSS files. When given, includes these fonts in the rendered HTML (Note that only actually used fonts will show up!). Defaults to nil, which will make the default font families available to be used (Open Sans, Droid Sans, Lato, Roboto, and Ubuntu).

  • include_loader - the loader to use for mj-include tags. Currently, the only supported include loader is Mjml.ParserOptions.LocalIncludeLoader. By default, there is no include loader configured, which means that transpiling MJML templates with mj-include tags will fail with an error.

Examples

iex> Mjml.to_html("<mjml><mj-head></mj-head></mjml>")
{:ok, "<!doctype html><html xmlns=..."}

iex> Mjml.to_html("something not MJML")
{:error, "Couldn't convert MJML template"}

iex> opts = [
iex>   keep_comments: false,
iex>   social_icon_path: "https://example.com/icons/"
iex>   fonts: %{
iex>     "Noto Color Emoji": "https://fonts.googleapis.com/css?family=Noto+Color+Emoji:400"
iex>   }
iex> ]
iex> Mjml.to_html("<mjml><mj-head></mj-head></mjml>", opts)
{:ok, "<!doctype html><html xmlns=..."}

iex> Mjml.to_html("<mjml><mj-head><mj-include path="./partial.mjml"/></mj-head></mjml>")
{:error, "unable to load include template ..."}

iex> alias Mjml.ParserOptions.LocalIncludeLoader
iex> opts = [include_loader: %LocalIncludeLoader{}]
iex> Mjml.to_html("<mjml><mj-head><mj-include path="file:///./partial.mjml"/></mj-head></mjml>", opts)
{:ok, "<!doctype html><html xmlns=..."} # assuming `partial.mjml` exists in the current working directory

iex> opts = [include_loader: %LocalIncludeLoader{path: "/path/to/mjml/includes"}]
iex> Mjml.to_html("<mjml><mj-head><mj-include path="file:///partial.mjml"/></mj-head></mjml>", opts)
{:ok, "<!doctype html><html xmlns=..."} # assuming `partial.mjml` exists in the specified path