up.fragment
up.render([target], [options])
JavaScript function
Replaces elements on the current page with matching elements from a server response or HTML string.
Choosing which fragment to update
The current and new elements must both match the same target selector.
The selector is either given as { target } option,
or a main target is used as default.
Let's say your current HTML looks like this:
<div class="one">old one</div>
<div class="two">old two</div>
We now replace the second <div> by targeting its CSS class:
up.render({ target: '.two', url: '/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 places it
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.
See targeting fragments for many examples for how you can target content.
Passing the new fragment
The new fragment content can be passed as one of the following options:
| Effect | HTML attribute | JavaScript option |
|---|---|---|
| Fetch a URL and update targeted fragments |
[href] or [action]
|
{ url } |
Update a fragment's inner HTML from a string, <template> or Element
|
[up-content] |
{ content } |
Update a fragment's outer HTML from a string, <template> or Element
|
[up-fragment] |
{ fragment } |
| Update targeted fragments from a larger HTML string | [up-document] |
{ document } |
Update targeted fragments from an existing up.Response object |
– | { response } |
See providing HTML to render for more details and examples.
Enabling side effects
This function has many options to enable scrolling, focus, request cancellation and other side effects. These options are all disabled by default and must be opted into one-by-one.
To enable defaults that a user would expect for navigation (like clicking a link),
pass { navigate: true } or use up.navigate() instead.
Hooking into the render process
Your code may hook into specific stages of the rendering process. This allows you to modify the rendered result or handle error cases.
See render hooks for details.
Concurrency
Unfinished requests targeting the updated fragment or its descendants are aborted.
You may control this behavior using the { abort } option.
Parameters
Targeting
The target selector to update.
Instead of passing the target as the first argument, you may also pass it as
a { target } option. See { target } for details.
The target selector to update after a successful response.
If omitted, a main target will be rendered.
You may also pass a DOM element or jQuery element here, in which case a selector
will be derived.
The given element will also be used as { origin } for the fragment update.
You may also pass an array of selector alternatives. The first selector matching in both old and new content will be used.
The target selector to update when the server responds with an error code.
Specifies behavior if the target selector is missing from the current page or the server response.
If set to a CSS selector string, Unpoly will attempt to replace that selector instead.
If set to true, Unpoly will attempt to replace a main target instead.
If set to false, Unpoly will immediately reject the render promise.
Also see Dealing with missing targets.
Controls which fragment to update when the { target } selector yields multiple results.
When set to 'region', Unpoly will prefer to update fragments in the
region of the origin element.
If set to 'first', Unpoly will always update the first matching fragment.
Defaults to up.fragment.config.match, which defaults to 'region'.
The element that triggered the change.
When multiple elements in the current page match the { target },
Unpoly will replace an element in the origin's proximity.
The origin's selector will be substituted for :origin in a target selector.
Navigation
Whether this fragment update is considered navigation.
Setting this to true will enable many side effects, like
like updating history or scrolling.
Setting this to false will disable most defaults, allowing you to
opt into individual side effects using the options below.
Request
The HTTP method to use for the request.
Common values are 'get', 'post', 'put', 'patch' and 'delete'.
The value is case insensitive.
Additional parameters that should be sent as the request's query string or payload.
When making a GET request to a URL with a query string, the given { params } will be added
to the query parameters.
An object with additional request headers.
Unpoly will by default send a number of custom request headers.
E.g. the X-Up-Target header includes the targeted CSS selector.
See up.protocol for details.
Whether to abort existing requests before rendering.
See aborting requests for details and a list of options.
Whether the request may be aborted by other requests targeting the same fragments or layer.
Whether this request will load in the background.
Background requests deprioritized over foreground requests.
Background requests also won't emit up:network:late events and won't trigger
the progress bar.
The number of milliseconds after which this request can cause
an up:network:late event and show the progress bar.
To prevent the event and progress bar, pass { lateDelay: false }.
Defaults to up.network.config.lateDelay.
The number of milliseconds after which this request fails with a timeout.
Defaults to up.network.config.timeout.
Whether to render failed responses differently.
Failed responses will be rendered using options prefixed with fail, e.g. { failTarget }.
By default any HTTP status code other than 2xx or 304 is considered failed.
Pass { fail: false } to handle any response as successful, even with a 4xx or 5xx status code.
Caching
Whether to read from and write to the cache.
With { cache: true } Unpoly will try to re-use a cached response before connecting
to the network. To prevent display of stale content, cached responses are
reloaded once rendered.
If no cached response exists, Unpoly will make a request and cache
the server response.
With { cache: 'auto' } Unpoly will use the cache only if up.network.config.autoCache
returns true for the request.
With { cache: false } Unpoly will always make a network request.
Whether to reload the targeted fragment after it was rendered from a cached response.
With { revalidate: 'auto' } Unpoly will revalidate expired responses.
This behavior can be configured with up.fragment.config.autoRevalidate(response).
With { revalidate: true } Unpoly will always revalidate cached content, regardless
of its age.
With { revalidate: false } Unpoly will never revalidate cached content.
Whether existing cache entries will be expired with this request.
Expired content remains in the cache, but will be revalidated with the server after rendering.
By default, any non-GET request will expire the entire cache.
This can be configured with up.network.config.expireCache.
To only expire some requests, pass an URL pattern that matches requests to uncache.
You may also pass a function that accepts an existing up.Request and returns a boolean value.
Whether existing cache entries will be evicted with this request.
By default, Unpoly will never evict entries while the cache has
space,
preferring expiration instead.
This can be configured with up.network.config.evictCache.
To only evict some requests, pass an URL pattern that matches requests to uncache.
You may also pass a function that accepts an existing up.Request and returns a boolean value.
Local content
The new inner HTML for the targeted fragment.
See Updating an element's inner HTML from a string.
Instead of passing an HTML string you can also refer to a template.
A string of HTML comprising only the new fragment's outer HTML.
When passing { fragment } you can omit the { target } option.
The target will be derived from the root element in the given HTML.
See Rendering a string that only contains the fragment.
Instead of passing an HTML string you can also refer to a template.
A string of HTML containing the targeted fragment.
See Extracting an element's outer HTML from a larger HTML string.
Instead of passing an HTML string you can also refer to a template.
An up.Response object that contains the targeted fragments in its text.
Layer
The layer in which to match and render the fragment.
See layer option for a list of allowed values.
To open the fragment in a new overlay, pass { layer: 'new' }.
In this case options for up.layer.open() may also be used.