HTML-Hilfsfunktionen

Ninox-Funktionen direkt aus HTML/JavaScript aufrufen

Ninext erleichtert das Erstellen von HTML-Oberflächen, die in Ninox eingebunden sind, indem es erlaubt, Ninox-Funktionen direkt aus HTML- oder JavaScript-Code aufzurufen. Zwar lassen sich mit der Ninox-Funktion html HTML-Komponenten bequem innerhalb einer Formel erzeugen, doch das Zusammenspiel mit der Ninox-Logik bleibt ohne aufwendigere Lösungen kompliziert.

Nehmen wir als Beispiel ein Eingabefeld, das ein an Ninox gebundenes Verhalten auslösen soll. Der herkömmliche Weg führt über die REST-API: Die Daten werden an den Server geschickt, der anschließend die lokale Anzeige aktualisiert. Diese Methode funktioniert, hat aber mehrere Nachteile:

• Technische Komplexität: Für API-Aufrufe braucht man solide Kenntnisse über HTTP-Anfragen in JavaScript.
• Eingeschränkte Interaktivität: Änderungen betreffen nur die Daten auf dem Server; unmittelbare lokale Aktualisierungen der Oberfläche lassen sich so nicht auslösen.

Mit Ninext gelingt die Einbindung flüssiger: Sie verbinden Ihre HTML/JavaScript-Komponenten direkt mit Ninox-Funktionen. Das erhöht die Interaktivität Ihrer Anwendungen, ohne die üblichen Einschränkungen von API-Aufrufen.

callNinoxFunction

Mit der Funktion callNinoxFunction rufen Sie ein Ninox-Skript aus JavaScript-Code auf. Diese Einbindung bietet große Freiheit im Umgang mit Ninox, insbesondere für:

• das Senden des Wertes eines Eingabefeldes,
• das Ausführen von Aktionen bei Ereignissen wie onclick, onfocus, onblur, ontimer usw.,
• den Umgang mit asynchronen Operationen über Callbacks.

Format und Parameter

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

Parameter	Beschreibung
functionName	Name der aufzurufenden Ninox-Funktion.
htmlElement	Entweder die ID des HTML-Elements (z. B. "myId") oder das Element selbst (z. B. this oder document.getElementById("myId")).
...args	Zusätzliche Parameter, die an die Ninox-Funktion übergeben werden.
callback	(Optional) Eine Funktion, die das Ergebnis asynchron entgegennimmt. Wird sie angegeben, so wird sie mit (error, result) aufgerufen.

Rückgabewert

Synchroner Modus (ohne Callback)

Die Funktion gibt ein JSON-Objekt mit einer der folgenden Strukturen zurück:

Bei Erfolg:

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

Bei Fehler:

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

Asynchroner Modus (mit Callback)

Wird als letztes Argument eine Callback-Funktion übergeben, so erhält dieser Callback zwei Parameter:

callback(error, result)

Parameter	Beschreibung
error	Ein Error-Objekt, falls etwas schiefgegangen ist, sonst undefined bei Erfolg.
result	Der von der Ninox-Funktion zurückgegebene Wert oder null, falls ein Fehler aufgetreten ist.

Funktionsweise

Der Grundgedanke ist, Ninox-Skripte im Kontext einer HTML-Seite auszuführen. So läuft es ab:

1. Die Ninox-Funktion definieren
   Legen Sie in Ihrer Ninox-Formel eine Funktion an (z. B. myOnblur), die die aus JavaScript übergebenen Parameter verarbeitet. Diese Funktion bleibt vom übrigen Skript getrennt und läuft im Kontext des aktuellen Datensatzes (entspricht this in Ninox).
2. Die HTML-Oberfläche erstellen
   Betten Sie in die Formel eine HTML-Komponente ein (z. B. ein Eingabefeld). Rufen Sie im Ereignisattribut (etwa onblur) mit callNinoxFunction die zugehörige Ninox-Funktion auf und übergeben Sie die nötigen Parameter.
3. Das Ereignis auslösen
   Tritt das HTML-Ereignis ein, ruft callNinoxFunction die angegebene Ninox-Funktion auf, isoliert sie und führt sie mit dem gegebenen Kontext und den Parametern aus (z. B. dem Wert des Eingabefeldes).

Dieser Mechanismus ahmt das Verhalten eines nativen Triggers nach und erlaubt zugleich, der Ausführung der Ninox-Funktion einen oder mehrere eigene Parameter mitzugeben.

Anwendungsbeispiele

Einfaches Beispiel: Eingabefeld mit onblur

1. Die Ninox-Funktion definieren

Fügen Sie Ihrer Ninox-Formel die folgende Funktion hinzu:

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

Diese Funktion zeigt eine Meldung mit der ID des aktuellen Datensatzes und dem übergebenen Wert an.

2. Das HTML-Eingabefeld einbinden

Fügen Sie anschließend den folgenden HTML-Code ein, um ein Eingabefeld anzuzeigen und das Ereignis onblur zu definieren:

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)""
    />
")

So funktioniert es:

• Verlässt der Benutzer das Eingabefeld (Ereignis onblur),
• wird die Funktion ninext.callNinoxFunction aufgerufen, und zwar mit:
  • 'myOnblur': dem Namen der auszuführenden Ninox-Funktion,
  • this: dem HTML-Element selbst,
  • this.value: dem aktuellen Wert des Eingabefeldes.

So läuft das Ninox-Skript myOnblur im Kontext des aktuellen Datensatzes, als wäre es nativ von Ninox ausgelöst worden – und erhält zugleich den Wert des Eingabefeldes als Parameter.

Beispiele für den synchronen Einsatz

// 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;
}

Beispiele für den asynchronen Einsatz (mit Callback)

// Basic callback usage
ninext.callNinoxFunction('myFunction', this, 'param1', function(error, result) {
    if (error) {
        console.error('Error:', error.message);
    } 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.message);
        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;
    }
});

Wann sollte man Callbacks verwenden?

Verwenden Sie das Callback-Muster, wenn:

• die Ninox-Funktion asynchrone Operationen ausführt (API-Aufrufe, aufwendige Berechnungen),
• Sie die Oberfläche aktualisieren müssen, nachdem die Funktion beendet ist,
• Sie mehrere Operationen nacheinander verketten möchten.

Das Wichtigste in Kürze

• Kontextbindung:
  Die Ninox-Funktion läuft mit this als aktuellem Datensatz, was einen einheitlichen Ausführungskontext sichert.
• Flexibilität:
  Über ...args können Sie beliebig viele Parameter hinzufügen und so das Verhalten der Ninox-Funktion an die Anforderungen Ihrer Anwendung anpassen.
• Fehlerbehandlung:
  Sowohl der synchrone als auch der asynchrone Modus melden Fehler eindeutig, was die Fehlersuche erleichtert.
• Vielseitigkeit:
  Dieser Mechanismus ist besonders nützlich, um komplexe Wechselwirkungen zwischen der HTML/JavaScript-Oberfläche und der in Ninox definierten Geschäftslogik umzusetzen.