Funkcje pomocnicze HTML

Dostęp do funkcji Ninox bezpośrednio z HTML/JavaScript

Ninext ułatwia tworzenie interfejsów HTML zintegrowanych z Ninox, pozwalając wywoływać funkcje Ninox bezpośrednio z kodu HTML lub JavaScript. Funkcja html w Ninox pozwala wprawdzie łatwo generować komponenty HTML wewnątrz formuły, ale interakcja z logiką Ninox pozostaje skomplikowana bez uciekania się do bardziej złożonych rozwiązań.

Weźmy na przykład pole wejściowe, które ma wyzwolić zachowanie powiązane z Ninox. Tradycyjne podejście polega na użyciu interfejsu REST API do wysłania danych na serwer, który następnie aktualizuje lokalny widok. Metoda ta jest skuteczna, ale ma kilka wad:

• Złożoność techniczna: implementacja wywołań API wymaga dobrej znajomości żądań HTTP w JavaScripcie.
• Ograniczona interaktywność: zmiany dotyczą wyłącznie danych po stronie serwera, bez możliwości natychmiastowej aktualizacji interfejsu lokalnie.

Dzięki Ninext otrzymują Państwo płynniejszą integrację, pozwalającą bezpośrednio łączyć komponenty HTML/JavaScript z funkcjami Ninox. Zwiększa to interaktywność aplikacji bez zwykłych ograniczeń wywołań API.

callNinoxFunction

Funkcja callNinoxFunction pozwala wywołać skrypt Ninox z kodu JavaScript. Ta integracja daje dużą swobodę w interakcji z Ninox, w szczególności do:

• wysyłania wartości pola wejściowego,
• wykonywania działań przy zdarzeniach takich jak onclick, onfocus, onblur, ontimer itp.,
• obsługi operacji asynchronicznych za pomocą callbacków.

Format i parametry

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

Parametr	Opis
functionName	Nazwa wywoływanej funkcji Ninox.
htmlElement	Może to być identyfikator elementu HTML (np. "myId") albo sam element (np. this lub document.getElementById("myId")).
...args	Dodatkowe parametry przekazywane do funkcji Ninox.
callback	(Opcjonalnie) Funkcja obsługująca wynik asynchronicznie. Jeśli zostanie podana, będzie wywołana z (error, result).

Wartość zwracana

Tryb synchroniczny (bez callbacku)

Funkcja zwraca obiekt JSON o jednej z poniższych struktur:

W razie powodzenia:

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

W razie błędu:

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

Tryb asynchroniczny (z callbackiem)

Gdy jako ostatni argument podano funkcję zwrotną, otrzymuje ona dwa parametry:

callback(error, result)

Parametr	Opis
error	Obiekt Error, jeśli coś poszło nie tak, albo undefined w razie powodzenia.
result	Wartość zwrócona przez funkcję Ninox albo null, jeśli wystąpił błąd.

Jak to działa

Główna idea polega na wykonywaniu skryptów Ninox w kontekście strony HTML. Oto jak to przebiega:

1. Zdefiniowanie funkcji Ninox
   W formule Ninox definiują Państwo funkcję (np. myOnblur), która obsłuży parametry przekazane z JavaScriptu. Funkcja ta pozostaje odizolowana od reszty skryptu i wykonuje się w kontekście bieżącego rekordu (odpowiednik this w Ninox).
2. Utworzenie interfejsu HTML
   Wewnątrz formuły osadzają Państwo komponent HTML (np. pole wejściowe). W atrybucie zdarzenia (takim jak onblur) używają Państwo callNinoxFunction, aby wywołać odpowiednią funkcję Ninox, przekazując potrzebne parametry.
3. Wyzwolenie zdarzenia
   Gdy zdarzenie HTML zostaje wyzwolone, callNinoxFunction wywołuje wskazaną funkcję Ninox, izoluje ją i wykonuje z podanym kontekstem oraz parametrami (np. wartością pola wejściowego).

Mechanizm ten naśladuje działanie natywnego wyzwalacza, pozwalając jednocześnie przekazać do wykonania funkcji Ninox jeden lub więcej własnych parametrów.

Przykłady zastosowania

Przykład podstawowy: pole wejściowe ze zdarzeniem onblur

1. Zdefiniowanie funkcji Ninox

W formule Ninox dodają Państwo następującą funkcję:

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

Funkcja ta wyświetla alert z identyfikatorem bieżącego rekordu i przekazaną wartością.

2. Osadzenie pola wejściowego HTML

Następnie wstawiają Państwo poniższy kod HTML, aby wyświetlić pole wejściowe i zdefiniować zdarzenie 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)""
    />
")

Jak to działa:

• Gdy użytkownik opuszcza pole wejściowe (zdarzenie onblur),
• wywoływana jest funkcja ninext.callNinoxFunction z:
  • 'myOnblur': nazwą funkcji Ninox do wykonania,
  • this: samym elementem HTML,
  • this.value: bieżącą wartością pola wejściowego.

Dzięki temu skrypt Ninox myOnblur wykonuje się w kontekście bieżącego rekordu, tak jakby został wyzwolony natywnie przez Ninox, otrzymując dodatkowo wartość pola wejściowego jako parametr.

Przykłady użycia synchronicznego

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

Przykłady użycia asynchronicznego (z callbackiem)

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

Kiedy używać callbacków?

Wzorca z callbackiem warto użyć, gdy:

• funkcja Ninox wykonuje operacje asynchroniczne (wywołania API, złożone obliczenia),
• trzeba zaktualizować interfejs po zakończeniu działania funkcji,
• chcą Państwo połączyć kilka operacji w sekwencję.

Najważniejsze punkty

• Kontekst:
  Funkcja Ninox wykonuje się z this reprezentującym bieżący rekord, co zapewnia spójność kontekstu wykonania.
• Elastyczność:
  Można dodać dowolną liczbę parametrów za pomocą ...args, dostosowując zachowanie funkcji Ninox do konkretnych potrzeb aplikacji.
• Obsługa błędów:
  Zarówno tryb synchroniczny, jak i asynchroniczny zapewniają czytelne zgłaszanie błędów, co ułatwia debugowanie.
• Wiele zastosowań:
  Mechanizm ten jest szczególnie przydatny do integrowania złożonych interakcji między interfejsem HTML/JavaScript a logiką biznesową zdefiniowaną w Ninox.