Phoenix.HTML.Tag (Phoenix.HTML v3.0.2) View Source

Helpers related to producing HTML tags within templates.

Note: the examples in this module use safe_to_string/1 imported from Phoenix.HTML for readability.

Note: with the addition of the HEEx template engine to Phoenix applications, the functions in this module have lost a bit of relevance. Whenever possible, prefer to use the HEEx template engine instead of the functions here. For example, instead of:

<%= content_tag :div, class: @class do %>
  Hello
<% end %>

Do:

<div class={@class}>
  Hello
</div>

Link to this section Summary

Functions

Escapes an enumerable of attributes, returning iodata.

Creates an HTML tag with given name, content, and attributes.

Generates a hidden input tag with a CSRF token.

Generates a meta tag with CSRF information.

Returns the csrf_token value to be used by forms, meta tags, etc.

Generates a form tag.

Generates a form tag with the given contents.

Generates an img tag with a src.

Creates an HTML tag with the given name and options.

Link to this section Functions

Link to this function

attributes_escape(attrs)

View Source

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> attributes_escape(title: "the title", id: "the id", selected: true)
{:safe,
 [
   [32, "title", 61, 34, "the title", 34],
   [32, "id", 61, 34, "the id", 34],
   [32, "selected"]
 ]}

iex> attributes_escape(%{data: [phx: [value: [foo: "bar"]]], class: "foo"})
{:safe,
 [
   [32, "class", 61, 34, "foo", 34],
   [32, "data-phx-value-foo", 61, 34, "bar", 34]
 ]}
Link to this function

content_tag(name, content)

View Source

Creates an HTML tag with given name, content, and attributes.

See Phoenix.HTML.Tag.tag/2 for more information and examples.

iex> safe_to_string content_tag(:p, "Hello")
"<p>Hello</p>"

iex> safe_to_string content_tag(:p, "<Hello>", class: "test")
"<p class=\"test\">&lt;Hello&gt;</p>"

iex> safe_to_string(content_tag :p, class: "test" do
...>   "Hello"
...> end)
"<p class=\"test\">Hello</p>"

iex> safe_to_string content_tag(:option, "Display Value", [{:data, [foo: "bar"]}, value: "value"])
"<option data-foo=\"bar\" value=\"value\">Display Value</option>"
Link to this function

content_tag(name, attrs, attrs)

View Source
Link to this function

csrf_input_tag(to, opts \\ [])

View Source

Generates a hidden input tag with a CSRF token.

This could be used when writing a form without the use of tag helpers like form_tag/3 or form_for/4, while maintaining CSRF protection.

The to argument should be the same as the form action.

Example

<form action="/login" method="POST">
  <%= csrf_input_tag("/login") %>

  etc.
</form>

Additional options to the tag can be given.

Link to this function

csrf_meta_tag(opts \\ [])

View Source

Generates a meta tag with CSRF information.

Additional options to the tag can be given.

Link to this function

csrf_token_value(to \\ %URI{host: nil})

View Source

Returns the csrf_token value to be used by forms, meta tags, etc.

By default, CSRF tokens are generated through Plug.CSRFProtection which is capable of generating a separate token per host. Therefore it is recommended to pass the URI of the destination as argument. If none is given %URI{host: nil} is used, which implies a local request is being done.

Link to this function

form_tag(action, opts \\ [])

View Source

Generates a form tag.

This function generates the <form> tag without its closing part. Check form_tag/3 for generating an enclosing tag.

Examples

form_tag("/hello")
<form action="/hello" method="post">

form_tag("/hello", method: :get)
<form action="/hello" method="get">

Options

  • :method - the HTTP method. If the method is not "get" nor "post", an input tag with name _method is generated along-side the form tag. Defaults to "post".

  • :multipart - when true, sets enctype to "multipart/form-data". Required when uploading files

  • :csrf_token - for "post" requests, the form tag will automatically include an input tag with name _csrf_token. When set to false, this is disabled

All other options are passed to the underlying HTML tag.

CSRF Protection

By default, CSRF tokens are generated through Plug.CSRFProtection.

Link to this function

form_tag(action, options, list)

View Source

Generates a form tag with the given contents.

Examples

form_tag("/hello", method: "get") do
  "Hello"
end
<form action="/hello" method="get">...Hello...</form>
Link to this function

img_tag(src, opts \\ [])

View Source

Generates an img tag with a src.

Examples

img_tag(user.photo_path)
<img src="/photo.png">

img_tag(user.photo, class: "image")
<img src="/smile.png" class="image">

To generate a path to an image hosted in your application "priv/static", with the @conn endpoint, use static_path/2 to get a URL with cache control parameters:

img_tag(Routes.static_path(@conn, "/logo.png"))
<img src="/logo-123456.png?vsn=d">

For responsive images, pass a map, list or string through :srcset.

img_tag("/logo.png", srcset: %{"/logo.png" => "1x", "/logo-2x.png" => "2x"})
<img src="/logo.png" srcset="/logo.png 1x, /logo-2x.png 2x">

img_tag("/logo.png", srcset: ["/logo.png", {"/logo-2x.png", "2x"}])
<img src="/logo.png" srcset="/logo.png, /logo-2x.png 2x">

Creates an HTML tag with the given name and options.

iex> safe_to_string tag(:br)
"<br>"
iex> safe_to_string tag(:input, type: "text", name: "user_id")
"<input name=\"user_id\" type=\"text\">"

Data attributes

In order to add custom data attributes you need to pass a tuple containing :data atom and a keyword list with data attributes' names and values as the first element in the tag's attributes keyword list:

iex> safe_to_string tag(:input, [data: [foo: "bar"], id: "some_id"])
"<input data-foo=\"bar\" id=\"some_id\">"

Boolean values

In case an attribute contains a boolean value, its key is repeated when it is true, as expected in HTML, or the attribute is completely removed if it is false:

iex> safe_to_string tag(:audio, autoplay: "autoplay")
"<audio autoplay=\"autoplay\">"
iex> safe_to_string tag(:audio, autoplay: true)
"<audio autoplay>"
iex> safe_to_string tag(:audio, autoplay: false)
"<audio>"

If you want the boolean attribute to be sent as is, you can explicitly convert it to a string before.