Fragment update API [up-keep] selector

Elements with an up-keep attribute will be persisted during fragment updates.

For example:

<audio up-keep src="song.mp3"></audio>

The element you're keeping should have an umambiguous class name, ID or up-id attribute so Unpoly can find its new position within the page update.

Emits events up:fragment:keep and up:fragment:kept.

Controlling if an element will be kept

Unpoly will only keep an existing element if:

• The existing element has an up-keep attribute
• The response contains an element matching the CSS selector of the existing element
• The matching element also has an up-keep attribute
• The up:fragment:keep event that is emitted on the existing element is not prevented by a event listener.

Let's say we want only keep an <audio> element as long as it plays the same song (as identified by the tag's src attribute).

On the client we can achieve this by listening to an up:keep:fragment event and preventing it if the src attribute of the old and new element differ:

up.compiler('audio', function($element) {
  $element.on('up:fragment:keep', function(event) {
    if $element.attr('src') !== event.$newElement.attr('src') {
      event.preventDefault();
    }
  });
});

If we don't want to solve this on the client, we can achieve the same effect on the server. By setting the value of the up-keep attribute we can define the CSS selector used for matching elements.

<audio up-keep="audio[src='song.mp3']" src="song.mp3"></audio>

Now, if a response no longer contains an <audio src="song.mp3"> tag, the existing element will be destroyed and replaced by a fragment from the response.