Fragment update API `up.replace(selectorOrElement, url, [options])` function

Replaces elements on the current page with corresponding elements from a new page fetched from the server.

The current and new elements must both match the given CSS selector.

The unobtrusive variant of this is the a[up-target] selector.

Example

Let's say your curent HTML looks like this:

<div class="one">old one</div>
<div class="two">old two</div>

We now replace the second <div>:

up.replace('.two', '/new');

The server renders a response for /new:

<div class="one">new one</div>
<div class="two">new two</div>

Unpoly looks for the selector .two in the response and implants it into the current page. The current page now looks like this:

<div class="one">old one</div>
<div class="two">new two</div>

Note how only .two has changed. The update for .one was discarded, since it didn't match the selector.

Appending or prepending instead of replacing

By default Unpoly will replace the given selector with the same selector from a freshly fetched page. Instead of replacing you can append the loaded content to the existing content by using the :after pseudo selector. In the same fashion, you can use :before to indicate that you would like the prepend the loaded content.

A practical example would be a paginated list of items:

<ul class="tasks">
  <li>Wash car</li>
  <li>Purchase supplies</li>
  <li>Fix tent</li>
</ul>

In order to append more items from a URL, replace into the .tasks:after selector:

up.replace('.tasks:after', '/page/2')

Setting the window title from the server

If the replace call changes history, the document title will be set to the contents of a <title> tag in the response.

The server can also change the document title by setting an X-Up-Title header in the response.

Optimizing response rendering

The server is free to optimize Unpoly requests by only rendering the HTML fragment that is being updated. The request's X-Up-Target header will contain the CSS selector for the updating fragment.

If you are using the unpoly-rails gem you can also access the selector via up.target in all controllers, views and helpers.

Events

Unpoly will emit up:fragment:destroyed on the element that was replaced and up:fragment:inserted on the new element that replaces it.

Parameters

selectorOrElement String or Element or jQuery

The CSS selector to update. You can also pass a DOM element or jQuery element here, in which case a selector will be inferred from the element's class and ID.

url String

The URL to fetch from the server.

[options.failTarget='body'] String optional

The CSS selector to update if the server sends a non-200 status code.

[options.fallback] String optional

The selector to update when the original target was not found in the page.

[options.title] String optional

The document title after the replacement.

If the call pushes an history entry and this option is missing, the title is extracted from the response's <title> tag. You can also pass false to explicitly prevent the title from being updated.

[options.method='get'] String optional

The HTTP method to use for the request.

[options.data] Object or Array optional

Parameters that should be sent as the request's payload.

Parameters can either be passed as an object (where the property names become the param names and the property values become the param values) or as an array of { name: 'param-name', value: 'param-value' } objects (compare to jQuery's serializeArray).

[options.transition='none'] String optional

[options.history=true] String or Boolean optional

If a String is given, it is used as the URL the browser's location bar and history. If omitted or true, the url argument will be used. If set to false, the history will remain unchanged.

[options.source=true] String or Boolean optional

[options.reveal=false] String optional

Whether to reveal the element being updated, by scrolling its containing viewport.

[options.restoreScroll=false] Boolean optional

If set to true, Unpoly will try to restore the scroll position of all the viewports around or below the updated element. The position will be reset to the last known top position before a previous history change for the current URL.

[options.cache] Boolean optional

Whether to use a cached response if available.

[options.historyMethod='push'] String optional

[options.headers={}] Object optional

An object of additional header key/value pairs to send along with the request.

[options.requireMatch=true] Boolean optional

Whether to raise an error if the given selector is missing in either the current page or in the response.

[options.origin] Element or jQuery optional

The element that triggered the replacement.

The element's selector will be substituted for the & shorthand in the target selector.

[options.layer='auto'] String optional

The name of the layer that ought to be updated. Valid values are auto, page, modal and popup.

If set to auto (default), Unpoly will try to find a match in the same layer as the element that triggered the replacement (see options.origin). If that element is not known, or no match was found in that layer, Unpoly will search in other layers, starting from the topmost layer.

Return value

Promise

A promise that will be resolved when the page has been updated.

Fragment update API up.replace(selectorOrElement, url, [options]) function