HTML 輔助函式

直接從 HTML/JavaScript 呼叫 Ninox 函式

Ninext 讓您可以從 HTML 或 JavaScript 程式碼直接呼叫 Ninox 函式，因而更容易打造與 Ninox 整合的 HTML 介面。雖然 Ninox 的 html 函式已能在公式中輕鬆產生 HTML 元件，但若不動用更複雜的解法，要與 Ninox 的邏輯互動仍相當麻煩。

以一個需要觸發 Ninox 相關行為的輸入欄位為例。傳統做法是透過 REST API 把資料送到伺服器，再由伺服器更新本機的顯示。這個方法確實有效，卻有幾個缺點：

• 技術門檻高：實作 API 呼叫需要對 JavaScript 中的 HTTP 請求有紮實的理解。
• 互動性受限：變更只影響伺服器端的資料，無法立即在介面上觸發本機更新。

有了 Ninext，整合就順暢多了：您可以把 HTML/JavaScript 元件直接連結到 Ninox 函式，在沒有 API 呼叫種種限制的情況下，提升應用程式的互動性。

callNinoxFunction

callNinoxFunction 函式讓您可以從 JavaScript 程式碼呼叫 Ninox 腳本：HTML 事件屬性、原生 JS 區塊……這樣的整合在與 Ninox 互動時帶來極大的彈性，特別適用於：

• 傳送輸入欄位的值，
• 在 onclick、onfocus 或 onblur 等事件發生時，或在計時器（setTimeout）到期時執行動作，
• 以回呼處理非同步作業。

格式與參數

ninext.callNinoxFunction(functionName, htmlElement, ...args, [callback])

回傳值

同步模式（不使用回呼）

此函式會立即傳回一個 JSON 物件，結構為下列其中一種：

成功時：

{
    result: <value>    // The value returned by the Ninox function
}

發生錯誤時：

{
    error: <string>    // Error message describing what went wrong
}

只有在 Ninox 函式不必等待就執行完畢時，其中才會有結果。若它必須等待（某筆記錄尚待載入、非同步處理），物件會在它完成之前就傳回，不含結果。若有疑慮，請傳入回呼函式。

非同步模式（使用回呼）

當最後一個引數是回呼函式時，該回呼會收到兩個參數：

callback(error, result)

當呼叫無法進行時，error 就會有內容：找不到函式、元素或記錄，或是程式碼無法編譯。

呼叫全域程式碼中的函式

以 null 作為第二個引數時，Ninext 會呼叫資料庫全域程式碼中的函式。它在沒有任何記錄作為環境的情況下執行。若全域程式碼中有這個函式：

function greet(name : text) do
    alert("Hello " + name)
end;

JavaScript 便這樣呼叫它：

ninext.callNinoxFunction('greet', null, 'Sofia');

這也是從 原生 JS 區塊呼叫全域程式碼函式的方法，因為該區塊無法直接看到它。

以參照指定函式

第二個引數也可以是指定某筆記錄的文字。Ninext 會先在其中尋找具有此 ID 的 HTML 元素，然後讀取該參照：函式便會在這筆記錄的環境（this）中執行。

A13 是記錄的完整 ID：表格的 ID 後面接著記錄的編號。表格觸發器以其內部名稱表示：afterCreate、afterUpdate 或 onClick。欄位則以其 ID 或名稱指定，不加引號。名稱中若含有括號或其他標點符號，呼叫就會失敗（JavaScript 例外）：此時請改以 ID 指定欄位。

引數

引數從 JavaScript 傳到 Ninox 的方式如下：

物件的值可以包含引號、換行與重音字母（自 3.2.0 版起）。請勿以 null 或 undefined 作為引數：呼叫會因此擲出 JavaScript 例外。

運作方式

核心概念是在 HTML 頁面的環境中執行 Ninox 腳本。運作方式如下：

1. 定義 Ninox 函式
   在您的 Ninox 公式中定義一個函式（例如 myOnblur），用來處理從 JavaScript 傳來的參數。Ninext 只會從公式中取出這個函式：它看不到公式中其他地方宣告的變數或其他函式。它在目前記錄的環境中執行（相當於 Ninox 中的 this）。
