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: un attributo di evento HTML, un blocco Native JS… 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 o onblur, oppure alla scadenza di un timer (setTimeout),
• Gestire operazioni asincrone con delle callback.

Formato e parametri

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

Valore restituito

Modalità sincrona (senza callback)

La funzione restituisce subito 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
}

Il risultato vi compare solo se la funzione Ninox è stata eseguita senza attendere. Se deve aspettare (un record ancora da caricare, un'elaborazione asincrona), l'oggetto viene restituito prima che abbia finito, senza risultato. Nel dubbio, passate una callback.

Modalità asincrona (con callback)

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

callback(error, result)

error è valorizzato quando la chiamata non è potuta avvenire: funzione, elemento o record introvabile, codice che non si compila.

Chiamare una funzione del codice globale

Con null come secondo argomento, Ninext chiama una funzione del codice globale del database. Viene eseguita senza record di contesto. Con questa funzione nel codice globale:

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

il JavaScript la chiama così:

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

È anche il modo di chiamare una funzione del codice globale da un blocco Native JS, che non la vede direttamente.

Designare la funzione con un riferimento

Il secondo argomento può anche essere un testo che designa un record. Ninext vi cerca prima un elemento HTML con questo ID, poi legge il riferimento: la funzione viene allora eseguita nel contesto di questo record (this).

A13 è l'ID completo del record: l'ID della tabella seguito dal numero del record. I trigger di tabella portano il loro nome interno: afterCreate, afterUpdate o onClick. Il campo si designa con il suo ID o con il suo nome, scritto senza virgolette. Un nome che contiene parentesi o altri segni di punteggiatura fa fallire la chiamata (eccezione JavaScript): designate allora il campo con il suo ID.

Gli argomenti

Gli argomenti passano da JavaScript a Ninox così:

I valori di un oggetto possono contenere virgolette, a capo e accenti (a partire dalla versione 3.2.0). Non inviate né null né undefined come argomento: la chiamata solleva allora un'eccezione JavaScript.

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. Ninext estrae dalla formula solo questa funzione: non vede né le variabili né le altre funzioni dichiarate altrove nella formula. 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);
    } 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;
    }
});

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, o il record designato dal riferimento, garantendo la coerenza del contesto di esecuzione. Una funzione del codice globale viene eseguita senza record.
• Flessibilità:
  Potete aggiungere tutti i parametri necessari tramite ...args, adattando il comportamento della funzione Ninox alle esigenze specifiche della vostra applicazione.
• Gestione degli errori:
  error segnala una chiamata che non è potuta avvenire: funzione, elemento o record introvabile, codice che non si compila. È un testo, da mostrare così com'è. Per una funzione che può dover attendere, passate una callback.
• Usi molteplici:
  Questo meccanismo è particolarmente utile per integrare interazioni complesse tra l'interfaccia utente HTML/JavaScript e la logica applicativa definita in Ninox.