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: atrybutu zdarzenia HTML, bloku Natywny JS… 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 lub onblur albo po upływie czasu minutnika (setTimeout),
• obsługi operacji asynchronicznych za pomocą callbacków.

Format i parametry

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

Wartość zwracana

Tryb synchroniczny (bez callbacku)

Funkcja natychmiast 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
}

Wynik znajduje się w nim tylko wtedy, gdy funkcja Ninox wykonała się bez czekania. Jeśli musi poczekać (na rekord, który trzeba jeszcze załadować, na operację asynchroniczną), obiekt jest zwracany, zanim skończy, bez wyniku. W razie wątpliwości proszę przekazać callback.

Tryb asynchroniczny (z callbackiem)

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

callback(error, result)

error jest ustawiany, gdy wywołanie nie mogło się odbyć: nie znaleziono funkcji, elementu lub rekordu albo kod się nie kompiluje.

Wywołanie funkcji kodu globalnego

Gdy drugim argumentem jest null, Ninext wywołuje funkcję kodu globalnego bazy. Wykonuje się ona bez rekordu kontekstu. Przy takiej funkcji w kodzie globalnym:

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

JavaScript wywołuje ją w ten sposób:

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

W ten sposób można też wywołać funkcję kodu globalnego z bloku Natywny JS, który nie widzi jej bezpośrednio.

Wskazanie funkcji przez odwołanie

Drugim argumentem może być także tekst wskazujący rekord. Ninext szuka najpierw elementu HTML o takim identyfikatorze, a następnie odczytuje odwołanie: funkcja wykonuje się wtedy w kontekście tego rekordu (this).

A13 to pełny identyfikator rekordu: identyfikator tabeli, po którym następuje numer rekordu. Wyzwalacze tabeli noszą swoją nazwę wewnętrzną: afterCreate, afterUpdate lub onClick. Pole wskazuje się za pomocą jego identyfikatora lub nazwy, zapisanej bez cudzysłowów. Nazwa zawierająca nawiasy lub inne znaki interpunkcyjne powoduje niepowodzenie wywołania (wyjątek JavaScript): należy wtedy wskazać pole za pomocą jego identyfikatora.

Argumenty

Argumenty przechodzą z JavaScriptu do Ninox w następujący sposób:

Wartości obiektu mogą zawierać cudzysłowy, znaki nowego wiersza i litery ze znakami diakrytycznymi (od wersji 3.2.0). Nie należy przekazywać jako argumentu ani null, ani undefined: wywołanie zgłasza wtedy wyjątek JavaScript.

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. Ninext wyodrębnia z formuły tylko tę funkcję: nie widzi ona ani zmiennych, ani innych funkcji zadeklarowanych w innym miejscu formuły. 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);
    } 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;
    }
});

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 albo rekord wskazany przez odwołanie, co zapewnia spójność kontekstu wykonania. Funkcja kodu globalnego wykonuje się bez rekordu.
• 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:
  error sygnalizuje wywołanie, które nie mogło się odbyć: nie znaleziono funkcji, elementu lub rekordu albo kod się nie kompiluje. Jest to tekst, który należy wyświetlić bez zmian. W przypadku funkcji, która może musieć poczekać, proszę przekazać callback.
• 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.