up.fragment up.replace(selectorOrElement, url, [options])

JavaScript 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.