Funzioni di aiuto HTML

Accedere alle funzioni Ninox direttamente da HTML/JavaScript

Ninext semplifica la creazione di interfacce HTML integrate con Ninox, permettendo di chiamare direttamente le funzioni Ninox dal codice HTML o JavaScript. La funzione html di Ninox consente di generare facilmente componenti HTML all'interno di una formula, ma interagire con la logica di Ninox resta complesso senza ricorrere a soluzioni più elaborate.

Prendiamo per esempio un campo di input che deve attivare un comportamento legato a Ninox. L'approccio tradizionale consiste nell'usare l'API REST per inviare i dati al server, che poi aggiorna la visualizzazione locale. Per quanto efficace, questo metodo presenta diversi inconvenienti:

• Complessità tecnica: implementare le chiamate all'API richiede una buona conoscenza delle richieste HTTP in JavaScript.
• Interattività limitata: le modifiche riguardano solo i dati lato server, senza la possibilità di attivare aggiornamenti locali immediati nell'interfaccia.

Con Ninext ottenete un'integrazione più fluida, che consente di collegare direttamente i vostri componenti HTML/JavaScript alle funzioni Ninox. Ciò aumenta l'interattività delle vostre applicazioni senza i consueti vincoli delle chiamate all'API.

callNinoxFunction

La funzione callNinoxFunction permette di chiamare uno script Ninox dal codice JavaScript. Questa integrazione offre grande flessibilità nell'interazione con Ninox, in particolare per:

• Inviare il valore di un campo di input,
• Eseguire azioni in occasione di eventi come onclick, onfocus, onblur, ontimer, ecc.,
• Gestire operazioni asincrone con delle callback.

Formato e parametri

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

Parametro	Descrizione
functionName	Nome della funzione Ninox da chiamare.
htmlElement	Può essere l'ID dell'elemento HTML (per esempio "myId") oppure l'elemento stesso (per esempio this o document.getElementById("myId")).
...args	Parametri aggiuntivi da passare alla funzione Ninox.
callback	(Facoltativo) Una funzione per gestire il risultato in modo asincrono. Se fornita, viene chiamata con (error, result).

Valore restituito

Modalità sincrona (senza callback)

La funzione restituisce un oggetto JSON con una delle strutture seguenti:

In caso di successo:

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

In caso di errore:

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

Modalità asincrona (con callback)

Quando una funzione di callback è fornita come ultimo argomento, la callback riceve due parametri:

callback(error, result)

Parametro	Descrizione
error	Un oggetto Error se qualcosa è andato storto, oppure undefined in caso di successo.
result	Il valore restituito dalla funzione Ninox, oppure null se si è verificato un errore.

Come funziona

L'idea principale è eseguire script Ninox nel contesto di una pagina HTML. Ecco come funziona:

1. Definire la funzione Ninox
   Nella vostra formula Ninox, definite una funzione (per esempio myOnblur) che gestirà i parametri passati da JavaScript. Questa funzione resta isolata dal resto dello script e viene eseguita nel contesto del record corrente (equivalente a this in Ninox).
2. Creare l'interfaccia HTML
   Incorporate un componente HTML (per esempio un campo di input) nella formula. Nell'attributo dell'evento (come onblur), usate callNinoxFunction per chiamare la funzione Ninox corrispondente, passando i parametri necessari.
3. Attivare l'evento
   Quando l'evento HTML si verifica, callNinoxFunction chiama la funzione Ninox indicata, la isola e la esegue con il contesto e i parametri forniti (per esempio il valore del campo di input).

Questo meccanismo simula il comportamento di un trigger nativo, consentendo al tempo stesso di passare uno o più parametri personalizzati all'esecuzione della funzione Ninox.

Esempi d'uso

Esempio di base: campo di input con onblur

1. Definire la funzione Ninox

Nella vostra formula Ninox, aggiungete la funzione seguente:

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

Questa funzione mostra un avviso con l'ID del record corrente e il valore passato.

2. Integrare il campo di input HTML

Inserite poi il codice HTML seguente per visualizzare un campo di input e definire l'evento 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)""
    />
")

Come funziona:

• Quando un utente esce dal campo di input (evento onblur),
• La funzione ninext.callNinoxFunction viene chiamata con:
  • 'myOnblur': il nome della funzione Ninox da eseguire,
  • this: l'elemento HTML stesso,
  • this.value: il valore corrente del campo di input.

In questo modo lo script Ninox myOnblur viene eseguito nel contesto del record corrente, come se fosse stato attivato nativamente da Ninox, ricevendo al contempo come parametro il valore del campo di input.

Esempi d'uso in modalità sincrona

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

Esempi d'uso in modalità asincrona (con 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;
    }
});

Quando usare le callback?

Usate il modello a callback quando:

• La funzione Ninox esegue operazioni asincrone (chiamate all'API, calcoli complessi),
• Dovete aggiornare l'interfaccia dopo il completamento della funzione,
• Volete concatenare più operazioni in sequenza.

Punti chiave

• Contestualizzazione:
  La funzione Ninox viene eseguita con this che rappresenta il record corrente, garantendo la coerenza del contesto di esecuzione.
• Flessibilità:
  Potete aggiungere tutti i parametri necessari tramite ...args, adattando il comportamento della funzione Ninox alle esigenze specifiche della vostra applicazione.
• Gestione degli errori:
  Sia la modalità sincrona sia quella asincrona segnalano chiaramente gli errori, agevolando il debug.
• Usi molteplici:
  Questo meccanismo è particolarmente utile per integrare interazioni complesse tra l'interfaccia utente HTML/JavaScript e la logica applicativa definita in Ninox.