Phoenix.HTML (Phoenix.HTML v3.1.0) View Source
Helpers for working with HTML strings and templates.
When used, it imports the given modules:
Phoenix.HTML- functions to handle HTML safety;Phoenix.HTML.Tag- functions for generating HTML tags;Phoenix.HTML.Form- functions for working with forms;Phoenix.HTML.Link- functions for generating links and urls;Phoenix.HTML.Format- functions for formatting text;
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:
<hello>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><hello></p>Link to this section Summary
Functions
Escapes an enumerable of attributes, returning iodata.
Escapes the HTML entities in the given term, returning safe iodata.
Escapes HTML content to be inserted a JavaScript string.
Marks the given content as raw.
Converts a safe result into a string.
Provides ~E sigil with HTML safe EEx syntax inside source files.
Provides ~e sigil with HTML safe EEx syntax inside source files.
Link to this section Types
Specs
safe() :: {:safe, iodata()}
Guaranteed to be safe
Specs
unsafe() :: Phoenix.HTML.Safe.t()
May be safe or unsafe (i.e. it needs to be converted)
Link to this section Functions
Escapes an enumerable of attributes, returning iodata.
Pay attention that, unlike tag/2 and content_tag/2, this
function does not sort the attributes. However if given a map,
note also that the key ordering may change.
iex> safe_to_string attributes_escape(title: "the title", id: "the id", selected: true)
" title=\"the title\" id=\"the id\" selected"
iex> safe_to_string attributes_escape(%{data: [phx: [value: [foo: "bar"]]], class: "foo"})
" class=\"foo\" data-phx-value-foo=\"bar\""Specs
Escapes the HTML entities in the given term, returning safe iodata.
iex> html_escape("<hello>")
{:safe, [[[] | "<"], "hello" | ">"]}
iex> html_escape('<hello>')
{:safe, ["<", 104, 101, 108, 108, 111, ">"]}
iex> html_escape(1)
{:safe, "1"}
iex> html_escape({:safe, "<hello>"})
{:safe, "<hello>"}Specs
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.
Specs
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, ""}Specs
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.
You can combine html_escape/1 and safe_to_string/1
to convert a data structure to a escaped string:
data |> html_escape() |> safe_to_string()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"]}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"]}