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
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.
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
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.
Whether to raise an error if the given selector is missing in either the current page or in the response.
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.
Return value
A promise that will be fulfilled when the page has been updated.