Phoenix.HTML v2.13.3 Phoenix.HTML.Tag 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.

Link to this section Summary

Functions

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

Generates a meta tag with CSRF information.

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

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

Generates a meta tag with CSRF information.

Tag attributes

  • content - a valid csrf token
  • csrf-param - a request parameter where expected csrf token
  • method-param - a request parameter where expected a custom HTTP method
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

  • :enforce_utf8 - when false, does not enforce utf8. Read below for more information

All other options are passed to the underlying HTML tag.

Enforce UTF-8

Although forms provide the accept-charset attribute, which we set to UTF-8, Internet Explorer 5 up to 8 may ignore the value of this attribute if the user chooses their browser to do so. This ends up triggering the browser to send data in a format that is not understandable by the server.

For this reason, Phoenix automatically includes a "_utf8=✓" parameter in your forms, to force those browsers to send the data in the proper encoding. This technique has been seen in the Rails web framework and reproduced here.

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", use static_path/1 to get a URL with cache control parameters:

img_tag(Routes.static_path("logo.png"))
<img src="logo.png?vsn=3456789">

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, "/images/logo.png"))
<img src="logo.png?vsn=3456789">

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.