🎯 context: The Action Object¶

context is the object Clera passes to every action function and lifecycle hook. It provides information about the current page and helpers for common tasks.

Think of it as your toolbox for that page. Navigation, data, DOM updates, form values, and network calls are all here.

⚠️ context is only available inside action functions and lifecycle hooks. It does not exist at the top level of your script. Accessing it outside a handler returns null and logs:

[CLERA:CONTEXT_OUTSIDE_HANDLER] context accessed outside an active handler.
context is only available inside action handlers and lifecycle hooks.

🌍 For things you need at the global level (timeouts, intervals, event listeners), use app.* equivalents:

Need	Inside a function	Outside a function
Timed callback	`context.timeout()`	`app.timeout()`
Repeating callback	`context.timeout()` in a loop	`app.interval()`
DOM event listener	`context.listen()`	`app.listen(element, ...)`
Trigger DOM update	`context.update()`	`app.update()`
Navigate	`context.navigate()`	`app.navigate()`

🗺️ Overview¶

function myAction(context) {
  context.pageName        // name of the current page
  context.params          // navigation params passed to this page
  context.event           // the triggering DOM event (or null)
  context.element         // the element that triggered the action (or null)

  context.navigate()      // navigate to another page
  context.back()          // go back

  // Data system
  context.data()          // attach page-local data
  context.update()        // manually patch DOM bindings
  context.fetch()         // Clera-aware fetch (auto-updates DOM)
  context.timeout()       // Clera-aware setTimeout (auto-updates DOM)
  context.myDataKey       // direct access to any key you attached via context.data()

  context.query()         // find an element in the page
  context.render()        // replace element content
  context.append()        // add to element content
  context.clear()         // empty an element

  // form actions only:
  context.values          // form field values as a plain object
  context.formData        // raw FormData object
  context.form            // the HTMLFormElement
  context.submitter       // the button that submitted the form
  context.resetForm()     // reset the form
  context.setSubmitting() // control the submitting lock

  context.log             // dev logging helpers
  context.unsafe          // escape hatches to raw DOM
}

📋 Properties¶

📌 `context.pageName`¶

The name of the page this action is running on.

console.log(context.pageName); // "home"

📦 `context.params`¶

Parameters passed during navigation. Empty object if none were passed.

app.navigate("profile", { userId: 42 });

// inside the profile page:
console.log(context.params.userId); // 42

🖱️ `context.event`¶

The raw DOM event that triggered the action. null for lifecycle hooks.

🔲 `context.element`¶

The element that triggered the action. For form actions, this is the submitter button (or null).

📦 `context.args` and `context.arg`¶

When an action is called with inline arguments, they are available on context.args (frozen array) and context.arg (first item shorthand, null when no args were passed).

Both syntaxes land identically:

<button action="deleteTask: {task.id}">Delete</button>
<button action="deleteTask({task.id})">Delete</button>

function deleteTask(context) {
  const id = context.arg;         // first arg shorthand
}

function move(context) {
  const id     = context.args[0];
  const status = context.args[1];
}

See 04 Actions for the full argument syntax, all supported types, and binding resolution rules.

🗄️ Data system¶

📥 `context.data(sourceObject)`¶

Attach page-local data. Merges by reference: keys become directly accessible on context.*. Page data overrides global data of the same key on this page only.

function loadHome(context) {
  const stats = { count: 0 };
  context.data({ stats });

  context.stats.count; // 0: direct access
}

⚠️ Avoid naming your data keys after Clera built-in properties like navigate, render, or pageName. Clera will reject them with [CLERA:DATA_KEY_RESERVED] and skip that key.

👂 `context.listen(selector, eventName, callback, options?)` → off()¶

Attaches an event listener to elements inside the current page. The callback runs inside Clera’s execution cycle so DOM bindings update automatically after each event. Auto-rebinds after context.render(), context.append(), and context.clear(). Prevents duplicates via callback reference identity.

