Funciones auxiliares HTML

Acceder a las funciones de Ninox directamente desde HTML/JavaScript

Ninext facilita la creación de interfaces HTML integradas con Ninox al permitir llamar directamente a funciones de Ninox desde código HTML o JavaScript. La función html de Ninox permite generar fácilmente componentes HTML dentro de una fórmula, pero interactuar con la lógica de Ninox sigue siendo complicado sin recurrir a soluciones más complejas.

Piense, por ejemplo, en un campo de entrada que debe activar un comportamiento ligado a Ninox. El enfoque tradicional consiste en usar la API REST para enviar los datos al servidor, que luego actualiza la presentación local. Aunque es eficaz, este método tiene varios inconvenientes:

• Complejidad técnica: implementar llamadas a la API exige dominar bien las peticiones HTTP en JavaScript.
• Interactividad limitada: los cambios solo afectan a los datos del servidor, sin posibilidad de provocar actualizaciones locales inmediatas en la interfaz.

Con Ninext obtiene una integración más fluida, que permite enlazar directamente sus componentes HTML/JavaScript con funciones de Ninox. Así aumenta la interactividad de sus aplicaciones sin las limitaciones habituales de las llamadas a la API.

callNinoxFunction

La función callNinoxFunction permite llamar a un script de Ninox desde código JavaScript: un atributo de evento HTML, un bloque de JavaScript nativo… Esta integración ofrece una gran flexibilidad para interactuar con Ninox, en particular para:

• Enviar el valor de un campo de entrada,
• Ejecutar acciones durante eventos como onclick, onfocus u onblur, o al vencer un temporizador (setTimeout),
• Gestionar operaciones asíncronas con funciones de retorno.

Formato y parámetros

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

Valor devuelto

Modo síncrono (sin callback)

La función devuelve de inmediato un objeto JSON con una de las estructuras siguientes:

En caso de éxito:

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

En caso de error:

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

El resultado solo figura en él si la función de Ninox se ha ejecutado sin esperar. Si tiene que esperar (un registro que aún debe cargarse, un proceso asíncrono), el objeto se devuelve antes de que haya terminado, sin resultado. En caso de duda, pase una función de retorno.

Modo asíncrono (con callback)

Cuando se pasa una función de retorno como último argumento, esa función recibe dos parámetros:

callback(error, result)

error se rellena cuando la llamada no ha podido hacerse: función, elemento o registro no encontrado, código que no compila.

Llamar a una función del código global

Con null como segundo argumento, Ninext llama a una función del código global de la base de datos. Se ejecuta sin registro de contexto. Con esta función en el código global:

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

el JavaScript la llama así:

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

Es también la manera de llamar a una función del código global desde un bloque de JavaScript nativo, que no la ve directamente.

Designar la función mediante una referencia

El segundo argumento también puede ser un texto que designe un registro. Ninext busca primero un elemento HTML con ese ID y, después, lee la referencia: la función se ejecuta entonces en el contexto de ese registro (this).

A13 es el identificador completo del registro: el identificador de la tabla seguido del número del registro. Los desencadenadores de tabla llevan su nombre interno: afterCreate, afterUpdate u onClick. El campo se designa por su identificador o por su nombre, escrito sin comillas. Un nombre que contiene paréntesis u otros signos de puntuación hace fallar la llamada (excepción JavaScript): en ese caso, designe el campo por su identificador.

Los argumentos

Los argumentos pasan de JavaScript a Ninox así:

Los valores de un objeto pueden contener comillas, saltos de línea y acentos (a partir de la versión 3.2.0). No envíe ni null ni undefined como argumento: la llamada lanza entonces una excepción JavaScript.

Cómo funciona

La idea principal es ejecutar scripts de Ninox dentro del contexto de una página HTML. Así funciona:

1. Definir la función de Ninox
   En su fórmula de Ninox, defina una función (por ejemplo, myOnblur) que trate los parámetros enviados desde JavaScript. Ninext solo extrae esa función de la fórmula: no ve ni las variables ni las demás funciones declaradas en otras partes de la fórmula. Se ejecuta en el contexto del registro actual (equivalente a this en Ninox).
2. Crear la interfaz HTML
   Incruste un componente HTML (por ejemplo, un campo de entrada) dentro de la fórmula. En el atributo del evento (como onblur), use callNinoxFunction para llamar a la función de Ninox correspondiente y pasarle los parámetros necesarios.
3. Disparar el evento
   Cuando se produce el evento HTML, callNinoxFunction llama a la función de Ninox indicada, la aísla y la ejecuta con el contexto y los parámetros dados (por ejemplo, el valor del campo de entrada).

Este mecanismo simula el comportamiento de un desencadenador nativo y permite además pasar uno o varios parámetros personalizados a la ejecución de la función de Ninox.

Ejemplos de uso

Ejemplo básico: campo de entrada con onblur

1. Definir la función de Ninox

En su fórmula de Ninox, añada la función siguiente:

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

Esta función muestra una alerta con el ID del registro actual y el valor recibido.

2. Integrar el campo de entrada HTML

A continuación, inserte el código HTML siguiente para mostrar un campo de entrada y definir el 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)""
    />
")

Cómo funciona:

• Cuando el usuario sale del campo de entrada (evento onblur),
• Se llama a la función ninext.callNinoxFunction con:
  • 'myOnblur': el nombre de la función de Ninox que hay que ejecutar,
  • this: el propio elemento HTML,
  • this.value: el valor actual del campo de entrada.

Así se garantiza que el script myOnblur de Ninox se ejecute en el contexto del registro actual, como si lo hubiera disparado Ninox de forma nativa, y que reciba además el valor del campo de entrada como parámetro.

Ejemplos de uso síncrono

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

Ejemplos de uso asíncrono (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;
    }
});

¿Cuándo usar las funciones de retorno?

Use el patrón de callback cuando:

• La función de Ninox realiza operaciones asíncronas (llamadas a la API, cálculos complejos),
• Necesita actualizar la interfaz una vez terminada la función,
• Quiere encadenar varias operaciones de forma secuencial.

Puntos clave

• Contextualización:
  La función de Ninox se ejecuta con this representando el registro actual, o el registro designado por la referencia, lo que garantiza la coherencia del contexto de ejecución. Una función del código global se ejecuta sin registro.
• Flexibilidad:
  Puede añadir tantos parámetros como necesite mediante ...args, lo que permite adaptar el comportamiento de la función de Ninox a las necesidades concretas de su aplicación.
• Gestión de errores:
  error señala una llamada que no ha podido hacerse: función, elemento o registro no encontrado, código que no compila. Es un texto, que se muestra tal cual. Para una función que puede tener que esperar, pase una función de retorno.
• Usos múltiples:
  Este mecanismo resulta especialmente útil para integrar interacciones complejas entre la interfaz de usuario HTML/JavaScript y la lógica de negocio definida en Ninox.