AjaxSlim element reference

Element reference14 elements, rendered from the libraries' .apiext files

Every element in the AjaxSlim library: what it does and its full set of bindings. For migration notes and the bigger picture, see the guide.

Container usually wraps content · Passthrough forwards attributes it doesn't handle (class, data-*, …) onto the rendered tag · ● required · ↓ pulled, ↑ pushed back, ↕ two-way. Full presentation, with the rest of the playground, on the playground.

AjaxUpdateContainer

Update Container Passthrough

A region of the page that can be refreshed independently via an Ajax request, morphing the freshly-rendered HTML into the live DOM (preserving focus, scroll, selection and unchanged subtrees) instead of replacing its innerHTML.

Passive: it is refreshed by other elements that name it in updateContainerID; it has no action and no self-refresh of its own. Binding any of the self-updating bindings (action, frequency, observeFieldID, stopped, fullSubmit) is rejected with an error — despite the passthrough policy, they are never forwarded as attributes; use AjaxSelfUpdatingContainer.

<wo:AjaxUpdateContainer id="detail"> ...content... </wo:AjaxUpdateContainer>
<!-- refresh it from elsewhere: -->
<wo:AjaxUpdateLink action="$reload" updateContainerID="detail">Reload</wo:AjaxUpdateLink>

Binding	Type	Description
id	↓ String	The DOM id of the container (defaults to a safe generated element id). This is the id other elements target.
elementName	↓ String	The HTML tag to render. default `div`
morph	↓ Boolean	When true, content updates reconcile the existing DOM via Idiomorph — preserving focus/scroll/selection and unchanged subtrees. Bind `morph="$false"` to force classic `innerHTML` replacement. default `true`
onRefreshComplete	↓ String	JavaScript to run after the container has been refreshed/morphed.
optional	↓ Boolean	Set true to skip rendering the container tags when this element is already inside another update container (renders only its children).

AjaxSelfUpdatingContainer

Update Container Passthrough

An update container that refreshes itself — on a timer (frequency) and/or when a field changes (observeFieldID) — and may invoke its own action when it does. The counterpart to the passive AjaxUpdateContainer; it also inherits all of that element's bindings (id, elementName, morph, onRefreshComplete, optional) and the same attribute passthrough (class, style, data-*, …).

<wo:AjaxSelfUpdatingContainer id="clock" frequency="5" action="$tick">
  Server time: <wo:str value="$now"/>
</wo:AjaxSelfUpdatingContainer>

Binding	Type	Description
frequency	↓ Number	The frequency, in seconds, of a periodic self-refresh.
stopped	↓ Boolean	Whether a periodic container loads stopped (so it can be started later by refreshing it).
observeFieldID	↓ String	The DOM id of a field whose changes trigger a self-refresh of this container.
fullSubmit	↓ Boolean	When observing a field, whether to submit the whole form (true) or just the field (false).
action	↓ WOActionResults	The action to invoke on the periodic self-refresh. It does not fire on an `observeFieldID`-triggered refresh — that path submits the observed field's form, and the container is only the render target.
id	↓ String	The DOM id of the container (defaults to a safe generated element id). This is the id other elements target.
elementName	↓ String	The HTML tag to render. default `div`
morph	↓ Boolean	When true, content updates reconcile the existing DOM via Idiomorph — preserving focus/scroll/selection and unchanged subtrees. Bind `morph="$false"` to force classic `innerHTML` replacement. default `true`
onRefreshComplete	↓ String	JavaScript to run after the container has been refreshed/morphed.
optional	↓ Boolean	Set true to skip rendering the container tags when this element is already inside another update container (renders only its children).

AjaxUpdateLink

Update Passthrough

A link (or button, or named JS function) that fires a server action and morphs the result into a target container (updateContainerID) or replaces a region (replaceID). The standard "click to update part of the page".

updateContainerID may name several containers separated by ; to refresh them all in one round-trip.

<wo:AjaxUpdateLink action="$edit" updateContainerID="detail" string="Edit"/>
<wo:AjaxUpdateLink action="$bumpAll" updateContainerID="boxA;boxB;boxC">Bump all</wo:AjaxUpdateLink>

