Conveniences for working with links and URLs in HTML.
Generates a button that uses a regular HTML form to submit to the given URL.
Generates a link to the given URL.
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.
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>
: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 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.
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
: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.
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 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
. 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.
By default, CSRF tokens are generated through Plug.CSRFProtection
.
© 2014 Chris McCord
Licensed under the MIT License.
https://hexdocs.pm/phoenix_html/Phoenix.HTML.Link.html