Now.js Framework Documentation

Now.js Framework Documentation

data-on-load

EN 11 Feb 2026 07:47

data-on-load

Overview

data-on-load calls a global function after API-driven content is ready (similar concept to data-script, but different lifecycle). It runs on the element that declares the attribute and is intended ONLY for initialization that should happen after an API payload has been loaded and inserted into the DOM. Typical callers are ApiComponent (when API data is rendered), FormManager (when form data is loaded, often via API), and TableManager (when a table's API data has been fetched and rendered). Do not use data-on-load as a page navigation hook.

The function receives a normalized data payload (not the full TemplateManager context): TemplateManager will pass context.state?.data ?? context.data ?? context as the second argument.

Use it to:

  • Run per-section initialization after an API or form payload has been inserted into a container
  • Attach behavior that depends on the loaded data (e.g., populate maps, charts, third-party widgets)
  • Use the signature (element, data) where data is the loaded payload provided by ApiComponent, FormManager, or TableManager

Basic Usage

<main>
  <section data-on-load="initFormLoad">
    <h2 data-text="data.title"></h2>
  </section>
</main>
function initFormLoad(element, data) {
  // element: DOM element with data-on-load
  // data: normalized payload from ApiComponent or FormManager
  console.log('Init section', element, data);

  // Optional cleanup
  return () => {
    console.log('Cleanup section');
  };
}

How it runs

  • ApiComponent: After rendering API data (or serving from cache), ApiComponent will run all [data-on-load] inside the component using the render context (the normalized payload is passed as the second argument).
  • FormManager: When a form's data is loaded (for example via an API) and rendered into the form container, FormManager will run [data-on-load] for elements inside the form using the normalized payload.
  • TableManager: When a table loads data from an API (server-side/source starts with api/ or http) and renders its rows, TableManager will invoke [data-on-load] only on the table element itself (not on every cell/row) once after the render completes. The payload passed is the table data (normalized) so handlers can initialize widgets tied to the table as a whole.

Note: TemplateManager/process lifecycle changed slightly in later framework versions — data-on-load is primarily intended for API-driven payloads, but FormManager will also invoke data-on-load after form initialization when there is no explicit data-load-api (for example when a form is inserted into a modal via the ResponseHandler). In that case FormManager passes a normalized payload (it prefers window._currentModalData when available, otherwise the current form values) so handlers can initialize behavior for modal or pre-rendered forms.

To avoid duplicate invocations, FormManager sets an internal flag when it has invoked data-on-load for a given form instance. If the form later receives an API payload (via data-load-api), the API-driven invocation will still run but duplicate calls are prevented by the FormManager flag.

Note: data-on-load is for API-driven loads only. For page-level initialization triggered by navigation, use data-script (RouterManager invokes data-script during navigation). The two hooks are separate and should not be interchanged.

Body-level usage (AppConfigManager)

When data-on-load is placed on the page <body> (for example to run logic after a combined config load), AppConfigManager executes that attribute and the function signature differs from the per-element handlers:

  • Normal per-element usage: handlers are called as window[fn](element, data) — signature (element, data) as described above.
  • Body-level usage (AppConfigManager): the attribute is compiled to a function and invoked as fn(site, theme, config) — where site is the site metadata object, theme is the current theme string, and config is the full config object containing site, theme and applied variables.

Example:

<body data-on-load="document.title = site.title; initHeader(site, theme, config)">
  <!-- available: site, theme, config -->
</body>

See the AppConfigManager documentation (docs/en/AppConfigManager.md) for more details and examples of using body-level data-on-load.

Function Signature

function initFn(element, data) {
  // element: HTMLElement with data-on-load
  // data: normalized payload (from ApiComponent or FormManager)
  // return optional cleanup function
}
Parameter Type Description
element HTMLElement Element bearing data-on-load
data Object Data/context passed from ApiComponent or FormManager (normalized payload)
Return Effect
undefined No cleanup
Function Called on cleanup (component/form teardown)

Tips

  • Prefer data-on-load for multiple independent areas; keep data-script for single entry-point logic.
  • Keep functions idempotent—reruns can happen after re-render.
  • Use returned cleanup to remove listeners/timers.

Did you spot an improvement?

Enhance the documentation by contributing updates or translations.

Visit project repository