Phoenix.HTML.Link (Phoenix.HTML v3.1.0) View Source

Conveniences for working with links and URLs in HTML.

Link to this section Summary

Functions

Generates a button tag that uses the Javascript function handleClick() (see phoenix_html.js) to submit the form data.

Generates a link to the given URL.

Link to this section Functions

Generates a button tag that uses the Javascript function handleClick() (see phoenix_html.js) to submit the form data.

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.

When the :method is set to :get and the :to URL contains query parameters the generated form element will strip the parameters in accordance with the W3C form specification.

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: URI.parse("https://elixir-lang.org"))
#=> <a href="https://elixir-lang.org">hello</a>

link("<hello>", to: "/world")
#=> <a href="/world">&lt;hello&gt;</a>

link("<hello>", to: "/world", class: "btn")
#=> <a class="btn" href="/world">&lt;hello&gt;</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.