up.link
[up-defer]
HTML selector
A placeholder for content that is loaded later from another URL.
By moving expensive but non-critical fragments into partials, you can paint critical content earlier.
Example
Identify fragments that are expensive to render on the server, but aren't immediately required. For example, you may have a large navigation menu that only appears once the user clicks a menu icon:
<div id="menu">
Hundreds of links here
</div>
To remove the menu from the initial render pass, extract its contents to its own route, like /menu.
In the initial view, only leave a placeholder element and mark it with an [up-defer] attribute.
Also set an [up-href] attribute with the URL from which to load the deferred content:
<div id="menu" up-defer up-href="/menu"> <!-- mark: up-defer -->
Loading...
</div>
The placeholder content can show a pending state while the full content is loading.
When the [up-defer] placeholder is rendered, it will immediately make a request to fetch
its content from /menu:
GET /path HTTP/1.1
X-Up-Target: #menu
Note
By default the placeholder is targeting itself (
#menu). For this the element must have a derivable target selector.
The server is now expected to respond with a page containing #menu with content:
<div id="menu">
Hundreds of links here
</div>
The element in the response should no longer have an [up-defer] attribute. This would cause infinite reloading.
The server is free to send additional elements or even a full HTML document.
Only #menu will be updated on the page. Other elements from the response will be discarded.
Info
All modifying attributes for
[up-follow]may also be used.
Timing
When to load and render the deferred content.
When set to 'insert' (the default), the deferred content will load immediatedly when
the [up-defer] element is inserted into the DOM.
When set to 'reveal', the deferred content will load when the [up-defer] placeholder is scrolled
into the viewport. If the element is already visible when
inserted, loading will start immediately. Also see loading as the placeholder becomes visible.
When set to 'manual' the deferred content will not load on its own.
You can control the load timing by calling up.deferred.load() from your own JavaScripts.
With [up-defer=reveal], this enlarges the viewport by the given number of pixels before
computing the intersection.
A positive number will load the deferred content some pixels before it becomes visible.
A negative number will require the user to scroll some pixels into the element before it is loaded.
Targeting
A selector for the fragment to render the content in.
By default the [up-defer] element itself will be replaced with the loaded content.
For this the element must have a derivable target selector.
You may target one or multiple fragments.
To target the placeholder itself, you can use :origin target instead of spelling out a selector.
Request
The URL from which to load the deferred content.
If your [up-defer] placeholder is a standard hyperlink, you can use an [href] attribute instead.
A relaxed JSON object with additional request headers.
Whether to load the deferred content in the background.
Background requests will not show the global progress bar.
Caching
Whether to read from and write to the cache.
With [up-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 [up-cache=auto] Unpoly will use the cache only if up.network.config.autoCache
returns true for the request. By default this only caches GET requests.
With [up-cache=false] Unpoly will always make a network request.
Whether to reload the targeted fragment after it was rendered from a cached response.
With [up-revalidate='auto'] Unpoly will revalidate expired responses.
This behavior can be configured with up.fragment.config.autoRevalidate(response).
With [up-revalidate='true'] Unpoly will always revalidate cached content, regardless
of its age.
With [up-revalidate='false'] Unpoly will never revalidate cached content.
The name of a preview that runs while revalidating cached content.
Whether existing cache entries will be expired with this request.
By default a non-GET request will expire the entire cache. You may also pass a URL pattern to only expire matching requests.
Also see up.request({ expireCache }) and up.network.config.expireCache.
Whether existing cache entries will be evicted with this request.
You may also pass a URL pattern to only evict matching requests.
Also see up.request({ evictCache }) and up.network.config.evictCache.