2. 建立 HTML 介面
   在公式中嵌入一個 HTML 元件（例如輸入欄位）。在事件屬性（例如 onblur）中，用 callNinoxFunction 呼叫對應的 Ninox 函式，並傳入所需的參數。
3. 觸發事件
   當 HTML 事件被觸發時，callNinoxFunction 會呼叫指定的 Ninox 函式，將它隔離出來，並帶著給定的環境與參數（例如輸入欄位的值）執行。

這套機制模擬了原生觸發器的行為，同時還能把一個或多個自訂參數傳給要執行的 Ninox 函式。

使用範例

基本範例：帶 onblur 的輸入欄位

1. 定義 Ninox 函式

在您的 Ninox 公式中加入下列函式：

function myOnblur(inputValue : text) do
    alert("Input of record " + this.Id + " is " + inputValue)
end;

這個函式會顯示一則警示，內容是目前記錄的 ID 與傳入的值。

2. 整合 HTML 輸入欄位

接著插入下列 HTML 程式碼，以顯示一個輸入欄位並定義 onblur 事件：

function myOnblur(inputValue : text) do
    alert("Input of record " + this.Id + " is " + inputValue)
end;

html("
    <input
        class='nx-input nx-input--editing'
        style='width: 100%; height: 100%;'
        onblur=""ninext.callNinoxFunction('myOnblur', this, this.value)""
    />
")

運作方式：

• 當使用者離開輸入欄位時（onblur 事件），
• ninext.callNinoxFunction 函式會以下列引數被呼叫：
  • 'myOnblur'：要執行的 Ninox 函式名稱，
  • this：HTML 元素本身，
  • this.value：輸入欄位目前的值。

如此一來，Ninox 腳本 myOnblur 就會在目前記錄的環境中執行，彷彿是由 Ninox 原生觸發的一樣，同時還能把輸入欄位的值當作參數收下。

同步用法範例

// Basic call - checking the result
const response = ninext.callNinoxFunction('myFunction', this, 'param1');
if (response.error) {
    console.error('Error:', response.error);
} else {
    console.log('Result:', response.result);
}

// Direct access to result (when you're confident there's no error)
alert(ninext.callNinoxFunction('getValue', this).result);

// With error handling
const res = ninext.callNinoxFunction('calculateTotal', 'myButtonId', 100, 0.2);
if (res.error) {
    alert('Calculation failed: ' + res.error);
} else {
    document.getElementById('total').textContent = res.result;
}

非同步用法範例（使用回呼）

// Basic callback usage
ninext.callNinoxFunction('myFunction', this, 'param1', function(error, result) {
    if (error) {
        console.error('Error:', error);
    } else {
        console.log('Result:', result);
    }
});

// Update UI after async operation
ninext.callNinoxFunction('loadData', 'myContainer', recordId, function(error, result) {
    if (error) {
        alert('Failed to load data: ' + error);
        return;
    }
    document.getElementById('output').innerHTML = result;
});

// Using arrow function syntax
ninext.callNinoxFunction('calculateTotal', this, 100, 0.2, (error, result) => {
    if (!error) {
        document.getElementById('total').textContent = result;
    }
});

何時該用回呼？

在下列情況請採用回呼的寫法：

• Ninox 函式會執行非同步作業（API 呼叫、複雜運算），
• 您需要在函式完成後更新使用者介面，
• 您想把多個作業依序串接起來。

重點

• 環境脈絡：
  Ninox 函式執行時，this 代表目前的記錄，或參照所指定的記錄，確保執行環境的一致性。全域程式碼中的函式則在沒有記錄的情況下執行。
• 彈性：
  您可以透過 ...args 視需要加入任意數量的參數，讓 Ninox 函式的行為配合您應用程式的具體需求。
• 錯誤處理：
  error 代表無法進行的呼叫：找不到函式、元素或記錄，或是程式碼無法編譯。它是文字，照原樣顯示即可。對於可能需要等待的函式，請傳入回呼函式。
• 多樣用途：
  這套機制特別適合把 HTML/JavaScript 使用者介面與 Ninox 中定義的商業邏輯做複雜的整合。