OcaltQL Javascript & Ajax

HTML "script" TEXT embeds raw client-side JavaScript. ONBROWSER JAVASCRIPT binds browser events directly, with no hand-written addEventListener boilerplate. NEW ONBROWSER AJAX generates a callable function that calls back into the current Site Mode site, with no credentials ever present in the browser.

Site Mode. These verbs build the page that gets delivered to a browser, so they belong in a Site Mode script. Outside Site Mode the generated JavaScript is still returned — useful for inspecting it — but there is no page for it to attach to.

Embedding Raw JavaScript

Raw client-side JavaScript is embedded directly with HTML "script" TEXT — no intermediate variable is needed.

Embed a Script
HTML "script" TEXT `alert('hello world');`

HTML "script" SRC — External Script Inclusion

Includes an external JavaScript file via a src attribute, as an alternative to HTML "script" TEXT for inline content.

Include an External Script
HTML "script" SRC "https://cdn.example.com/library.js"

HTML GET — Selecting Elements

HTML GET selects a single element by CSS selector. HTML GET ALL selects every matching element as an array. Both are used to target ONBROWSER JAVASCRIPT event bindings at specific elements.

Select a Single Element
HTML GET ".element" SET ?el
Select All Matching Elements
HTML GET ALL ".element" SET ?elarray

ONBROWSER JAVASCRIPT — Event Binding

Binds a browser event directly — no addEventListener boilerplate. With no element target, the event binds at the window/document level. With an element or array of elements from HTML GET/HTML GET ALL, it binds to that element, or to every element in the array.

The event object is already in scope. The code inside ENTER is wrapped in function(event) { ... } automatically — reference event directly, with no need to declare the function signature yourself.
Page-Level Events — No Element Target
ONBROWSER JAVASCRIPT ONLOAD ENTER `alert('hello world');`
More Page-Level Events
ONBROWSER JAVASCRIPT ONPAGESHOW ENTER `alert('hello world');`
ONLOADED — First Pageshow Only
ONBROWSER JAVASCRIPT ONLOADED ENTER `alert('runs once');`
ONLOADED is ONPAGESHOW, fired once. A browser fires pageshow again every time the page is restored from the back/forward cache — the visitor navigates away, presses back, and the handler runs a second time on a page that was never reloaded. ONLOADED binds the same event but blocks that re-run, so the code fires on the first pageshow and never again unless the page is genuinely reloaded.
Why It Matters — the Same Code Both Ways
ONBROWSER JAVASCRIPT ONPAGESHOW ENTER `startTour();`
(* Runs again every time the visitor presses back into this page *)

ONBROWSER JAVASCRIPT ONLOADED ENTER `startTour();`
(* Runs on the first arrival, and not on a back-navigation restore *)
Window Focus
ONBROWSER JAVASCRIPT ONFOCUS ENTER `alert('hello world');`
Binding to a Single Element
HTML GET ".element" SET ?el
AFTER ONBROWSER JAVASCRIPT ?el ONCLICK ENTER `alert('hello world');`
Binding to Every Matching Element
HTML GET ALL ".element" SET ?elarray
AFTER ONBROWSER JAVASCRIPT ?elarray ONCLICK ENTER `alert('hello world');`
(* Binds to every element in the array *)
Focus Binding on a Specific Element
HTML GET ".element" SET ?el
AFTER ONBROWSER JAVASCRIPT ?el ONFOCUS ENTER `alert('hello world');`

The Full Event Set

Any browser event binds by its real name, prefixed ON. The page-level events above are the common ones; element events are the same grammar with a target from HTML GET.

