Phoenix.HTML v2.14.2 Phoenix.HTML.Link View Source
Conveniences for working with links and URLs in HTML.
Link to this section Summary
Functions
Generates a button that uses a regular HTML form to submit to the given URL.
Generates a link to the given URL.
Link to this section Functions
Generates a button that uses a regular HTML form to submit to the given URL.
Useful to ensure that links that change data are not triggered by search engines and other spidering software.
Examples
button("hello", to: "/world")
#=> <button class="button" data-csrf="csrf_token" data-method="post" data-to="/world">hello</button>
button("hello", to: "/world", method: :get, class: "btn")
#=> <button class="btn" data-method="get" data-to="/world">hello</button>
Options
:to
- the page to link to. This option is required:method
- the method to use with the button. Defaults to :post.
All other options are forwarded to the underlying button input.
Data attributes
Data attributes are added as a keyword list passed to the
data
key. The following data attributes are supported:
data-confirm
- shows a confirmation prompt before generating and submitting the form.
Generates a link to the given URL.
Examples
link("hello", to: "/world")
#=> <a href="/world">hello</a>
link("<hello>", to: "/world")
#=> <a href="/world"><hello></a>
link("<hello>", to: "/world", class: "btn")
#=> <a class="btn" href="/world"><hello></a>
link("delete", to: "/the_world", data: [confirm: "Really?"])
#=> <a data-confirm="Really?" href="/the_world">delete</a>
# If you supply a method other than `:get`:
link("delete", to: "/everything", method: :delete)
#=> <a href="/everything" data-csrf="csrf_token" data-method="delete" data-to="/everything">delete</a>
# You can use a `do ... end` block too:
link to: "/hello" do
"world"
end
Options
:to
- the page to link to. This option is required:method
- the method to use with the link. In case the method is not:get
, the link is generated inside the form which sets the proper information. In order to submit the form, JavaScript must be enabled:csrf_token
- a custom token to use for links with a method other than:get
.
All other options are forwarded to the underlying <a>
tag.
JavaScript dependency
In order to support links where :method
is not :get
or use the above
data attributes, Phoenix.HTML
relies on JavaScript. You can load
priv/static/phoenix_html.js
into your build tool.
Data attributes
Data attributes are added as a keyword list passed to the data
key.
The following data attributes are supported:
data-confirm
- shows a confirmation prompt before generating and submitting the form when:method
is not:get
.
Overriding the default confirm behaviour
phoenix_html.js
does trigger a custom event phoenix.link.click
on the
clicked DOM element when a click happened. This allows you to intercept the
event on it's way bubbling up to window
and do your own custom logic to
enhance or replace how the data-confirm
attribute is handled.
You could for example replace the browsers confirm()
behavior with a
custom javascript implementation:
// listen on document.body, so it's executed before the default of
// phoenix_html, which is listening on the window object
document.body.addEventListener('phoenix.link.click', function (e) {
// Prevent default implementation
e.stopPropagation();
// Introduce alternative implementation
var message = e.target.getAttribute("data-confirm");
if(!message){ return true; }
vex.dialog.confirm({
message: message,
callback: function (value) {
if (value == false) { e.preventDefault(); }
}
})
}, false);
Or you could attach your own custom behavior.
window.addEventListener('phoenix.link.click', function (e) {
// Introduce custom behaviour
var message = e.target.getAttribute("data-prompt");
var answer = e.target.getAttribute("data-prompt-answer");
if(message && answer && (answer != window.prompt(message))) {
e.preventDefault();
}
}, false);
The latter could also be bound to any click
event, but this way you can be
sure your custom code is only executed when the code of phoenix_html.js
is run.
CSRF Protection
By default, CSRF tokens are generated through Plug.CSRFProtection
.