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: un atribut d'esdeveniment HTML, un bloc Native JS… 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 o onblur, o quan venç un temporitzador (setTimeout),
• Gestionar operacions asíncrones amb funcions de retorn.

Format i paràmetres

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

Valor retornat

Mode síncron (sense funció de retorn)

La funció retorna immediatament 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
}

El resultat només hi figura si la funció de Ninox s'ha executat sense esperar. Si ha d'esperar (un registre que encara s'ha de carregar, un tractament asíncron), l'objecte es retorna abans que hagi acabat, sense resultat. En cas de dubte, passeu-hi una funció de retorn.

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)

error s'omple quan la crida no s'ha pogut fer: funció, element o registre no trobat, codi que no es compila.

Cridar una funció del codi global

Amb null com a segon argument, Ninext crida una funció del codi global de la base de dades. S'executa sense registre de context. Amb aquesta funció al codi global:

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

el JavaScript la crida així:

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

També és la manera de cridar una funció del codi global des d'un bloc Native JS, que no la veu directament.

Designar la funció amb una referència

El segon argument també pot ser un text que designi un registre. Ninext hi cerca primer un element HTML que porti aquest identificador i, després, llegeix la referència: la funció s'executa aleshores en el context d'aquest registre (this).

A13 és l'identificador complet del registre: l'identificador de la taula seguit del número del registre. Els activadors de taula porten el seu nom intern: afterCreate, afterUpdate o onClick. El camp es designa pel seu identificador o pel seu nom, escrit sense cometes. Un nom que conté parèntesis o altres signes de puntuació fa fallar la crida (excepció JavaScript): en aquest cas, designeu el camp pel seu identificador.

Els arguments

Els arguments passen de JavaScript a Ninox així:

Els valors d'un objecte poden contenir cometes, salts de línia i accents (a partir de la versió 3.2.0). No envieu ni null ni undefined com a argument: la crida llança aleshores una excepció JavaScript.

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. Ninext només extreu aquesta funció de la fórmula: no veu ni les variables ni les altres funcions declarades en altres llocs de la fórmula. 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);
    } 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;
    }
});

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, o el registre designat per la referència, cosa que garanteix la coherència del context d'execució. Una funció del codi global s'executa sense registre.
• 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:
  error assenyala una crida que no s'ha pogut fer: funció, element o registre no trobat, codi que no es compila. És un text, que cal mostrar tal qual. Per a una funció que pot haver d'esperar, passeu-hi una funció de retorn.
• 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.