Group Events
PageONLOAD, ONPAGESHOW, ONLOADED, ONPAGEHIDE, ONBEFOREUNLOAD, ONHASHCHANGE, ONPOPSTATE
WindowONFOCUS, ONBLUR, ONRESIZE, ONSCROLL, ONONLINE, ONOFFLINE, ONVISIBILITYCHANGE
MouseONCLICK, ONDBLCLICK, ONMOUSEDOWN, ONMOUSEUP, ONMOUSEOVER, ONMOUSEOUT, ONMOUSEMOVE, ONCONTEXTMENU, ONWHEEL
KeyboardONKEYDOWN, ONKEYUP, ONKEYPRESS
FormONSUBMIT, ONRESET, ONCHANGE, ONINPUT, ONSELECT, ONINVALID
TouchONTOUCHSTART, ONTOUCHEND, ONTOUCHMOVE, ONTOUCHCANCEL
DragONDRAGSTART, ONDRAG, ONDROP, ONDRAGOVER, ONDRAGENTER, ONDRAGLEAVE
Form Submit, Intercepted
HTML GET "#signup" SET ?form
AFTER ONBROWSER JAVASCRIPT ?form ONSUBMIT ENTER `
event.preventDefault();
console.log('intercepted');
`
Keyboard on a Specific Field
HTML GET "#search" SET ?input
AFTER ONBROWSER JAVASCRIPT ?input ONKEYUP ENTER `
if (event.key === 'Enter') { doSearch(); }
`

Passing OcaltQL Values Into the Browser

An ENTER block is raw JavaScript, so a server-side value reaches it the same way any string is built — with &. Anything structured goes across as JSON via CAST.

A Value and an Object
STRING "Kea" SET ?name
AFTER ONBROWSER JAVASCRIPT ONLOADED ENTER `alert('hello ` & ?name & `');`

AFTER SELECT ROWS FROM DB "shopdb" TABLE "orders" SET ?rows
AFTER CAST ?rows AS JSON SET ?json
AFTER HTML "script" TEXT `const ORDERS = ` & ?json & `;`

NEW ONBROWSER AJAX

Generates a named, callable JavaScript function that makes an AJAX call back into the current Site Mode site. No credentials are ever present in the browser — the Site Mode router already authenticates as the site owner server-side, invisibly, exactly as it did to serve the current page. This is the only safe way to make an AJAX call from OcaltQL-generated browser JavaScript; embedding real credentials directly in client-side code is never safe, as covered on OcaltQL API & Client.

Call Back Into the Current Page
NEW ONBROWSER AJAX TO SELF NAMED "ajaxRequest" ON SUCCESS `console.log(result);` SET ?script
AFTER HTML "script" TEXT ?script
Call a Different Page on the Same Site
NEW ONBROWSER AJAX TO "/other-page" NAMED "loadOther" ON SUCCESS `console.log(result);` SET ?script
AFTER HTML "script" TEXT ?script

Sending Data and Handling Failure

The generated function takes an object and posts it; inside ON SUCCESS the response body is available as result. ON ERROR handles a non-2xx response or a failed request.

Post a Payload, Handle Both Outcomes
NEW ONBROWSER AJAX TO "/api" NAMED "saveOrder"
ON SUCCESS `document.querySelector('#status').textContent = result;`
ON ERROR `document.querySelector('#status').textContent = 'failed';`
SET ?script
AFTER HTML "script" TEXT ?script
AFTER HTML "script" TEXT `saveOrder({ item: 'widget', qty: 2 });`
The Endpoint It Calls
(* /root/sites/mysite/api.oql *)
PARSE !REQUEST('body') AS JSON SET ?in
AFTER INSERT INTO DB "shopdb" TABLE "orders" ROW "item" AS ?in("item") SET ?id
AFTER EMIT "saved as #" & ?id
The endpoint is an ordinary Site Mode script — see Notifications & API Endpoints. TO SELF calls the current page back instead of a separate file, which suits a page that handles both its own rendering and its own AJAX.
Site Mode only. NEW ONBROWSER AJAX relies on Site Mode's own server-side authentication as the site owner. It has no equivalent outside Site Mode — a script running via the plain credentialed API has no session for a browser call to lean on.
GATHER & CONFIRM →