Binding	Type	Description
action	↓ WOActionResults	The action to call when the link executes.
directActionName	↓ String	The direct action to call when the link executes (requires `replaceID`).
updateContainerID	↓ String \| List	The update container(s) to morph after the action — a single id, a `;`-separated set, or a `List` of ids. `"_parent"` targets the nearest enclosing container.
replaceID	↓ String	The id of the element whose contents are replaced with the action's result.
string	↓ String	String prepended to the contained elements (the link text).
onClick	↓ String	JavaScript to run on the client after the request is sent (the fetch is asynchronous, so before the response arrives — use `onSuccess`/`onComplete` for after-the-morph hooks).
onClickBefore	↓ String	If this expression is false, the click is ignored (e.g. `confirm(...)`).
onClickServer	↓ String	JS returned from the server after the action when there is no update.
onSuccess	↓ String	JavaScript to run after a successful update/morph (before `onComplete`).
onComplete	↓ String	JavaScript to run after the update/morph completes.
ignoreActionResponse	↓ Boolean	If true, the action's response is thrown away.
function	↓ String	A custom JS function to call, passed the action url.
functionName	↓ String	If set, the link becomes a named JavaScript function instead of an element.
elementName	↓ String	The element name to use. default `a`
button	↓ Boolean	If true, renders an `<input type="button">`.
disabled	↓ Boolean	If true, the link tag is not rendered.
title	↓ String	The HTML title attribute, passed through to the rendered tag.
class	↓ String	The HTML class attribute, passed through to the rendered tag.
style	↓ String	The HTML style attribute, passed through to the rendered tag.
id	↓ String	The HTML id attribute, passed through to the rendered tag.
accesskey	↓ String	The HTML accesskey attribute, passed through to the rendered tag.

At least one of 'action', 'directActionName' and 'updateContainerID' must be bound.

At most one of 'action' and 'directActionName' may be bound.

At most one of 'updateContainerID', 'replaceID' and 'ignoreActionResponse' may be bound.

'replaceID' must be bound when 'directActionName' is bound.

At most one of 'directActionName' and 'ignoreActionResponse' may be bound.

AjaxSubmitButton

Update Passthrough

Like a WOSubmitButton, but submits its form in the background via Ajax and morphs the result into a target container (updateContainerID) or replaces a region (replaceID). Honours the AJAX_SUBMIT_BUTTON_NAME partial-submit contract, so it works correctly in multiple-submit forms.

<wo:AjaxSubmitButton action="$save" updateContainerID="result" value="Save"/>

Binding	Type	Description
action	↓ WOActionResults	The action to execute when the button is pressed.
updateContainerID	↓ String \| List	The update container(s) to morph after submitting — a single id, a `;`-separated set, or a `List` of ids. `"_parent"` targets the nearest enclosing container.
replaceID	↓ String	The id of the region to replace (mutually exclusive with `updateContainerID`).
value	↓ String	The button text.
name	↓ String	The HTML name of the button.
button	↓ Boolean	If false, renders a link instead of a button (default true).
useButtonTag	↓ Boolean	Render a `<button>` instead of `<input type="button">`.
formName	↓ String	The name of the form to submit (defaults to the containing form).
functionName	↓ String	If set, exposes the submit as a named JS function (the UI then defaults to hidden).
showUI	↓ Boolean	When `functionName` is set (which hides the UI by default), set true to render the button anyway.
onClick	↓ String	Client hook run after the request is sent.
onClickBefore	↓ String	Gate evaluated before the request; if it is false the click is ignored.
onClickServer	↓ String	Server-returned JS used when the action returns null.
onSuccess	↓ String	Post-update hook (run after a successful morph).
onComplete	↓ String	Post-update hook (run after the morph).
disabled	↓ Boolean	Renders the `disabled` attribute.
ignoreActionResponse	↓ Boolean	If true, the action's result is ignored and an empty (or `onClickServer`) response is returned instead.
id	↓ String	The HTML id attribute on the rendered element.
elementName	↓ String	The element name used when rendering a link. default `a`

At most one of 'updateContainerID', 'replaceID' and 'ignoreActionResponse' may be bound.

AjaxDefaultSubmitButton

Update

