Funcions d'ajuda HTML

Accedir a les funcions de Ninox directament des d'HTML/JavaScript

Ninext facilita la creació d'interfícies HTML integrades amb Ninox permetent cridar directament funcions de Ninox des de codi HTML o JavaScript. Si bé la funció html de Ninox permet generar fàcilment components HTML dins d'una fórmula, interactuar amb la lògica de Ninox continua sent complex sense recórrer a solucions més complicades.

Penseu, per exemple, en un camp d'entrada que ha de desencadenar un comportament vinculat a Ninox. L'enfocament tradicional consisteix a fer servir l'API REST per enviar dades al servidor, que després actualitza la visualització local. Tot i que és eficaç, aquest mètode té diversos inconvenients:

• Complexitat tècnica: implementar crides a l'API exigeix un bon coneixement de les peticions HTTP en JavaScript.
• Interactivitat limitada: els canvis només afecten les dades del costat del servidor, sense poder desencadenar actualitzacions locals immediates a la interfície.

Amb Ninext obteniu una integració més fluida, que permet enllaçar directament els vostres components HTML/JavaScript amb funcions de Ninox. Això augmenta la interactivitat de les vostres aplicacions sense les limitacions habituals de les crides a l'API.

callNinoxFunction

La funció callNinoxFunction us permet cridar un script de Ninox des de codi JavaScript. Aquesta integració ofereix una gran flexibilitat per interactuar amb Ninox, en particular per:

• Enviar el valor d'un camp d'entrada,
• Executar accions durant esdeveniments com ara onclick, onfocus, onblur, ontimer, etc.,
• Gestionar operacions asíncrones amb funcions de retorn.

Format i paràmetres

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

Paràmetre	Descripció
functionName	Nom de la funció de Ninox que cal cridar.
htmlElement	Pot ser l'identificador de l'element HTML (per exemple, "myId") o l'element mateix (per exemple, this o document.getElementById("myId")).
...args	Paràmetres addicionals que es passen a la funció de Ninox.
callback	(Opcional) Una funció per tractar el resultat de manera asíncrona. Si s'indica, es cridarà amb (error, result).

Valor retornat

Mode síncron (sense funció de retorn)

La funció retorna un objecte JSON amb una de les estructures següents:

En cas d'èxit:

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

En cas d'error:

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

Mode asíncron (amb funció de retorn)

Quan es passa una funció de retorn com a darrer argument, aquesta funció rep dos paràmetres:

callback(error, result)

Paràmetre	Descripció
error	Un objecte Error si alguna cosa ha anat malament, o undefined en cas d'èxit.
result	El valor retornat per la funció de Ninox, o null si s'ha produït un error.

Com funciona

La idea principal és executar scripts de Ninox dins del context d'una pàgina HTML. Vet aquí com funciona:

1. Definiu la funció de Ninox
   A la vostra fórmula de Ninox, definiu una funció (per exemple, myOnblur) que tractarà els paràmetres passats des de JavaScript. Aquesta funció queda aïllada de la resta de l'script i s'executa dins del context del registre actual (equivalent a this a Ninox).
2. Creeu la interfície HTML
   Incrusteu un component HTML (per exemple, un camp d'entrada) dins de la fórmula. A l'atribut de l'esdeveniment (com ara onblur), feu servir callNinoxFunction per cridar la funció de Ninox corresponent, tot passant-li els paràmetres necessaris.
3. Desencadeneu l'esdeveniment
   Quan es dispara l'esdeveniment HTML, callNinoxFunction crida la funció de Ninox indicada, l'aïlla i l'executa amb el context i els paràmetres donats (per exemple, el valor del camp d'entrada).

Aquest mecanisme simula el comportament d'un activador natiu tot permetent passar un o més paràmetres personalitzats a l'execució de la funció de Ninox.

Exemples d'ús

Exemple bàsic: camp d'entrada amb onblur

1. Definició de la funció de Ninox

A la vostra fórmula de Ninox, afegiu-hi la funció següent:

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

Aquesta funció mostra una alerta amb l'identificador del registre actual i el valor rebut.

2. Integració del camp d'entrada HTML

A continuació, inseriu-hi el codi HTML següent per mostrar un camp d'entrada i definir l'esdeveniment 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)""
    />
")

Com funciona:

• Quan l'usuari surt del camp d'entrada (esdeveniment onblur),
• Es crida la funció ninext.callNinoxFunction amb:
  • 'myOnblur': el nom de la funció de Ninox que cal executar,
  • this: l'element HTML mateix,
  • this.value: el valor actual del camp d'entrada.

Això garanteix que l'script myOnblur de Ninox s'executi en el context del registre actual, com si l'hagués desencadenat Ninox de manera nativa, tot rebent a més el valor del camp d'entrada com a paràmetre.

Exemples d'ús síncron

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

Exemples d'ús asíncron (amb funció de retorn)

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

Quan cal fer servir funcions de retorn?

Feu servir el patró de funció de retorn quan:

• La funció de Ninox fa operacions asíncrones (crides a l'API, càlculs complexos),
• Heu d'actualitzar la interfície un cop la funció ha acabat,
• Voleu encadenar diverses operacions de manera seqüencial.

Punts clau

• Contextualització:
  La funció de Ninox s'executa amb this representant el registre actual, cosa que garanteix la coherència del context d'execució.
• Flexibilitat:
  Podeu afegir tants paràmetres com calgui mitjançant ...args, cosa que permet adaptar el comportament de la funció de Ninox a les necessitats concretes de la vostra aplicació.
• Gestió dels errors:
  Tant el mode síncron com l'asíncron informen clarament dels errors, cosa que facilita la depuració.
• Usos múltiples:
  Aquest mecanisme és especialment útil per integrar interaccions complexes entre la interfície d'usuari HTML/JavaScript i la lògica de negoci definida a Ninox.