View Source Phoenix.WebComponent.Helpers.Link (Phoenix.WebComponent v2.2.3)
Conveniences for working with links and URLs in HTML.
Link to this section Summary
Functions
Returns a list of attributes that make an element behave like a link. For example, to make a button work like a link
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.
Generates a link that will patch the current LiveView.
When navigating to the current LiveView,
Phoenix.LiveView.handle_params/3
is
immediately invoked to handle the change of params and URL state.
Then the new state is pushed to the client, without reloading the
whole page while also maintaining the current scroll position.
For live redirects to another LiveView, use wc_live_redirect/2
.
Generates a link that will redirect to a new LiveView of the same live session.
The current LiveView will be shut down and a new one will be mounted
in its place, without reloading the whole page. This can
also be used to remount the same LiveView, in case you want to start
fresh. If you want to navigate to the same LiveView without remounting
it, use wc_live_patch/2
instead.
Note: The live redirects are only supported between two LiveViews defined
under the same live session. See Phoenix.LiveView.Router.live_session/3
for
more details.
Link to this section Functions
Returns a list of attributes that make an element behave like a link. For example, to make a button work like a link:
<button {link_attributes("/home")}>
Go back to home
</button>
However, this function is more often used to create buttons that must invoke an action on the server, such as deleting an entity, using the relevant HTTP protocol:
<button data-confirm="Are you sure?" {link_attributes("/product/1", method: :delete}>
Delete product
</button>
The to
argument may be a string, a URI, or a tuple {scheme, value}
.
See the examples below.
Note: using this function requires loading the JavaScript library
at priv/static/phoenix_html.js
. See the Phoenix.HTML
module
documentation for more information.
options
Options
:method
- the HTTP method for the link. Defaults to:get
.:csrf_token
- a custom token to use when method is not:get
. This is used to ensure the request was sent by the user who rendered the page. By default, CSRF tokens are generated throughPlug.CSRFProtection
. You can set this option tofalse
, to disable token generation, or set it to your own token. 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
The following data attributes can also be manually set in the element:
data-confirm
- shows a confirmation prompt before generating and submitting the form.
examples
Examples
iex> link_attributes("/world")
[data: [method: :get, to: "/world"]]
iex> link_attributes(URI.parse("https://elixir-lang.org"))
[data: [method: :get, to: "https://elixir-lang.org"]]
iex> link_attributes("/product/1", method: :delete)
[data: [csrf: Plug.CSRFProtection.get_csrf_token(), method: :delete, to: "/product/1"]]
if-the-url-is-absolute-only-certain-schemas-are-allowed-to-avoid-javascript-injection
If the URL is absolute, only certain schemas are allowed to avoid JavaScript injection.
For example, the following will fail
iex> link_attributes("javascript:alert('hacked!')")
** (ArgumentError) unsupported scheme given as link. In case you want to link to an
unknown or unsafe scheme, such as javascript, use a tuple: {:javascript, rest}
You can however explicitly render those unsafe schemes by using a tuple:
iex> link_attributes({:javascript, "alert('my alert!')"})
[data: [method: :get, to: ["javascript", 58, "alert('my alert!')"]]]
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
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
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
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
Examples
wc_link("hello", to: "/world")
#=> <a href="/world"><wc-button>hello</wc-button></a>
wc_link("hello", to: URI.parse("https://elixir-lang.org"))
#=> <a href="https://elixir-lang.org"><wc-button>hello</wc-button></a>
wc_link("<hello>", to: "/world")
#=> <a href="/world"><wc-button><hello></wc-button></a>
wc_link("<hello>", to: "/world", class: "btn")
#=> <a class="btn" href="/world"><wc-button><hello></wc-button></a>
wc_link("delete", to: "/the_world", data: [confirm: "Really?"])
#=> <a data-confirm="Really?" href="/the_world"><wc-button>delete</wc-button></a>
# If you supply a method other than `:get`:
wc_link("delete", to: "/everything", method: :delete)
#=> <a href="/everything" data-csrf="csrf_token" data-method="delete" data-to="/everything"><wc-button>delete</wc-button></a>
# You can use a `do ... end` block too:
link to: "/hello" do
"world"
end
#=> <a href="/hello"><wc-button>world</wc-button><a>
options
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.
data-attributes
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
.
csrf-protection
CSRF Protection
By default, CSRF tokens are generated through Plug.CSRFProtection
.
Generates a link that will patch the current LiveView.
When navigating to the current LiveView,
Phoenix.LiveView.handle_params/3
is
immediately invoked to handle the change of params and URL state.
Then the new state is pushed to the client, without reloading the
whole page while also maintaining the current scroll position.
For live redirects to another LiveView, use wc_live_redirect/2
.
options
Options
:to
- the required path to link to.:replace
- the flag to replace the current history or push a new state. Defaultsfalse
. All other options are forwarded to the anchor tag.
examples
Examples
<%= wc_live_patch "home", to: Routes.page_path(@socket, :index) %>
<%= wc_live_patch "next", to: Routes.live_path(@socket, MyLive, @page + 1) %>
<%= wc_live_patch to: Routes.live_path(@socket, MyLive, dir: :asc), replace: false do %>
Sort By Price
<% end %>
Generates a link that will redirect to a new LiveView of the same live session.
The current LiveView will be shut down and a new one will be mounted
in its place, without reloading the whole page. This can
also be used to remount the same LiveView, in case you want to start
fresh. If you want to navigate to the same LiveView without remounting
it, use wc_live_patch/2
instead.
Note: The live redirects are only supported between two LiveViews defined
under the same live session. See Phoenix.LiveView.Router.live_session/3
for
more details.
options
Options
:to
- the required path to link to.:replace
- the flag to replace the current history or push a new state. Defaultsfalse
. All other options are forwarded to the anchor tag.
examples
Examples
<%= wc_live_redirect "home", to: Routes.page_path(@socket, :index) %>
<%= wc_live_redirect "next", to: Routes.live_path(@socket, MyLive, @page + 1) %>
<%= wc_live_redirect to: Routes.live_path(@socket, MyLive, dir: :asc), replace: false do %>
Sort By Price
<% end %>