API Attributes and options
Unpoly attributes
Unpoly provides up-prefixed attributes that enable additional behavior on HTML elements.
For example, the [up-follow] attribute will cause a clicked link to swap the <main> or <body> element
instead of replacing the full page:
<a href="/path" up-follow>Click me</a> <!-- mark-phrase "up-follow" -->
Modifying attributes
Most Unpoly attributes have modifying attributes to fine-tune their behavior.
For example, the [up-transition] attribute causes an [up-follow] to swap
using an animated transition:
<a href="/path" up-follow up-transition="cross-fade">Click me</a> <!-- mark-phrase "up-transition" -->
Modifying attributes are documented with the main attribute they're modifying.
For example, see modifying attributes for [up-follow].
Configuring default behavior for all elements
Instead of configuring the same attributes on many elements, you can configure Unpoly to apply behavior to all elements matching a given CSS selector.
For example, the following configuration will enable single-page navigation for all hyperlinks:
up.link.config.followSelectors.push('a[href]')
Unpoly will now handle all links, even those without
an [up-follow] attribute:
<a href="/path">Click for single-page navigation</a>
Tip
An alternative way to apply default behavior to many elements is a macro.
Making exceptions
You can still make exceptions by setting an [up-follow=false] attribute:
<a href="/path" up-follow="false">Click for full page load</a> <!-- mark-phrase "false" -->
Overriding attributes with JavaScript options
Most Unpoly attributes come with matching JavaScript functions that trigger the same behavior programmatically.
Let's say you have the following link:
<a href="/path" up-follow up-meta-tags="false">Click me</a>
Your scripts can tell Unpoly to follow the link like this:
up.follow(link)
The up.follow() call will parse all modifying attributes from the given link element into a JavaScript object
with camel-cased keys. So we're implicitly making the following call:
// The options object is parsed from the link and can be omitted
up.follow(link, { url: '/path', metaTags: false })
If you pass other options, these will override (or supplement) any options parsed from the link's attributes:
// This overrides the [up-meta-tags=false] attribute
up.follow(link, { metaTags: true })
Auto-attributes
Some attributes default to a value "auto". This indicates a more complex default.
For example, the [up-cache=auto] attribute caches all links with a GET method:
<a href="/path" up-follow up-cache="auto">Click me</a> <!-- mark-phrase "auto" -->
You can usually configure auto-behavior. For example, the following will prevent auto-caching
of requests to URLs ending with /edit:
let defaultAutoCache = up.network.config.autoCache
up.network.config.autoCache = function(request) {
defaultAutoCache(request) && !request.url.endsWith('/edit')
}
Boolean attributes
Most Unpoly attributes can be enabled with a value "true" and be disabled with a value "false":
<a href="/path" up-follow="true">Click for single-page navigation</a> <!-- mark-phrase "true" -->
<a href="/path" up-follow="false">Click for full page load</a> <!-- mark-phrase "false" -->
Instead of setting a true you can also set an empty value:
<a href="/path" up-follow>Click for single-page navigation</a>
<a href="/path" up-follow="">Click for single-page navigation</a>
<a href="/path" up-follow="true">Click for single-page navigation</a>
Boolean values can be helpful with a server-side templating language like ERB, Liquid or Haml, when the attribute value is set from a boolean variable:
<a href="/path" up-follow="<%= is_signed_in %>">Click me</a> <%# mark-phrase "is_signed_in" %>
This can also help when you're generating HTML from a different programming language and want to pass a true literal
as an attribute value:
link_to 'Click me', '/path', 'up-follow': true