Saltar para o conteúdo
Verificado

JavaScript

Código JS real, compilado ao guardar, para lógica que um programa declarativo não consegue exprimir.

Um programa JavaScript contém código-fonte real em scriptData.value, a saída de emergência para lógica que um Obter Dados, Definir Dados ou Lote declarativo não consegue exprimir. Compila ao guardar (save_prog executa a mesma compilação que o Studio e devolve data.compile, { ok: true, dependencies } ou { ok: false, error }), e corre com uma API real para campos, tabelas e eventos, não apenas um elemento DOM.

Propriedades

O contrato de execução

O código-fonte é um corpo assíncrono simples, sem export, sem wrapper, executado como:

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

params são os parâmetros de quem chama, já avaliados. xu é a API do runtime: campos, linhas da base de dados, eventos, HTTP. await funciona livremente, uma vez que o wrapper é assíncrono. As aspas não têm problema aqui, ao contrário de um valor de atributo xu-script.

Ler e escrever numa tabela

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 || `` })));

Os métodos dbs_* recebem o _id da tabela, nunca o seu nome. A projeção fields em dbs_read é opcional: [], o valor predefinido, devolve todos os campos, e uma lista de ids de campos devolve só esses.

Passar dados: campos, não parâmetros

call_native_javascript não avalia os wrappers de parâmetros {value, fx}, um script chamado dessa forma recebe os objetos literais {value: "", fx: "@field"}, não valores resolvidos. O padrão fiável: quem chama coloca primeiro a carga num campo (um passo update ou um campo de entrada xu-bind), chama o script com parameters: {} vazio, e o script lê com xu.get_field_value e comunica de volta com xu.set_field_value. Chamar a partir de outro script é diferente, os parâmetros de xu.call_javascript(prog_id, {...}) chegam tal como foram passados.

Invocar um programa JavaScript

Exemplo prático

Declare os parâmetros

As entradas de progFields tornam-se os nomes dos argumentos da função wrapper, pela ordem da chamada.

Escreva o corpo

Um corpo de função assíncrona simples, faça return de um valor se call_evaluate_javascript o for ler.

Chame-o e leia compile.ok

Depois de save_prog, verifique data.compile.ok, uma compilação falhada ainda guarda o documento com um build_error anexado.

Crie um nó JavaScript em Programas, escreva o código no editor de código e adicione parâmetros na grelha de Campos. Guardar recompila automaticamente, os erros aparecem no 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" } }
  ]
}