Learn Attributes and options

Most of Unpoly's features share one shape: the common case is an HTML attribute, the same feature is also available as a JavaScript function, and its defaults can be changed through a global configuration.

This page covers the pattern in detail: how attributes and their modifiers are parsed, which values they accept, and how JavaScript options and configured defaults override them.

One option, three places

You can set most options in three places: a configuration default for your entire app, an attribute on one element, or an option in one JavaScript call. When more than one place sets the same option, the most specific one wins.

Let's say your app animates every navigation with a cross-fade:

up.fragment.config.navigateOptions.transition = 'cross-fade'

One link prefers to slide in from the right. Its attribute overrides the default for this link only:

<a href="/next" up-follow up-transition="move-left">Next page</a> <!-- mark: up-transition="move-left" -->

When your own script follows that link, it can override the attribute again. Here the script skips the animation altogether:

up.follow(link, { transition: 'none' }) // mark: transition: 'none'

When Unpoly navigates, it starts with the configured defaults, then applies the attributes it parsed from the element, and finally the options you passed. Each place only replaces the values it actually sets, so the script above still gets the link's URL and every other attribute.

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 page's main fragment instead of replacing the full page:

<a href="/path" up-follow>Click me</a> <!-- mark: up-follow -->

Modifying attributes

Most Unpoly attributes have modifying attributes to fine-tune their behavior. For example, the [up-confirm] attribute makes an [up-follow] link show a confirmation dialog before it is followed:

<a href="/users/5/delete" up-follow up-confirm="Really delete this user?">Delete user</a> <!-- mark: up-confirm -->

Modifying attributes are documented with the main attribute they're modifying. For example, see modifying attributes for [up-follow].

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: true -->
<a href="/path" up-follow="false">Click for full page load</a> <!-- mark: false -->

Instead of setting a true value 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: 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 # mark: true

The examples use Ruby on Rails, but work similarly with any other backend.

Structured values

A few attributes take a structured value, like an object or an array. These values are written in relaxed JSON, which allows single quotes and unquoted keys:

<a href="/path" up-follow up-headers="{ 'X-Requested-From': 'sidebar' }">Click me</a> <!-- mark: up-headers -->

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 })

Changing defaults globally

Most modules have an up.*.config property that adjusts their behavior for your entire application. For example, this makes every new overlay open as a drawer instead of a modal:

up.layer.config.mode = 'drawer'

A configured value becomes the new default. Elements and function calls can still override it with their own attributes and options.

Many config properties hold a list of CSS selectors, letting you apply a behavior to all matching elements. For example, you can tell Unpoly to handle every link on the page without any [up-follow] attributes.

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: up-cache="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) {
  return defaultAutoCache(request) && !request.url.endsWith('/edit')
}