View Source Phoenix.HTML.Tag (Phoenix.HTML v3.3.1)
Helpers related to producing HTML tags within templates.
Note: with the addition of the HEEx template engine to Phoenix applications, the functions in this module have lost a bit of relevance and must only be used in special circumstances.
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>
Note: the examples in this module use
safe_to_string/1
imported fromPhoenix.HTML
for readability.
Link to this section Summary
Functions
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
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\"><Hello></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>"
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
Example
<form action="/login" method="POST">
<%= csrf_input_tag("/login") %>
etc.
</form>
Additional options to the tag can be given.
Generates a meta tag with CSRF information.
Additional options to the tag can be given.
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.
Generates a form tag.
This function generates the <form>
tag without its closing part.
Check form_tag/3
for generating an enclosing tag.
examples
Examples
form_tag("/hello")
<form action="/hello" method="post">
form_tag("/hello", method: :get)
<form action="/hello" method="get">
options
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
CSRF Protection
By default, CSRF tokens are generated through Plug.CSRFProtection
.
Generates a form tag with the given contents.
examples
Examples
form_tag("/hello", method: "get") do
"Hello"
end
<form action="/hello" method="get">...Hello...</form>
Generates an img tag with a src.
examples
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
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
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.