JavaScript Scripting API Reference for Qödiak

Qödiak’s JavaScript Scripting API lets you add dynamic behavior to your no‑code apps without leaving the platform. Whether you need to manipulate form data, control component visibility, or run server‑side transformations, this reference explains every built‑in function, event type, and execution environment you can use.

1. Getting Started with JavaScript in Qödiak

JavaScript scripting is available on the Starter tier ($9 / month) and above. The free tier does not include scripting capabilities, so be sure your subscription meets the minimum requirement before you begin.

Tip: All scripts are sandboxed. Client‑side scripts run in the browser, while server‑side scripts execute in a secure Jint engine with strict resource limits.

2. Form Data API

The Form Data API gives you direct programmatic access to any field on a Qödiak form. Use these functions inside button custom scripts, page‑level scripts, or server‑side transformations.

2.1 Core Functions

• setField(name, value) – Assigns value to the field identified by name.
• getField(name) – Returns the current value of the specified field.
• getFormData() – Retrieves an object containing all field names and their values.
• clearField(name) – Clears the content of a single field.
• resetForm() – Clears every field on the current form, returning it to its initial state.

2.2 Practical Example – Auto‑Fill a Discount Code

1. Place a button labeled “Apply Discount” on your checkout page.
2. Open the button’s Custom Script editor and add the following client‑side code:

   // Assume the discount field is named "discountCode"
   if (getField('totalAmount') > 100) {
       setField('discountCode', 'SAVE20');
       showMessage('Discount code applied!', 'success');
   } else {
       showMessage('Total must exceed $100 for a discount.', 'warning');
   }

3. Save the script and test the button. When the total amount exceeds $100, the discount field is automatically populated and a success toast appears.

3. Session Data API (Cross‑Page Persistence)

Sometimes you need to keep data while the user navigates between pages—like a shopping cart ID or a temporary token. The Session Data API stores key/value pairs that survive page changes but are cleared when the session ends (e.g., browser close).

3.1 Core Functions

• setSession(key, value) – Saves value under key for the current user session.
• getSession(key) – Retrieves the stored value for key. Returns undefined if the key does not exist.

3.2 Use Case – Remembering a User’s Preferred Language

1. On the language‑selection page, add a button “Save Preference”.
2. Attach this client‑side script:

   const selectedLang = getField('languageSelect');
   setSession('preferredLanguage', selectedLang);
   showMessage('Language saved for this session.', 'info');

3. On any subsequent page, you can read the value:

   const lang = getSession('preferredLanguage');
   if (lang) {
       // Apply language settings, e.g., load translations
       console.log('User prefers:', lang);
   }

4. Component Visibility Control

Dynamic UI changes are essential for a polished user experience. Qödiak provides a small but powerful set of functions to show, hide, enable, or disable components on the fly.

4.1 Core Functions

• showComponent(componentId) – Makes the component visible.
• hideComponent(componentId) – Hides the component (CSS display:none).
• isComponentVisible(componentId) – Returns true if the component is currently visible.
• enableComponent(componentId) – Allows user interaction (removes disabled attribute).
• disableComponent(componentId) – Prevents interaction (adds disabled attribute).

4.2 Example – Conditional “Additional Details” Section

Suppose you have a checkbox “I have special requirements”. When checked, an extra text area should appear.

1. Give the checkbox the field name hasSpecialReq and the text area the component ID detailsSection.
2. Add an onChange script to the checkbox:

   if (getField('hasSpecialReq') === true) {
       showComponent('detailsSection');
       enableComponent('detailsSection');
   } else {
       hideComponent('detailsSection');
       disableComponent('detailsSection');
       clearField('specialDetails'); // optional: clear hidden input
   }

3. Now the “Additional Details” area only appears when the user indicates they need it.

5. Navigation & Actions

Control the flow of your app with a handful of navigation and action helpers.

5.1 Core Functions

• navigateToPage(pageSlug) – Sends the user to another page within the same Qödiak app.
• submitForm() – Triggers the native form submission process (including server‑side scripts).
• showMessage(message, type) – Displays a toast‑style notification. type can be info, success, warning, or error.

5.2 Scenario – Multi‑Step Wizard

Imagine a three‑step onboarding wizard where each step is a separate page.

1. On the “Next” button of Step 1, add:

   if (getFormData().agreeTerms) {
       submitForm(); // optional: persist data
       navigateToPage('step-2');
   } else {
       showMessage('You must agree to the terms before continuing.', 'error');
   }

2. Repeat similar logic on Step 2, navigating to 'step-3' after validation.
3. On the final “Finish” button, call submitForm() only, letting Qödiak process the complete data set.

6. Event Types

Qödiak components expose a set of standard events that you can bind custom scripts to. Understanding these events helps you decide where to place your logic.

