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.
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.
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')
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.
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.
Unpoly will emit up:fragment:destroyed
on the element
that was replaced and up:fragment:inserted
on the new
element that replaces it.
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.
The URL to fetch from the server.
The CSS selector to update if the server sends a non-200 status code.
The selector to update when the original target was not found in the page.
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.
The HTTP method to use for the request.
Parameters that should be sent as the request's payload.
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.
Whether to reveal the new fragment.
You can also pass a CSS selector for the element to reveal.
Whether to reveal the new fragment when the server responds with an error.
You can also pass a CSS selector for the element to reveal.
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.
Whether to use a cached response if available.
An object of additional header key/value pairs to send along with the request.
The element that triggered the replacement.
The element's selector will be substituted for the &
shorthand in the target selector (like in Sass).
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.
The name of the layer that ought to be updated if the server sends a non-200 status code.
Whether this replacement will preserve [up-keep]
elements.
Whether this replacement will update [up-hungry]
elements.
A promise that will be fulfilled when the page has been updated.