HTMX: poll region

Plugin ID: eca_htmx_poll

Available since: 3.1.3

Build a region that periodically polls a URL via HTMX and swaps in the returned markup. The polled fragment can be served by an ECA endpoint (see the ECA Endpoint module).

Only main content

The only main content option is enabled by default. When enabled, the polled URL is requested with the Drupal "only main content" hint, so the response is the minimal HTMX render (the main content wrapped in a bare HTML document) rather than a full themed page. Disable it only if the polled URL already returns a fragment by other means.

A natural source for the polled fragment is an ECA endpoint. See Building HTMX-powered interfaces with ECA.

Fields

Poll URL — config key: url

The URL that HTMX requests on every poll. The response markup replaces the polled region. An ECA endpoint can serve this fragment.
This field supports tokens.

Type: textfield · Required: yes · Default: empty string

Poll interval (seconds) — config key: interval

The number of seconds between two polls.
This field supports tokens.

Type: textfield · Required: yes · Default: 10

Swap strategy — config key: swap

The HTMX swap strategy, for example innerHTML, outerHTML or beforeend.
This field supports tokens.

Type: textfield · Required: yes · Default: innerHTML

Swap target — config key: target

Optional CSS selector identifying the element that receives the swapped content. When left empty, the polling region itself is the target.
This field supports tokens.

Type: textfield · Required: no · Default: empty string

The selector has to match an element that already exists on the page. This action gives the element it builds neither an id nor a class, so one HTMX element cannot address another one by selector.

Initial content — config key: content

The markup shown inside the region before the first poll completes.
This field supports tokens.

Type: textarea · Required: no · Default: empty string

Wrapper tag — config key: wrapper_tag

The HTML tag of the polling region, for example div or span.
When using the "Defined by token" option, make sure there is a token with this name: eca_htmx_poll_wrapper_tag

Type: select · Required: yes · Default: div

Allowed values: div, span, section, article, aside, nav, p, button, a, ul, ol, li, details, _eca_token

button submits the form it sits in

The element is built as a plain HTML tag and receives no type attribute, and HTML treats a <button> without type as type="submit". Inside a form, for example under a Build form event, clicking it submits the form instead of issuing the HTMX request. Use a or span instead.

Request only the main content — config key: htmx_only

When enabled, the polled URL is requested with the Drupal "only main content" hint, so the response is the minimal HTMX render rather than a full HTML page.

Type: checkbox · Required: no · Default: true

Machine name — config key: name

Optionally define a machine name of this render element. It will be made available under that name in the render array of the current event in scope. Nested elements can be set with using "][" brackets, for example details][title.
This field supports tokens.

Type: textfield · Required: no · Default: empty string

The machine name is a key in the render array of the event in scope. ECA's form events expose the form array itself as their render array, so under a Build form or Process form event this name is a form element key, and ][ nesting addresses nested form elements. See rendering HTMX elements into a form for what that makes possible.

Leaving the name empty is the usual choice for a standalone element. It is unsafe only together with the Build mode value Set and clear any previous value, which then replaces the whole render array instead of adding to it. See the note on the Build mode field.

Token name — config key: token_name

Optionally define a token name of this render element. It will be made available under that token name for later usage. Please provide the token name only, without brackets.

Type: textfield · Required: no · Default: empty string

Element weight — config key: weight

Optionally specify an element weight. The lower the weight, the element appears before other elements having a higher weight.
This field supports tokens.

Type: textfield · Required: no · Default: empty string

Build mode — config key: mode

When using the "Defined by token" option, make sure there is a token with this name: eca_htmx_poll_mode

Type: select · Required: yes · Default: append

Allowed values: set:clear, set:clear:defined, merge, prepend, append, nothing, _eca_token

An empty machine name clears the whole render array

With this field set to Set and clear any previous value and no Machine name, the action adds nothing: it replaces the entire render array of the event in scope with the element it just built. Under a Build form event, whose render array is the form itself, that discards the whole form.

Use Set value when machine name is defined above whenever the name comes from a token that might resolve to nothing. That mode leaves the target untouched while the name is empty.