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 : un attribut d'événement HTML, un bloc Native JS… 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 ou onblur, ou à l'échéance d'une minuterie (setTimeout),
• Gérer des opérations asynchrones avec des fonctions de rappel.

Format et paramètres

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

Valeur de retour

Mode synchrone (sans fonction de rappel)

La fonction rend aussitôt 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
}

Le résultat n'y figure que si la fonction Ninox s'est exécutée sans attendre. Si elle doit patienter (une fiche encore à charger, un traitement asynchrone), l'objet est rendu avant qu'elle ait fini, sans résultat. Dans le doute, passez une fonction de rappel.

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)

error est renseigné quand l'appel n'a pas pu se faire : fonction, élément ou fiche introuvable, code qui ne se compile pas.

Appeler une fonction du code global

Avec null en deuxième argument, Ninext appelle une fonction du code global de la base. Elle s'exécute sans fiche de contexte. Avec cette fonction dans le code global :

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

le JavaScript l'appelle ainsi :

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

C'est aussi le moyen d'appeler une fonction du code global depuis un bloc Native JS, qui ne la voit pas directement.

Désigner la fonction par une référence

Le deuxième argument peut aussi être un texte qui désigne une fiche. Ninext y cherche d'abord un élément HTML portant cet identifiant, puis lit la référence : la fonction s'exécute alors dans le contexte de cette fiche (this).

A13 est l'identifiant complet de la fiche : l'identifiant de la table suivi du numéro de la fiche. Les déclencheurs de table portent leur nom interne : afterCreate, afterUpdate ou onClick. Le champ se désigne par son identifiant ou par son nom, écrit sans guillemets. Un nom qui contient des parenthèses ou d'autres signes de ponctuation fait échouer l'appel (exception JavaScript) : désignez alors le champ par son identifiant.

Les arguments

Les arguments passent du JavaScript à Ninox ainsi :

Les valeurs d'un objet peuvent contenir guillemets, retours à la ligne et accents (à partir de la version 3.2.0). N'envoyez ni null ni undefined en argument : l'appel lève alors une exception JavaScript.

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. Ninext n'extrait que cette fonction de la formule : elle ne voit ni les variables ni les autres fonctions déclarées ailleurs dans la formule. Elle 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);
    } 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;
    }
});

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, ou la fiche désignée par la référence, ce qui garantit la cohérence du contexte d'exécution. Une fonction du code global s'exécute sans fiche.
• 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 :
  error signale un appel qui n'a pas pu se faire : fonction, élément ou fiche introuvable, code qui ne se compile pas. C'est un texte, à afficher tel quel. Pour une fonction qui peut devoir attendre, passez une fonction de rappel.
• 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.