• onClick – Fires when a button or clickable element is pressed.
• onChange – Fires when an input’s value changes (including selects, checkboxes, and text fields).
• onFocus – Fires when an input receives focus.
• onBlur – Fires when an input loses focus.
• onSubmit – Fires when a form is submitted (before the server‑side processing begins).

6.1 Quick Tip

When you need to validate data before a form is sent, attach your script to onSubmit. Returning false from the script aborts the submission.

7. Client‑Side Scripts (Button Custom Scripts)

Button custom scripts run directly in the user’s browser, giving you full access to the DOM, browser storage, and async capabilities.

7.1 What You Can Do

• Manipulate any element on the page via document or window.
• Read/write localStorage and sessionStorage for persistent client data.
• Use navigate() (alias of navigateToPage) for quick page changes.
• Maintain component‑level state with setState(componentId, stateObj) and getState(componentId).
• Leverage async/await for asynchronous operations such as calling external APIs with fetch.
• Access a context object that contains the current app state (e.g., user ID, current page slug).

7.2 Example – Fetching Real‑Time Exchange Rates

1. Create a button “Load Rate” next to a currency field.
2. Attach this async script:

   async function loadRate() {
       const base = getField('baseCurrency');
       const target = getField('targetCurrency');
       try {
           const response = await fetch(`https://api.exchangerate.host/latest?base=${base}&symbols=${target}`);
           const data = await response.json();
           const rate = data.rates[target];
           setField('exchangeRate', rate);
           showMessage('Rate updated successfully.', 'success');
       } catch (e) {
           console.error(e);
           showMessage('Failed to fetch rate.', 'error');
       }
   }
   loadRate();

3. When the user clicks the button, the script contacts the external service, updates the “exchangeRate” field, and shows a notification.

8. Server‑Side Scripts (Jint Sandbox)

Server‑side scripts run in a secure Jint JavaScript engine on Qödiak’s backend. They are ideal for data transformations, calculations, or validation that must stay hidden from the client.

8.1 Execution Limits

• Maximum execution time: 5 seconds
• Memory cap: 50 MB
• Statement limit: 100,000 JavaScript statements per run
• No access to browser APIs (window, document, fetch)
• No access to the .NET Base Class Library

8.2 Typical Use Cases

• Complex tax calculations that rely on server‑side rates.
• Sanitizing or normalizing data before it is stored.
• Generating a unique reference number based on multiple fields.

8.3 Example – Generating a Secure Order Reference

1. Open the form’s Server‑Side Script editor (available under Form Settings → Scripts).
2. Insert the following code:

   // Assume form fields: customerId, orderDate
   function pad(num, size) {
       let s = String(num);
       while (s.length < size) s = "0" + s;
       return s;
   }
   const data = getFormData();
   const datePart = data.orderDate.replace(/-/g, ""); // YYYYMMDD
   const idPart = pad(data.customerId, 6);
   const randomPart = Math.floor(Math.random() * 1000);
   const reference = `ORD-${datePart}-${idPart}-${randomPart}`;
   setField('orderReference', reference); // write back to form
   // No return needed; script ends after 5 s limit.

3. When the form is submitted, the server‑side script creates a unique reference like ORD-20240220-000123-457 and stores it in the hidden field orderReference.

9. Best Practices & Common Pitfalls

9.1 Keep Scripts Small and Focused

Because server‑side scripts have strict execution limits, break large transformations into multiple, reusable functions. Re‑use client‑side utilities (e.g., getFormData()) instead of duplicating logic.

9.2 Validate Before You Submit

Use onSubmit to run quick client‑side checks. If a rule requires secret data (e.g., a private API key), move the validation to a server‑side script where the key cannot be exposed.

9.3 Avoid Direct DOM Manipulation for Core Logic

While you can access document in client scripts, rely on Qödiak’s API (e.g., setField, showComponent) for state changes. Direct DOM changes may become out‑of‑sync with the platform’s internal state.

9.4 Use Session Data Sparingly

Session storage is great for short‑lived data, but remember it is cleared when the browser session ends. For long‑term persistence, consider saving data to a Qödiak collection or external database.

10. Frequently Asked Questions

• Can I call external APIs from server‑side scripts? No. The Jint sandbox does not expose fetch or any network APIs. Use client‑side scripts for external calls, or create a Qödiak integration that runs on the server.
• What happens if a script exceeds the 5‑second limit? Execution is terminated, and an error is logged in the app’s debug console. The user will see the form submission fail unless you catch the error client‑side.
• Do I need to import any libraries to use async/await? No. Modern JavaScript features, including async/await, are natively supported in client‑side scripts.
• Is there a way to debug server‑side scripts? Yes. Use console.log() inside the script; logs appear in the “Script Execution” tab of the Qödiak admin console.

11. Quick Reference Cheat Sheet