Regions that load when seen: the ypy-lazy extension
A dashboard, a long page or a table with "show more" rows holds content that most visitors never scroll to.
ypy-lazy leaves a placeholder in the page and asks the server for the real content only when the placeholder is
about to come into view.
<script src="ypy.min.js"></script>
<script src="ext/ypy-lazy.min.js"></script>
<section ypy-lazy="/reports/summary" class="min-h-32 animate-pulse rounded bg-slate-100 p-4">
<a href="/reports/summary" class="underline">Open the summary</a>
</section>When the section is within 200 px of the window, YPY sends GET /reports/summary and the response replaces the
element. It is requested once.
The extension is part of ypy.max.
It is an attribute, never a Custom Element, so it works on <tr>, <tbody>, <li> and <dd>, where a Custom
Element is not allowed:
<table>
<tbody>
<tr ypy-lazy="/orders?page=2"><td colspan="3"><a href="/orders?page=2">Show more orders</a></td></tr>
</tbody>
</table>The server answers with <tr> rows and they replace the placeholder row.
Attributes
| Attribute | Value | Meaning |
|---|---|---|
ypy-lazy |
a URL | the GET made when the element is about to be seen (data-ypy-lazy also works) |
ypy-lazy-placeholder |
a selector | a <template> (or element) whose content replaces the children as soon as the element is processed |
ypy-lazy-error |
a selector | a <template> (or element) whose content replaces the children when the load fails |
ypy-lazy-retry |
none | on an element inside a failed region: loads the region again when clicked |
ypy-lazy-group |
a name | regions of the same group that come into view together share one request (see below) |
ypy-lazy-group-url |
a URL | the URL of the group request, on any region of the group |
The URL must be on the page's origin, like every YPY request. The other request attributes of the element work as on
ypy-get: ypy-swap, ypy-target, ypy-select. With ypy-swap="innerHTML" the element stays and is filled.
The element needs a box to be seen. An <option>, or anything with display: none or display: contents, never loads.
A region inside ypy-ignore is not started, and ypy:before:init fires on it before it starts, so a gate such as the
nonce extension can stop it.
Placeholder
The content of the element is the placeholder. It is also what a visitor without JavaScript sees, so put a link there.
While the request runs the core sets the ypy-request class, data-ypy-state="request" and aria-busy="true".
For a skeleton that only visitors with JavaScript get, point ypy-lazy-placeholder at a <template>:
<template id="skeleton"><div class="h-24 animate-pulse rounded bg-slate-200"></div></template>
<div ypy-lazy="/panel" ypy-lazy-placeholder="#skeleton"><a href="/panel">Open the panel</a></div>Errors
If the request fails (no connection, a status of 400 or more, a swap error), the element gets
data-ypy-state="error" and ypy:lazy:error fires on it. The body of an error response is not swapped in; it
would replace the placeholder with an error page. ypy-error-swap="outerHTML" on the element asks for it.
<template id="failed">
<p class="text-red-700">The summary did not load.</p>
<button ypy-lazy-retry class="underline">Try again</button>
</template>
<div ypy-lazy="/reports/summary" ypy-lazy-error="#failed">Loading...</div>A click on an ypy-lazy-retry element loads the region again, and only while the region is in the error state; the
state is cleared when the new request starts.
Groups: one request for several regions
A page with six report cards would send six requests as the visitor scrolls. Give the regions one ypy-lazy-group and
an id each:
<div id="sales" ypy-lazy="/reports" ypy-lazy-group="reports" class="h-40">Sales...</div>
<div id="visits" ypy-lazy="/reports" ypy-lazy-group="reports" class="h-40">Visits...</div>Regions of one group that enter the view within lazy.window (50 ms by default) are loaded with one GET:
GET /reports?group=reports&id=sales&id=visits HTTP/1.1
YPY-Request: true
YPY-Lazy-Group: reports-
The URL is the
ypy-lazy-group-urlof the first region that has one, or else theypy-lazyof the first region of the batch.groupand oneidper region (in the order they came into view) are added to its query string. -
The server answers with one
<ypy-partial id="...">perid. A partial with noypy-swapreplaces its region, the way an individual region would be replaced (with the region's ownypy-swap,outerHTMLby default). A partial can name its ownypy-swap. -
A region the answer leaves out is an error, as if it had failed alone:
data-ypy-state="error"andypy:lazy:error. If the whole request fails, every region of the group is marked. -
A region without an
id, and a region alone in its window, loads on its own with its ownypy-lazyURL. The individual mode needs nothing from the server, so the group is an optimization you can add later. - Groups are kept apart by name: two groups in view together make two requests.
HTTP/1.1 200 OK
Content-Type: text/html
<ypy-partial id="sales"><section id="sales" class="p-4">Sales: 1,204</section></ypy-partial>
<ypy-partial id="visits"><section id="visits" class="p-4">Visits: 8,310</section></ypy-partial>The server answers a group with one <ypy-partial> per id it received. A partial with only an id targets #id, which is the region. Write the id on the card you send back too, so a
later group can find it.
Events
| Event | On | Detail |
|---|---|---|
ypy:lazy:error |
the failed region | ctx (the request, when there was one), error |
ypy:lazy:group |
the first region of the batch, just before the request | group, ids, url |
Neither is cancelable. The normal request events (ypy:before:request, ypy:after:swap...) fire on the first
region for a group request.
Configuration
| Key | Default | Meaning |
|---|---|---|
lazy.margin |
"200px" |
how far outside the window a region is loaded, a CSS margin |
lazy.window |
50 |
how long a group waits for the other regions, in milliseconds or a time ("50ms") |
<meta name="ypy-config" content='{"lazy": {"margin": "400px", "window": 100}}'>Pitfalls
- A grouped region needs an
id. Without one it silently loads on its own. -
The answer to a group request is read as partials. A plain fragment with no
<ypy-partial>leaves every region in the error state. -
lazy.windowstarts when the first region of the group is seen. A region that comes into view after the window has closed belongs to the next request. -
Give the placeholder a height (
min-h-*). Placeholders that collapse to nothing sit close together, so many of them come into view at once and all of them load. - Without
IntersectionObserverthe region loads as soon as it is processed. - A lazy region is a normal
GET. Do not use it for an action that changes state.
The tests are in test/tests/ext/ypy-lazy.js.