Replaces the given element with a fresh copy fetched from the server.
By default, reloading is not considered a user navigation and will not scroll, focus
or update the browser location. You may change this with { navigate: true }
.
let { fragment } = await up.reload('.inbox')
console.log("New .inbox element: ", fragment)
Unpoly remembers the URL from which a fragment was loaded, so you don't usually need to pass a URL when reloading.
To reload from another URL, pass a { url }
option or set an [up-source]
attribute
on the element being reloaded or its ancestors.
Your server-side app is not required to re-render a request if there are no changes to the cached content.
By supporting conditional HTTP requests you can quickly produce an empty response for unchanged content.
To instantly restore a fragment to the last cached version, pass a { cache: true }
option:
up.reload('.inbox', { cache: true }) // mark: cache
If the fragment source isn't cached, a network request is made.
To restore a fragment from cache, but revalidate cached content that
has expired, also pass a { revalidate: 'auto' }
option:
up.reload('.inbox', { cache: true, revalidate: 'auto' }) // mark: revalidate
Additional render options to use when reloading the fragment.
Common options are documented below, but most options for up.render()
may be used.
The URL from which to reload the fragment.
Defaults to the URL from which the fragment was originally loaded.
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.
Whether to restore a fragment from its cached state.
By default the cache is ignored and a new HTTP request is sent.
You can pass { cache: 'auto' }
to restore a fragment to its previously cached state.
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.
A placeholder to show within the targeted fragment while new content is loading.
Existing children of the targeted fragment will be hidden during the request. When the request ends for any reason, all changes will be reverted.
One or more previews that temporarily change the page while new content is loading.
The preview changes will be reverted automatically when the request ends for any reason.
Whether to preserve the fragment's data object throughout the update.
Properties from the new fragment's [up-data]
are overridden with the old fragment's [up-data]
.
The data object object for the new fragment.
If the new fragment already has an [up-data]
object, this option will override
individual properties from that attribute.
A message the user needs to confirm before any request or changes are made.
The message will be shown as a native browser prompt.
If the user does not confirm, no request is sent and no fragments are updated.
In that case the render promise rejects with an up.AbortError
.
A callback that will be run when the server responds with new HTML, but before the HTML is rendered.
The callback argument is a preventable up:fragment:loaded
event.
This callback will also run for failed responses.
A callback that will be run when the fragment could not be loaded due to a disconnect or timeout.
The callback argument is a preventable up:fragment:offline
event.
A function to call when Unpoly has updated fragments.
This callback may be called zero, one or two times:
{ onRendered }
is not called.{ onRendered }
is called with the result.{ onRendered }
is called again with the final result.Also see Running code after rendering.
A function to call when no further DOM changes will be caused by this render pass.
In particular:
The callback argument is the last up.RenderResult
that updated a fragment.
If revalidation re-rendered the fragment, it is the result from the
second render pass. If no revalidation was performed, or if revalidation yielded an empty response,
it is the result from the initial render pass.
Also see Awaiting postprocessing.
A callback that will be run when any error is thrown during the rendering process.
The callback is also called when the render pass fails due to network issues, or aborts.
Also see Handling errors.
A promise that fulfills with an up.RenderResult
once the page has been updated.
The promise rejects when one of the following conditions occur:
See Render lifecycle hooks for more information about handling errors, or running code after rendering.