Transformer

Transformers allow you to write lightweight JavaScript functions to transform or reshape data from queries, components, or application state. Think of them as computed properties: they take existing data, process it, and return a new value you can reuse across your app.

Why Use Transformers?

• Data shaping: Turn raw API/SQL results into the structure your UI needs.
• Formatting: Format dates, numbers, or strings consistently.
• Preprocessing: Filter, group, or aggregate data before binding.
• Reusability: Centralize a transformation once and use it in multiple components.
• Dynamic logic: Reference user context (currentUser, roles, input values).

Anatomy

1. Explorer (left)
   • Transformers are listed alongside queries.
   • Example: transformer1 under Explorer.
2. Editor (center)
   • JavaScript editor where you define your logic.
   • Code must return a value.
   • Example: const name = currentUser.userName || 'world'; return 'Hello ' + name;
3. Execute button
   • Runs the transformer immediately so you can preview the result.
4. Response panel (bottom)
   • Displays the returned value in real-time.
   • Example output: { "success": true, "value": "Hello Zeroplat" }

How Transformers Work

• Transformers are pure functions: they don’t trigger queries, they just process data.
• Always end with a return statement.
• Whatever you return becomes accessible as transformerName.value.
• Execution is synchronous (no await). If you need async orchestration, use a JS Query instead.

Common Use Cases

1. String Formatting

const name = currentUser.userName || "Guest";
return `Welcome back, ${name}!`;

2. Aggregate Data

const rows = getOrders.data || [];
const total = rows.reduce((sum, r) => sum + (r.amount || 0), 0);
return { count: rows.length, total };

Usage in a label:
{{ transformer1.value.total }}

3. Prepare Chart Data

const sales = getSales.data || [];
return sales.map(item => ({
  x: item.date,
  y: item.amount
}));

Usage in chart binding:
{{ transformer1.value }}

4. Conditional Mapping

const user = getUser.data || {};
return user.role === "admin" ? "Administrator" : "Standard User";

Usage:
{{ transformer1.value }} → outputs "Administrator" or "Standard User"

5. Table Column Enhancement

const rows = getCustomers.data || [];
return rows.map(r => ({
  ...r,
  fullName: `${r.firstName} ${r.lastName}`
}));

Usage:
Bind {{ transformer1.value }} directly to a Table.

Best Practices

• Keep it simple: Transformers should be focused on shaping/formatting, not heavy logic.
• Avoid side effects: Do not run queries or change state here.
• Consistency: Return a predictable structure (object, array, or primitive).
• Naming: Use descriptive names (e.g., ordersSummary, chartData, formatUser).
• Reuse: Instead of repeating formatting logic in multiple components, centralize it in a transformer.

Accessing Transformer Output

• Anywhere in the app, refer to the transformer’s result with: {{ transformer1.value }}
• If the result is an object or array, access properties: {{ transformer1.value.total }} {{ transformer1.value[0].name }}

Error Handling

If your transformer throws an error:

• The Response panel will display the error message.
• Example: throw new Error("Invalid data");
• Best practice: always check inputs before processing: const rows = getOrders.data; if (!Array.isArray(rows)) return []; return rows.filter(r => r.status === "active");

Example Walkthrough

Code

const name = currentUser.userName || 'world';
return 'Hello ' + name;

Response

{
  "success": true,
  "value": "Hello Zeroplat"
}

Usage

• Bind anywhere as {{ transformer1.value }}.
• Output → "Hello Zeroplat"

FAQ

Q: Can a Transformer run async code (await)?
A: No. Use JS Query if you need async operations.

Q: How do I use a Transformer inside components?
A: Use {{ transformerName.value }} in bindings (table data, labels, conditions, etc.).

Q: When does a Transformer update?
A: It re-runs automatically whenever its dependencies (queries, components, or variables referenced inside) change.

👉 Transformers are ideal for computed values. Use them to keep your pages clean, declarative, and reusable.