Skip to content
Verified

JavaScript

Real JS source, compiled on save, for logic that a declarative program cannot express.

A JavaScript program holds real source code in scriptData.value, the escape hatch for logic that a declarative Get Data, Set Data or Batch cannot express. It compiles on save (save_prog runs the same build Studio does and returns data.compile, { ok: true, dependencies } or { ok: false, error }), and it runs with a real API for fields, tables and events, not just a DOM element.

Properties

The execution contract

The source is a plain async body, no export, no wrapper, run as:

js
async function (params, xu, SESSION_ID, SESSION_OBJ, jobNoP, $container, func, glb, APP_OBJ, evt) {
  /* your source */
}

params are the caller's already-evaluated parameters. xu is the runtime API: fields, database rows, events, HTTP. await works freely since the wrapper is async. Quotes are fine here, unlike an xu-script attribute value.

Reading and writing a table

js
const raw = await xu.get_field_value(`rows_json_v`);
const rows = typeof raw === `string` ? JSON.parse(raw || `[]`) : raw || [];
for (const row of rows) {
  await xu.dbs_create(`392_tbl_…`, { CNT_Name: row.name || `` });
}
// dbs_read resolves to an ARRAY of { id, value } rows, the row id on .id, fields under .value.
const all = await xu.dbs_read(`392_tbl_…`, {}, [], null, 999);
await xu.set_field_value(`saved_rows_v`, all.map((r) => ({ row_id: r.id, name: r.value?.CNT_Name || `` })));

dbs_* methods take the table's _id, never its name. The fields projection on dbs_read is optional: [], the default, returns every field, and a list of field ids returns only those.

Passing data in: fields, not parameters

call_native_javascript does not evaluate {value, fx} parameter wrappers, a script called that way receives the literal {value: "", fx: "@field"} objects, not resolved values. The reliable pattern: the caller puts the payload into a field first (an update step or an xu-bind input), calls the script with empty parameters: {}, and the script reads with xu.get_field_value and reports back with xu.set_field_value. Calling from another script is different, xu.call_javascript(prog_id, {...}) parameters do arrive as passed.

Invoking a JavaScript program

Worked example

Declare the parameters

progFields entries become the wrapper function's argument names, in call order.

Write the body

A plain async function body, return a value if call_evaluate_javascript will read it.

Call it and read compile.ok

After save_prog, check data.compile.ok, a failed compile still saves the doc with a build_error attached.

Create a JavaScript node under Programs, write source in the code editor, add parameters on the Fields grid. Save recompiles automatically, errors surface in the editor.

xml
<meta lang="json5">
{
  id: "normalize_student_name",
  menuTitle: "Normalize Student Name"
}
</meta>

<params lang="json5">
{
  in: { raw_name_in: "string" },
  out: { normalized_name_out: "string" }
}
</params>

<code>
return (@raw_name_in || "")
  .trim()
  .split(/\s+/)
  .filter(Boolean)
  .map(part => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
  .join(" ");
</code>
json
{
  "properties": { "menuType": "javascript", "menuName": "Slugify Name", "fileExtension": "js" },
  "scriptData": { "value": "return name.toLowerCase().replace(/[^a-z0-9]+/g, '-');", "dependencies": [] },
  "progFields": [
    { "id": "b2c3d4e5-…", "data": { "field_id": "name", "type": "virtual" }, "props": { "fieldType": "string" } }
  ]
}