const off = context.listen(".item", "click", (event) => {
  context.data({ selected: event.target.textContent });
});

off(); // remove rule and all element attachments

See 15 Page Listeners for full usage.

🔄 `context.update()`¶

Manually trigger a DOM binding patch. Use when data mutates outside Clera-controlled execution (raw setTimeout, raw fetch, WebSocket etc.).

setTimeout(() => {
  context.stats.count += 1;
  context.update(); // manual trigger required
}, 1000);

🌐 `context.fetch(url, options?, callback?)` → Promise¶

Clera-aware fetch. DOM bindings update automatically after callback or await resolves. No context.update() needed.

// Callback style
context.fetch("/api/data", function(result) {
  context.stats.count = result.count; // auto-updates DOM
});

// Async/await
const result = await context.fetch("/api/data", { method: "POST", body: { name } });

See 11 Async Helpers for full options reference.

⏱️ `context.timeout(callback, delay)` → timerId¶

Clera-aware setTimeout. DOM bindings update automatically after the callback runs.

context.timeout(function() {
  context.message.text = "Done!"; // auto-updates DOM
}, 2000);

🔑 `context.myDataKey`¶

Any key attached via context.data() or app.data() is accessible directly on context:

context.data({ stats, filters });
context.stats.count;    // direct access
context.filters.active; // direct access

🔍 DOM helpers¶

All DOM helpers are scoped to the current page. They cannot reach elements outside the active page.

🔍 `context.query(cssSelector)`¶

Find an element within the current page. Returns a safe wrapper object.

const wrapper = context.query("#title");
wrapper.exists            // true or false
wrapper.element           // raw HTMLElement or null
wrapper.text("Hello")     // set text content
wrapper.text()            // get text content
wrapper.html("<b>Hi</b>") // set innerHTML
wrapper.value("new")      // set input value
wrapper.value()           // get input value
wrapper.on("click", fn)   // add event listener

🖊️ `context.render(selector, html, options?)`¶

Replace the inner HTML of an element. Processes {path} bindings in injected HTML automatically.

context.render("#taskList", tasks.map(t => `<li>${t}</li>`).join(""));

// Prevent layout jump during swap:
context.render("#feedList", html, { reserveHeight: true });

➕ `context.append(selector, html)`¶

Add HTML to an element without clearing existing content. Processes {path} bindings in the appended fragment.

context.append("#taskList", `<li>${newTask}</li>`);

🗑️ `context.clear(selector)`¶

Empty an element.

context.clear("#taskList");

📝 Form helpers (form actions only)¶

📋 `context.values`¶

Form field values as a plain object. Fields with the same name become arrays.

context.values.title  // "Buy milk"
context.values.tags   // ["design", "code"] (multiple checkboxes)

📄 `context.form`¶

The raw HTMLFormElement. context.form.reset() clears the form.

📦 `context.formData`¶

The raw FormData object for advanced use cases (file uploads etc.).

🖱️ `context.submitter`¶

The button that submitted the form, or null.

🔁 `context.resetForm()`¶

Resets the form. Equivalent to context.form.reset().

🔒 `context.setSubmitting(boolean)`¶

Manually control the double-submit lock.

📟 Logging¶

context.log emits structured entries into the Clera diagnostics buffer from your own code. Entries appear in app.diagnostics alongside runtime entries and are formatted in the console as [CRE:CODE] message.

context.log.warn("MY_CODE", "Something unexpected happened");
context.log.error("MY_CODE", "Something failed", caughtError);

Method	Level	When to use
`context.log.warn(code, msg)`	`warn`	Unexpected but recoverable. Will not stop execution.
`context.log.error(code, msg, caughtError?)`	`error`	Failed operation. Pass the caught error as the third argument to append its message.

code should be a stable ALL_CAPS string that identifies the call site. It appears in the console and in app.diagnostics.logs() entries for filtering and tooling support.

🚪 Escape hatches¶

