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: einem HTML-Ereignisattribut, einem Native JS-Block … 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 oder onblur oder beim Ablauf eines Timers (setTimeout),
• den Umgang mit asynchronen Operationen über Callbacks.

Format und Parameter

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

Rückgabewert

Synchroner Modus (ohne Callback)

Die Funktion gibt sofort 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
}

Das Ergebnis ist darin nur enthalten, wenn die Ninox-Funktion ohne Wartezeit ausgeführt wurde. Muss sie warten (ein noch zu ladender Datensatz, eine asynchrone Verarbeitung), wird das Objekt zurückgegeben, bevor sie fertig ist, ohne Ergebnis. Übergeben Sie im Zweifel einen Callback.

Asynchroner Modus (mit Callback)

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

callback(error, result)

error ist gesetzt, wenn der Aufruf nicht erfolgen konnte: Funktion, Element oder Datensatz nicht gefunden, Code, der sich nicht kompilieren lässt.

Eine Funktion des globalen Codes aufrufen

Mit null als zweitem Argument ruft Ninext eine Funktion des globalen Codes der Datenbank auf. Sie wird ohne Kontext-Datensatz ausgeführt. Mit dieser Funktion im globalen Code:

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

ruft das JavaScript sie so auf:

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

Auf diese Weise lässt sich auch aus einem Native JS-Block, der sie nicht direkt sieht, eine Funktion des globalen Codes aufrufen.

Die Funktion über einen Verweis bezeichnen

Das zweite Argument kann auch ein Text sein, der einen Datensatz bezeichnet. Ninext sucht darin zuerst ein HTML-Element mit dieser ID und liest dann den Verweis: Die Funktion wird dann im Kontext dieses Datensatzes (this) ausgeführt.

A13 ist die vollständige ID des Datensatzes: die ID der Tabelle, gefolgt von der Nummer des Datensatzes. Die Trigger einer Tabelle tragen ihren internen Namen: afterCreate, afterUpdate oder onClick. Das Feld wird über seine ID oder seinen Namen bezeichnet, ohne Anführungszeichen geschrieben. Ein Name, der Klammern oder andere Satzzeichen enthält, lässt den Aufruf scheitern (JavaScript-Ausnahme): Bezeichnen Sie das Feld dann über seine ID.

Die Argumente

Die Argumente gelangen so von JavaScript zu Ninox:

Die Werte eines Objekts dürfen Anführungszeichen, Zeilenumbrüche und Akzente enthalten (ab Version 3.2.0). Übergeben Sie weder null noch undefined als Argument: Der Aufruf löst dann eine JavaScript-Ausnahme aus.

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. Ninext entnimmt der Formel nur diese Funktion: Sie sieht weder die Variablen noch die anderen Funktionen, die an anderer Stelle in der Formel deklariert sind. Sie 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);
    } 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;
    }
});

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 oder als dem durch den Verweis bezeichneten Datensatz, was einen einheitlichen Ausführungskontext sichert. Eine Funktion des globalen Codes läuft ohne Datensatz.
• 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:
  error meldet einen Aufruf, der nicht erfolgen konnte: Funktion, Element oder Datensatz nicht gefunden, Code, der sich nicht kompilieren lässt. Es ist ein Text, der unverändert angezeigt wird. Übergeben Sie für eine Funktion, die unter Umständen warten muss, einen Callback.
• Vielseitigkeit:
  Dieser Mechanismus ist besonders nützlich, um komplexe Wechselwirkungen zwischen der HTML/JavaScript-Oberfläche und der in Ninox definierten Geschäftslogik umzusetzen.