JavaScript Events and Markup Reference

•
3 min read

Reference for the client-side API surface. Accurate as of 2.4.2.

Events

ajaxpress:ready

Dispatched on document once per navigation, after the new page’s title and head metadata have been synced.

document.addEventListener('ajaxpress:ready', (e) => {
  e.detail.url;    // string — the new URL
  e.detail.title;  // string — the new document title
});
  • Fires once per navigation, including browser Back and Forward.
  • Does not fire on pages listed in Exclude Links. Known limitation.
  • Does not fire in wp-admin — the dashboard is never part of the SPA.

Persistence markers

An element matching any of these is preserved across navigation. All available in the free version.

SelectorExample
[data-ajaxpress-persist]<div data-ajaxpress-persist>
.ajaxpress-persist<div class="ajaxpress-persist">
audio[data-persist]<audio data-persist>
video[data-persist]<video data-persist>
[id^="persistent-"]<div id="persistent-radio">

Additional selectors can be supplied through Settings → AjaxPress → Advanced → Media Players (Pro), comma-separated. They are merged with the list above.

Identity resolution

A persistent element needs a stable key so it can be recognised as the same element across pages. Resolved in this order:

  1. data-persist-key attribute — used verbatim
  2. id:<element id>
  3. src:<src> of the first descendant iframe[src], audio[src] or video[src]
  4. src:<src> of the element itself, if it is <audio> or <video>
  5. sig: plus the first 200 characters of outerHTML
<div data-ajaxpress-persist data-persist-key="live-radio">…</div>

Set data-persist-key whenever the id or media src can vary between pages. A stream URL with a cache-busting query parameter produces a different key per page, causing a second player to be preserved alongside the first.

DOM structure

AjaxPress appends a container to <body> and moves preserved elements into it:

<div id="ajaxpress-persist" style="position: fixed; z-index: 1000000; pointer-events: auto;">
  <div data-ajaxpress-lifted data-persist-key="live-radio">
    <!-- the preserved element -->
  </div>
</div>
  • #ajaxpress-persist — the container. position: fixed with no offsets.
  • [data-ajaxpress-lifted] — wrapper added around each preserved element.
  • [data-persist-key] on the wrapper — the resolved identity key.

Use these for CSS targeting after an element has been preserved:

#ajaxpress-persist [data-persist-key="live-radio"] {
  position: fixed;
  bottom: 0; left: 0; right: 0;
}

Lifecycle

  1. First encounter — the live element is moved (not cloned, not rebuilt from HTML) into #ajaxpress-persist. Event listeners, media state and embedded iframes survive.
  2. Subsequent pages — the incoming page’s own copy is removed; the preserved element continues.
  3. Page without the element — the preserved element is removed.

On a cold load the shell document’s own copy is preferred, since scripts that ran in the parent realm bound their listeners to it. Otherwise the element is adopted from the frame document and that frame is retained so the listeners’ realm stays alive.

Known limitations

  • ajaxpress:ready does not fire on excluded pages.
  • No per-element or per-form opt-out from submit interception.
  • Inline visibility: hidden; opacity: 0; pointer-events: none can be applied to a preserved element in some cases.