An invisible submit button placed first in a form so that pressing Enter performs its action (the form's "default" action) via the background Ajax submit. A subclass of AjaxSubmitButton; renders an off-screen type="submit" input. Modern browsers fire its click on Enter natively (the legacy IE<9 keypress shim is dropped).

<wo:form>
  <wo:AjaxDefaultSubmitButton action="$search" updateContainerID="results"/>
  ...fields...
</wo:form>

Binding	Type	Description
action	↓ WOActionResults	The action to execute on Enter.
updateContainerID	↓ String \| List	The update container(s) to morph after the action — a single id, a `;`-separated set, or a `List` of ids. `"_parent"` targets the nearest enclosing container.
replaceID	↓ String	The id of an element to replace with the action's response (alternative to `updateContainerID`).
formName	↓ String	The name of the form to submit (defaults to the containing form).
name	↓ String	HTML name of the hidden button (optional).
value	↓ String	HTML value of the hidden button (optional).
onClick	↓ String	Client hook: JavaScript to run after the request is sent.
onClickBefore	↓ String	Gate before the request: if the given expression is false, the click is ignored (e.g. `confirm(...)`).
onClickServer	↓ String	If the action returns null, this binding's value is returned as server JS.
ignoreActionResponse	↓ Boolean	If true, the action's result is ignored and an empty/`onClickServer` response is returned instead.
onSuccess	↓ String	Post-update hook: JavaScript to run after a successful update/morph completes.
onComplete	↓ String	Post-update hook: JavaScript to run after the update/morph completes.
disabled	↓ Boolean	If true, the button does not handle the form submission on the server.
id	↓ String	The HTML id of this submit button.
class	↓ String	The HTML class of this submit button.
accesskey	↓ String	Hot key that should trigger the button (optional).

AjaxObserveField

Update

Performs an Ajax submit (and optional container morph) when a form field changes. Two modes: give it an observeFieldID to watch a single field; or omit observeFieldID to watch every descendant form field inside it (it then renders a wrapper element). Binds native change/input listeners with a debounce. fullSubmit="false" (the default) sends only the changed field (partial submit).

Element content is only meaningful in descendant mode — in single-field mode the element must be empty (use the self-closing form; content there is rejected at template parse time rather than silently dropped).

<!-- single field -->
<wo:textfield value="$q" id="q"/>
<wo:AjaxObserveField observeFieldID="q" updateContainerID="results" action="$search"/>

<!-- descendant mode: watch every field inside the wrapper -->
<wo:AjaxObserveField updateContainerID="results" action="$refresh">
  <wo:popUpButton .../> <wo:textfield .../>
</wo:AjaxObserveField>

Binding	Type	Description
observeFieldID	↓ String	The id of the field to observe. Omit to observe all descendant fields of this element (descendant mode).
updateContainerID	↓ String \| List	The update container(s) to morph on change — a single id, a `;`-separated set, or a `List` of ids. `"_parent"` targets the nearest enclosing container.
action	↓ WOActionResults	The action to call when the observer fires.
fullSubmit	↓ Boolean	When false (default), only the changed field is submitted (partial); when true, the whole form is submitted.
observeDelay	↓ Number	The debounce, in seconds, before the submit fires.
observeFieldFrequency	↓ Number	Legacy poll interval, in seconds; now treated as a debounce. deprecated Use `observeDelay` instead.
onBeforeSubmit	↓ String	JS called before submitting; return false to deny the submit.
onSuccess	↓ String	JavaScript to run after a successful update/morph completes.
onComplete	↓ String	JavaScript to run after the update/morph completes.
name	↓ String	The HTML name used as the ajax submit-button name (defaults to the element id).
id	↓ String	The id of the observe-field wrapper (only used in descendant mode).
elementName	↓ String	The wrapper element name (only used in descendant mode). default `div`
class	↓ String	CSS class of the wrapper (only used in descendant mode), passed through to the rendered tag.
style	↓ String	CSS style of the wrapper (only used in descendant mode), passed through to the rendered tag.

AjaxUpdateTrigger

Server

A server-side-only element with no UI of its own: when it is rendered into a response, it forces named AjaxUpdateContainers elsewhere on the page to refresh. Useful when a central area controls several others — e.g. an edit view that, on opening, tells all the sibling read-only views to re-render. A missing target is silently skipped.

<!-- inside a region that, when re-rendered, should refresh others: -->
<wo:AjaxUpdateTrigger updateContainerID="summaryPanel"/>

Binding	Type	Description
updateContainerID	↓ String \| List	The update container(s) to refresh — a single id, a `;`-separated set, or a `List` of ids. `"_parent"` targets the nearest enclosing container.

AjaxPopUpButton

Passthrough

A drop-in WOPopUpButton that renders a searchable single-select instead of a bare <select>. Reach for it when a long option list needs type-to-filter. The widget auto-enhances any matching <select> on the page, so it needs no per-page init.

<wo:AjaxPopUpButton list="$items" item="$item" selection="$sel"
  displayString="$item.name" noSelectionString="Pick one…"/>

Binding	Type	Description
list ●	↓ List	The list of objects to choose from.
item	↓ Object	The repetition item (current object) during rendering.
selection	↕ Object	The currently selected object (settable).
displayString	↓ String	The text shown for each option (defaults to the item's `toString`).
noSelectionString	↓ String	Placeholder option text shown when nothing is selected.
value	↓ Object	Value-based selection (as on WOPopUpButton).
selectedValue	↕ Object	Value-based selection (as on WOPopUpButton).
disabled	↓ Boolean	Standard WOPopUpButton behaviour.
escapeHTML	↓ Boolean	Standard WOPopUpButton behaviour.
otherTagString	↓ String	Additional attributes appended verbatim to the rendered tag (the legacy WOPopUpButton escape hatch from before attribute passthrough existed). deprecated Unknown attributes pass through to the rendered tag natively — write them directly on the element instead.
id	↓ String	Standard HTML attribute. (The marker class `ajax-popup-button` is merged in automatically.)
name	↓ String	Standard HTML attribute. (The marker class `ajax-popup-button` is merged in automatically.)
class	↓ String	Standard HTML attribute. (The marker class `ajax-popup-button` is merged in automatically.)
style	↓ String	Standard HTML attribute. (The marker class `ajax-popup-button` is merged in automatically.)

'list' must be a keypath, not a constant.

'item' must be settable (assignable, not a constant) when 'displayString' or 'value' is bound.

'item' must be bound when 'displayString' or 'value' is bound.

At most one of 'selection' and 'selectedValue' may be bound.

AjaxBrowser

Passthrough

The multi-select companion to AjaxPopUpButton: a drop-in WOBrowser that renders the same searchable wonder-select widget with removable tags instead of a bare multi-select. The shared wonder-select.js reads the <select>'s multiple attribute to switch between single value and removable tags.

<wo:AjaxBrowser list="$items" item="$item" selections="$selected"
  multiple="$true" displayString="$item.name" noSelectionString="Add some…"/>

Binding	Type	Description
list ●	↓ List	The list of objects to choose from.
item	↓ Object	The repetition item during rendering.
selections	↕ List	The currently selected objects (settable).
selectedValues	↕ List	Value-based multi-selection (as on `WOBrowser`).
value	↓ Object	The value for each option, taken from `item` during rendering.
multiple	↓ Boolean	Whether the browser is multi-select (bind `multiple="$true"` for tags).
displayString	↓ String	The text shown for each option.
otherTagString	↓ String	Extra attributes appended to the rendered `<select>` tag. deprecated Unknown attributes pass through to the rendered tag natively — write them directly on the element instead.
disabled	↓ Boolean	Standard `WOBrowser` behaviour — renders the select as disabled.
escapeHTML	↓ Boolean	Standard `WOBrowser` behaviour — whether the display string is HTML-escaped.
id	↓ String	Standard HTML `id` attribute.
name	↓ String	Standard HTML `name` attribute.
class	↓ String	Standard HTML `class` attribute.
style	↓ String	Standard HTML `style` attribute.

'list' must be a keypath, not a constant.

'item' must be settable (assignable, not a constant) when 'displayString' or 'value' is bound.

'item' must be bound when 'displayString' or 'value' is bound.

At most one of 'selections' and 'selectedValues' may be bound.

AjaxModalContainer

Update Container

Renders a trigger button that opens its inline content in a modal dialog, built on the platform's native <dialog> (free backdrop, focus trapping and Esc-to-close; clicking outside the dialog closes it too — clicks inside, including drags that end outside, never do). The content stays in place in the DOM, so forms/links inside the dialog — including update containers — work exactly as anywhere else. Only the inline-content use is supported (iframe / direct-action / skin / locked modes are dropped).

<wo:AjaxModalContainer label="Details" title="Order details" id="box">
  ...dialog content (may contain its own update container)...
</wo:AjaxModalContainer>

Binding	Type	Description
label	↓ String	The text on the trigger button.
title	↓ String	Optional title shown at the top of the dialog (and as the button's `title`).
closeLabel	↓ String	The text on the dialog's close button. default `Close`
open	↓ Boolean	If true, the dialog is open on initial render.
id	↓ String	Optional id for the trigger button.
class	↓ String	The HTML class attribute, passed through to the trigger button.
style	↓ String	The HTML style attribute, passed through to the trigger button.

AjaxBusySpinner

Activity

Shows a busy indicator while AjaxSlim has one or more Ajax requests in flight, and hides it when idle. A pure-CSS spinner driven by the runtime's activity broker — ajaxslim.js sets data-ajaxslim-busy on the document element while any request is in flight. No configuration: a busy indicator is the same everywhere. (Apps wanting a bespoke one can style .ajaxslim-busy-spinner or react to the ajaxslim:busy/ajaxslim:idle events on document.)

<wo:AjaxBusySpinner/>

Binding	Type	Description
id	↓ String	Optional id for the spinner element.
class	↓ String	Optional extra CSS class(es) on the spinner.
style	↓ String	Optional inline style on the spinner.
delay	↓ String	Optional show-delay (anti-flash): the spinner only appears after this much sustained Ajax activity. A bare number is seconds (`delay="0.2"`); a CSS time value with its own unit (`"200ms"`) is also accepted.
fade	↓ String	Optional fade-in/out duration: the spinner fades over this time instead of appearing and vanishing instantly. Same value format as `delay`; independent of it.

AjaxPing

Activity

Refreshes a large content area based on periodic refreshes of a very small one. A tiny self-refreshing container whose content depends only on cacheKey: while the key is unchanged the periodic ping is cheap; when it changes, the embedded AjaxPingUpdate refreshes the (potentially large) updateContainerID. So the expensive container is rebuilt only when something actually changed.

<wo:AjaxPing updateContainerID="bigPanel" cacheKey="$panelVersion" frequency="5"/>

Binding	Type	Description
updateContainerID	↓ String	The id of the update container to refresh when the key changes.
targetContainerID	↓ String	Alias for `updateContainerID`, kept for backward compatibility. deprecated Use `updateContainerID` instead.
cacheKey	↓ Object	A value that represents the state of the target container.
frequency	↓ Number	The frequency of the ping, in seconds. default `3`
onBeforeUpdate	↓ String	A JS function to call before updating; return true to allow the update.
stop	↓ Boolean	If true, the ping stops; if false it runs (refresh the ping's container to restart it).
id	↓ String	Optional id of the ping container.

At most one of 'updateContainerID' and 'targetContainerID' may be bound.

AjaxPingUpdate

Server

Refreshes a target AjaxUpdateContainer when its cache key changes. Used inside an AjaxPing — place several in one ping to drive multiple targets from a single periodic refresh. It tracks cacheKey across requests and emits a refresh script for its target only when the key differs from the last seen value.

<wo:AjaxPing frequency="5" cacheKey="$tick">
  <wo:AjaxPingUpdate updateContainerID="panelA" cacheKey="$versionA"/>
  <wo:AjaxPingUpdate updateContainerID="panelB" cacheKey="$versionB"/>
</wo:AjaxPing>

Binding	Type	Description
updateContainerID	↓ String	The id of the update container to refresh when the key changes.
targetContainerID	↓ String	Alias for `updateContainerID`, kept for backward compatibility. deprecated Use `updateContainerID` instead.
cacheKey	↓ Object	A value that represents the state of the target container.
onBeforeUpdate	↓ String	A JS function to call before updating; return true to allow the update.

Exactly one of 'updateContainerID' and 'targetContainerID' must be bound.

AjaxSortable

Makes the rows of a list drag-reorderable. Drop this element inside (or next to) the container whose children should be sortable; it renders the one-time client registration and, on drop, fires your action and morphs your updateContainerID — so reordering is a normal server action that can mutate the model and refresh whatever it needs.

The browser side is a dependency-free, morph-safe sortable that drags by a handle and, on drop, reports the move positionally — the dragged row's original index and its final index. There is no per-row id binding; the contract is purely positional. The live drag is optimistic (rows reorder under the pointer); the authoritative server response morphs the list back in and makes it real.

The reorderable rows and their drag grips are marked in your own row markup with data attributes — data-sortable-item on each draggable row and data-sortable-grip on the grab handle inside it — so the container's internal DOM structure stays out of the template bindings. A drag only starts from a grip, so the row's own controls (inputs, links) don't initiate one.

Server side, read the move in your action with the AjaxSortable.dragResult(request) helper:

public WOActionResults reorderLines() {
  AjaxSortable.DragResult move = AjaxSortable.dragResult(context().request());
  if (move != null && move.isValidFor(_lines.size())) {
    _lines.add(move.toIndex(), _lines.remove(move.fromIndex()));
  }
  return null;
}

<wo:AjaxUpdateContainer id="linesContainer" elementName="div">
  <wo:AjaxSortable listID="linesContainer" action="$reorderLines"
     updateContainerID="linesContainer;totalsPanel;renderedInvoice" />
  <table>
    <tr ... data-sortable-item>
      <td data-sortable-grip>&#x283F;</td> ...
    </tr>
  </table>
</wo:AjaxUpdateContainer>

Binding	Type	Description
listID ●	↓ String	The id of the container holding the rows marked with `data-sortable-item`.
action	↓ WOActionResults	The server action fired on drop. Read the move with `AjaxSortable.dragResult(request)`.
updateContainerID	↓ String \| List	The update container(s) to morph from the action's response — a single id, a `;`-joined set, or a `List` of ids. `"_parent"` targets the nearest enclosing container.