Phoenix.HTML

v2.2.0

Phoenix.HTML

Helpers for working with HTML strings and templates.

When used, it imports the given modules:

HTML Safe

One of the main responsibilities of this module is to provide convenience functions for escaping and marking HTML code as safe.

By default, data output in templates is not considered safe:

<%= "<hello>" %>

will be shown as:

&lt;hello&gt;

User data or data coming from the database is almost never considered safe. However, in some cases, you may want to tag it as safe and show its “raw” contents:

<%= raw "<hello>" %>

Keep in mind most helpers will automatically escape your data and return safe content:

<%= tag :p, "<hello>" %>

will properly output:

<p>&lt;hello&gt;</p>

Summary

Types

safe()

Guaranteed to be safe

unsafe()

May be safe or unsafe (i.e. it needs to be converted)

Functions

html_escape(safe)

Escapes the HTML entities in the given term, returning iodata

raw(value)

Marks the given content as raw

safe_to_string(arg)

Converts a safe result into a string

Macros

sigil_E(expr, opts)

Provides ~E sigil with HTML safe EEx syntax inside source files

sigil_e(expr, opts)

Provides ~e sigil with HTML safe EEx syntax inside source files

Types 

safe :: {:safe, iodata}

Guaranteed to be safe

unsafe :: Phoenix.HTML.Safe.t

May be safe or unsafe (i.e. it needs to be converted)

Functions

html_escape(safe)

Specs

html_escape(unsafe) :: safe

Escapes the HTML entities in the given term, returning iodata.

iex> html_escape("<hello>")
{:safe, "&lt;hello&gt;"}

iex> html_escape('<hello>')
{:safe, ["&lt;", 104, 101, 108, 108, 111, "&gt;"]}

iex> html_escape(1)
{:safe, "1"}

iex> html_escape({:safe, "<hello>"})
{:safe, "<hello>"}
raw(value)

Specs

raw(iodata | safe) :: safe

Marks the given content as raw.

This means any HTML code inside the given string won’t be escaped.

iex> raw("<hello>")
{:safe, "<hello>"}
iex> raw({:safe, "<hello>"})
{:safe, "<hello>"}
iex> raw(nil)
{:safe, ""}
safe_to_string(arg)

Specs

safe_to_string(safe) :: String.t

Converts a safe result into a string.

Fails if the result is not safe. In such cases, you can invoke html_escape/1 or raw/1 accordingly before.

Macros

sigil_E(expr, opts)

Provides ~E sigil with HTML safe EEx syntax inside source files.

This sigil does not support interpolation and is should be prefered rather than ~e.

iex> ~E"""
...> Hello <%= "world" %>
...> """
{:safe, [[["" | "Hello "] | "world"] | "\n"]}
sigil_e(expr, opts)

Provides ~e sigil with HTML safe EEx syntax inside source files.

iex> ~e"""
...> Hello <%= "world" %>
...> """
{:safe, [[["" | "Hello "] | "world"] | "\n"]}