@spec default_footer_html(keyword()) :: String.t()

Core's footer: the site's name and a link to the site.

Options

• :link — false prints {{site_url}} as text instead of a link. Default true.

@spec default_header_html(keyword()) :: String.t()

Core's header: the logo when there is one, else the site's name.

Options

• :logo — true when {{logo_url}} is set. Default false.

@spec default_html(keyword()) :: String.t()

Core's layout: a card with the header, the body and the footer — and a bar in the accent colour on top when the site has chosen one.

Options

• :locale — becomes the document's lang attribute when it is a well-formed language tag (pt_BR is written pt-BR); omitted otherwise.
• :accent_bar — true draws a 3px bar in {{accent_color}} on top of the card. Default false.

@spec document?(String.t()) :: boolean()

Whether html is a whole document rather than a fragment to wrap.

Leading byte-order marks, whitespace (non-breaking included), comments and an XML prolog are skipped before looking for <!doctype or <html.

@spec footer_name() :: String.t()

The reserved template name the footer resolves under.

@spec header_name() :: String.t()

The reserved template name the header resolves under.

@spec name() :: String.t()

The reserved template name the layout resolves under.

@spec render(String.t(), String.t() | nil, keyword()) :: {String.t(), sources()}

Wraps an HTML fragment in the layout, and says where the layout, header and footer came from.

Options

• :locale, :paths — the message's own, so the chrome resolves from the same override roots and for the same reader as the message.
• :group — the email's group (see "Groups" above); nil for none.
• :branding — the logo_url/accent_color variables, when the caller has already read them (an invalid value reads as no logo / the neutral colour); read from PhoenixKit.Email.Branding otherwise.
• :accent_bar — whether core's layout draws its accent bar. Defaults to whether the email_accent_color setting holds a colour, so a site that never chose one looks as it did before the bar existed.

@spec render_parts(String.t() | nil, keyword()) :: parts()

The header and footer for a message, rendered on their own, without the layout around them.

For a caller that builds its own document but wants the site's chrome in it — a newsletter's wrapper, say, placing {{{header}}} and {{{footer}}} around its own body. The parts are chosen exactly as render/3 chooses them — both use the same private resolution: per group, locale and override root, an empty file counting as missing, core's own part last (see "Groups" and "Core's defaults" above).

Takes render/3's :locale, :paths, :group and :branding options; subject may be nil. One default differs: without :paths (or with paths: nil) the host's override roots are read, PhoenixKit.Email.Content.override_paths/0 — the same roots PhoenixKit.Email.Content.resolve/5 reads — so a caller gets the host's _header/_footer files without naming them. Pass paths: [] for core's parts only. Returns parts/0:

parts = Layout.render_parts(subject, locale: "de", group: "newsletters")

variables =
  Map.merge(parts.variables, %{
    "header" => parts.header,
    "footer" => parts.footer,
    "content" => body_html
  })

Substitution.substitute(wrapper, variables, escape: true)

header and footer are HTML: place them with three braces. Everything in variables is raw text: place it with two braces, under escape: true.

@spec text_to_html(String.t()) :: String.t()

Plain text as an HTML fragment.

Every character of text is escaped. A blank line separates paragraphs, each a <p>; a single line break becomes <br>. An http:// or https:// address becomes a link. It ends at <, >, ", any Unicode whitespace or separator, any invisible format character (zero-width spaces and joiners, the soft hyphen, the byte-order mark, bidirectional controls — which could otherwise make a link display a different address from the one it opens), guillemets, the em dash and the punctuation after it up to the ellipsis (U+2014–U+2027: typographic quotes, … and the like), and CJK/fullwidth punctuation. Hyphens and the en dash do not end it, since real addresses carry them. Trailing sentence punctuation and unbalanced closing parentheses stay outside it. No other scheme becomes a link, so javascript: and friends remain text, and neither does an address longer than 2048 bytes.

@spec valid_group?(term()) :: boolean()

Whether group is a usable group name: [a-z0-9-]+.

@spec wrap(String.t(), String.t() | nil, keyword()) :: String.t()

Wraps an HTML fragment in the layout for this message's locale.

subject may be nil. See render/3 for the options.