API Linking to fragments

module up.link

The up.link module lets you build links that update fragments instead of entire pages.

Motivation

In a traditional web application, the entire page is destroyed and re-created when the user follows a link:

This makes for an unfriendly experience:

• State changes caused by AJAX updates get lost during the page transition.
• Unsaved form changes get lost during the page transition.
• The JavaScript VM is reset during the page transition.
• If the page layout is composed from multiple scrollable containers (e.g. a pane view), the scroll positions get lost during the page transition.
• The user sees a "flash" as the browser loads and renders the new page, even if large portions of the old and new page are the same (navigation, layout, etc.).

Unpoly fixes this by letting you annotate links with an [up-target] attribute. The value of this attribute is a CSS selector that indicates which page fragment to update. The server still renders full HTML pages, but we only use the targeted fragments and discard the rest:

With this model, following links feels smooth. All DOM state outside the updated fragment is preserved. Pages also load much faster since the DOM, CSS and JavaScript environments do not need to be destroyed and recreated for every request.

Example

Let's say we are rendering three pages with a tabbed navigation to switch between screens:

Your HTML could look like this:

<nav>
  <a href="/pages/a">A</a>
  <a href="/pages/b">B</a>
  <a href="/pages/b">C</a>
</nav>

<article>
  Page A
</article>

Since we only want to update the <article> tag, we annotate the links with an up-target attribute:

<nav>
  <a href="/pages/a" up-target="article">A</a>
  <a href="/pages/b" up-target="article">B</a>
  <a href="/pages/b" up-target="article">C</a>
</nav>

Note

Instead of article you can use any other CSS selector like #main .article.

With these [up-target] annotations Unpoly only updates the targeted part of the screen. The JavaScript environment will persist and the user will not see a white flash while the new page is loading.