Fonctions d'aide HTML

Accéder aux fonctions Ninox directement depuis HTML/JavaScript

Ninext facilite la création d'interfaces HTML intégrées à Ninox en permettant d'appeler directement des fonctions Ninox depuis du code HTML ou JavaScript. Si la fonction html de Ninox permet de produire facilement des composants HTML dans une formule, dialoguer avec la logique Ninox reste compliqué sans recourir à des solutions plus lourdes.

Prenons l'exemple d'un champ de saisie qui doit déclencher un comportement lié à Ninox. L'approche traditionnelle consiste à passer par l'API REST pour envoyer les données au serveur, lequel met ensuite à jour l'affichage local. Efficace, cette méthode a plusieurs inconvénients :

• Complexité technique : mettre en œuvre des appels d'API suppose une bonne maîtrise des requêtes HTTP en JavaScript.
• Interactivité limitée : les changements ne portent que sur les données côté serveur, sans possibilité de déclencher une mise à jour locale immédiate de l'interface.

Avec Ninext, l'intégration est plus fluide : vous reliez directement vos composants HTML/JavaScript à des fonctions Ninox. Vos applications y gagnent en interactivité, sans les contraintes habituelles des appels d'API.

callNinoxFunction

La fonction callNinoxFunction permet d'appeler un script Ninox depuis du code JavaScript. Cette intégration offre une grande souplesse pour dialoguer avec Ninox, notamment pour :

• Envoyer la valeur d'un champ de saisie,
• Exécuter des actions lors d'événements comme onclick, onfocus, onblur, ontimer, etc.,
• Gérer des opérations asynchrones avec des fonctions de rappel.

Format et paramètres

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

Paramètre	Description
functionName	Nom de la fonction Ninox à appeler.
htmlElement	Peut être l'identifiant de l'élément HTML (par exemple "myId"), ou l'élément lui-même (par exemple this ou document.getElementById("myId")).
...args	Paramètres supplémentaires à transmettre à la fonction Ninox.
callback	(Facultatif) Une fonction pour traiter le résultat de façon asynchrone. Si elle est fournie, elle est appelée avec (error, result).

Valeur de retour

Mode synchrone (sans fonction de rappel)

La fonction renvoie un objet JSON ayant l'une des structures suivantes :

En cas de succès :

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

En cas d'erreur :

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

Mode asynchrone (avec fonction de rappel)

Lorsqu'une fonction de rappel est fournie en dernier argument, elle reçoit deux paramètres :

callback(error, result)

Paramètre	Description
error	Un objet Error si quelque chose s'est mal passé, ou undefined en cas de succès.
result	La valeur renvoyée par la fonction Ninox, ou null si une erreur est survenue.

Comment cela fonctionne

L'idée maîtresse est d'exécuter des scripts Ninox dans le contexte d'une page HTML. Voici comment cela se passe :

1. Définir la fonction Ninox
   Dans votre formule Ninox, définissez une fonction (par exemple myOnblur) qui traitera les paramètres transmis depuis le JavaScript. Cette fonction reste isolée du reste du script et s'exécute dans le contexte de l'enregistrement courant (l'équivalent de this dans Ninox).
2. Créer l'interface HTML
   Intégrez un composant HTML (par exemple un champ de saisie) dans la formule. Dans l'attribut d'événement (comme onblur), utilisez callNinoxFunction pour appeler la fonction Ninox correspondante, en lui passant les paramètres nécessaires.
3. Déclencher l'événement
   Lorsque l'événement HTML se produit, callNinoxFunction appelle la fonction Ninox indiquée, l'isole et l'exécute avec le contexte et les paramètres fournis (par exemple la valeur du champ de saisie).

Ce mécanisme reproduit le comportement d'un déclencheur natif, tout en permettant de passer un ou plusieurs paramètres personnalisés à l'exécution de la fonction Ninox.

Exemples d'utilisation

Exemple de base : champ de saisie avec onblur

1. Définir la fonction Ninox

Dans votre formule Ninox, ajoutez la fonction suivante :

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

Cette fonction affiche une alerte indiquant l'identifiant de l'enregistrement courant et la valeur transmise.

2. Intégrer le champ de saisie HTML

Insérez ensuite le code HTML suivant pour afficher un champ de saisie et définir l'événement 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)""
    />
")

Comment cela fonctionne :

• Lorsque l'utilisateur quitte le champ de saisie (événement onblur),
• La fonction ninext.callNinoxFunction est appelée avec :
  • 'myOnblur' : le nom de la fonction Ninox à exécuter,
  • this : l'élément HTML lui-même,
  • this.value : la valeur courante du champ de saisie.

Le script Ninox myOnblur s'exécute ainsi dans le contexte de l'enregistrement courant, comme s'il avait été déclenché nativement par Ninox, tout en recevant la valeur du champ de saisie en paramètre.

Exemples d'utilisation en mode synchrone

// 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'utilisation en mode asynchrone (avec fonction de rappel)

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

Quand utiliser les fonctions de rappel ?

Employez le motif de rappel lorsque :

• La fonction Ninox effectue des opérations asynchrones (appels d'API, calculs complexes),
• Vous devez mettre à jour l'interface une fois la fonction terminée,
• Vous souhaitez enchaîner plusieurs opérations séquentiellement.

Points clés

• Contextualisation :
  La fonction Ninox s'exécute avec this désignant l'enregistrement courant, ce qui garantit la cohérence du contexte d'exécution.
• Souplesse :
  Vous pouvez ajouter autant de paramètres que nécessaire grâce à ...args, ce qui permet d'adapter le comportement de la fonction Ninox aux besoins propres de votre application.
• Gestion des erreurs :
  Les modes synchrone et asynchrone signalent clairement les erreurs, ce qui facilite le débogage.
• Usages multiples :
  Ce mécanisme est particulièrement utile pour intégrer des interactions complexes entre l'interface utilisateur HTML/JavaScript et la logique métier définie dans Ninox.