How forms are loaded

How the script finds the forms of a page, loads them in one request, and picks up forms added later.

The script does not carry the definition of the forms: it only knows which forms are linked to the website — their identifier and, when the client set one, their CSS selector. It loads the forms it actually finds in the page, already translated, in one request. A page without a form loads none.

1. Finding the forms of the page

Once the page is ready, the script looks for, in the order of the page:

the elements carrying data-rikochey-form="…" — and the older attributes still recognized;
the elements matching the CSS selector set by the client on a form's link to the website, when no tag already carries that form.

For each form found, it keeps the identifier and the requested language: the tag's data-rikochey-lang attribute, otherwise the page's <html lang> — see Languages.

2. One request for all of them

The script then asks for the forms found, in a single request — see Load the forms of a page:

GET /api/websites/{website}/forms/config?f=contact~fr,quote~en

Before sending it, the script normalizes the list: each language is reduced to its base language in lowercase (en-GB → en), entries are deduplicated and sorted. Every page showing the same forms thus sends the same request, and shares the same cached response. Beyond 20 forms, the list is split into several requests of 20, sent in parallel.

The server picks the language of each form and returns it already translated: the browser never receives the other languages.

3. Rendering

As each form arrives, the script renders it or attaches to it — see Automatic rendering or attached mode — and adds it to window.FORMS. It then dispatches a rikochey:forms-loaded event on document:

document.addEventListener('rikochey:forms-loaded', function (event) {
    console.log(event.detail.forms); // the forms just loaded
});

A form the server does not return — disabled, or not linked to this website — is not rendered. If the request fails, the script tries once more two seconds later, then gives up silently: a warning in the browser console, nothing in the page.

Loading placeholder

While a form loads, an empty tag in automatic rendering shows an animated placeholder form: a few field outlines and a button, so the page keeps its space and does not jump when the form arrives. It appears after 150 ms only, so a form served from the cache shows up without any flash, and the real form then fades in.

It is announced to screen readers ("Loading the form…", in the requested language).
It follows your --rk-form-radius, --rk-form-gap and --rk-form-accent variables, and stays still for visitors who ask for reduced motion.
A tag that already has content — your own fallback text, for instance — keeps it instead, until the form replaces it. Attached forms and CSS-selector bindings never get a placeholder.

To restyle or hide it, target its classes:

.rikochey-skeleton { max-width: 480px; }       /* the whole placeholder */
.rikochey-skeleton-bar { border-radius: 0; }   /* each outline */
.rikochey-skeleton { display: none; }          /* no placeholder at all */

Forms added later

Modal windows, single-page applications, content loaded on scroll: a form tag added to the page after it has loaded is picked up too, for the whole life of the page, even minutes later.

The script watches the elements added to the page, and only those.
Additions close together are grouped: a batch is processed 50 ms after the last addition, and at the latest 250 ms after the first one.
A batch sends one request, for the forms not already loaded; a form already loaded is reused without any request.
An element already handled is never handled twice, even if it is removed from the page and inserted again.

Nothing is needed on your side: add the usual tag, the form appears.

Attached mode before the form has loaded

In attached mode, the script takes charge of your <form> as soon as it finds it, before its configuration has arrived. A visitor who submits in the meantime does not lose anything: the button shows the sending state, the submission waits for the configuration, then goes through as usual.

If the form cannot be loaded — disabled, not linked to the website, or network failure — the script lets go of your form: a pending submission is then sent by the browser as your HTML defines it, as if the script were not there.

Caching

The response is public and cached for 5 minutes, by the browser and the network edge, then revalidated. A change made to a form in the panel — a label, a translation, its appearance — therefore reaches visitors within 5 minutes. The script itself is cached for an hour, but does not change when a form's content changes.

Missing forms

Thirty seconds after the page has loaded, the script reports once the forms linked to the website that it never found in the page, and those found but refused by the server. The client sees them in their panel, on the link between the form and the website. The watching of the page goes on afterwards.