context.unsafe gives direct access to raw DOM objects that Clera’s scoped helpers cannot reach. Use only when the standard helpers are not sufficient.

context.unsafe.root()      // the live <page> DOM element
context.unsafe.document()  // window.document
context.unsafe.window()    // window

Direct DOM manipulation via context.unsafe bypasses the binding engine. Changes made this way will not trigger {path} binding updates. Call context.update() after if bindings need to reflect any changes.

Next¶

07 Forms and Values

🎯 context: The Action Object¶

🗺️ Overview¶

📋 Properties¶

📌 `context.pageName`¶

📦 `context.params`¶

🖱️ `context.event`¶

🔲 `context.element`¶

📦 `context.args` and `context.arg`¶

🧭 Navigation¶

🧭 `context.navigate(pageName, params?, options?)`¶

⬅️ `context.back()`¶

🗄️ Data system¶

📥 `context.data(sourceObject)`¶

👂 `context.listen(selector, eventName, callback, options?)` → off()¶

🔄 `context.update()`¶

🌐 `context.fetch(url, options?, callback?)` → Promise¶

⏱️ `context.timeout(callback, delay)` → timerId¶

🔑 `context.myDataKey`¶

🔍 DOM helpers¶

🔍 `context.query(cssSelector)`¶

🖊️ `context.render(selector, html, options?)`¶

➕ `context.append(selector, html)`¶

🗑️ `context.clear(selector)`¶

📝 Form helpers (form actions only)¶

📋 `context.values`¶

📄 `context.form`¶

📦 `context.formData`¶

🖱️ `context.submitter`¶

🔁 `context.resetForm()`¶

🔒 `context.setSubmitting(boolean)`¶

📟 Logging¶

🚪 Escape hatches¶

Next¶

🎯 context: The Action Object¶

🗺️ Overview¶

📋 Properties¶

📌 context.pageName¶

📦 context.params¶

🖱️ context.event¶

🔲 context.element¶

📦 context.args and context.arg¶

🧭 Navigation¶

🧭 context.navigate(pageName, params?, options?)¶

⬅️ context.back()¶

🗄️ Data system¶

📥 context.data(sourceObject)¶

👂 context.listen(selector, eventName, callback, options?) → off()¶

🔄 context.update()¶

🌐 context.fetch(url, options?, callback?) → Promise¶

⏱️ context.timeout(callback, delay) → timerId¶

🔑 context.myDataKey¶

🔍 DOM helpers¶

🔍 context.query(cssSelector)¶

🖊️ context.render(selector, html, options?)¶

➕ context.append(selector, html)¶

🗑️ context.clear(selector)¶

📝 Form helpers (form actions only)¶

📋 context.values¶

📄 context.form¶

📦 context.formData¶

🖱️ context.submitter¶

🔁 context.resetForm()¶

🔒 context.setSubmitting(boolean)¶

📟 Logging¶

🚪 Escape hatches¶

Next¶

📌 `context.pageName`¶

📦 `context.params`¶

🖱️ `context.event`¶

🔲 `context.element`¶

📦 `context.args` and `context.arg`¶

🧭 `context.navigate(pageName, params?, options?)`¶

⬅️ `context.back()`¶

📥 `context.data(sourceObject)`¶

👂 `context.listen(selector, eventName, callback, options?)` → off()¶

🔄 `context.update()`¶

🌐 `context.fetch(url, options?, callback?)` → Promise¶

⏱️ `context.timeout(callback, delay)` → timerId¶

🔑 `context.myDataKey`¶

🔍 `context.query(cssSelector)`¶

🖊️ `context.render(selector, html, options?)`¶

➕ `context.append(selector, html)`¶

🗑️ `context.clear(selector)`¶

📋 `context.values`¶

📄 `context.form`¶

📦 `context.formData`¶

🖱️ `context.submitter`¶

🔁 `context.resetForm()`¶

🔒 `context.setSubmitting(boolean)`¶