Phoenix.HTML

v2.13.3

Phoenix.HTML v2.13.3 Phoenix.HTML View Source

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:

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

will properly output:

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

Link to this section 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.

javascript_escape(data)

Escapes HTML content to be inserted a JavaScript string.

raw(value)

Marks the given content as raw.

safe_to_string(arg)

Converts a safe result into a string.

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.

Link to this section Types

Link to this type

safe() View Source 
safe() :: {:safe, iodata()}

Guaranteed to be safe

Link to this type

unsafe() View Source 
unsafe() :: Phoenix.HTML.Safe.t()

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

Link to this section Functions

Link to this function

html_escape(safe) View Source 
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>"}
Link to this function

javascript_escape(data) View Source 
javascript_escape(binary()) :: binary()
javascript_escape(safe()) :: safe()

Escapes HTML content to be inserted a JavaScript string.

This function is useful in JavaScript responses when there is a need to escape HTML rendered from other templates, like in the following:

$("#container").append("<%= javascript_escape(render("post.html", post: @post)) %>");

It escapes quotes (double and single), double backslashes and others.

Link to this function

raw(value) View Source 
raw(iodata() | safe() | nil) :: 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, ""}
Link to this function

safe_to_string(arg) View Source 
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.

Link to this macro

sigil_E(expr, opts) View Source (macro)

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

Does not raise on attempts to interpolate with #{}, but rather shows those characters literally, so it should be preferred over ~e.

iex> ~E"""
...> Hello <%= "world" %>
...> """
{:safe, ["Hello ", "world", "\n"]}
Link to this macro

sigil_e(expr, opts) View Source (macro)

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

Raises on attempts to interpolate with #{}, so ~E should be preferred.

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