Fonctions définies par l'utilisateur (UDF) : Guide complet
Les fonctions définies par l’utilisateur permettent de créer des fonctions personnalisées au sein d’une application canvas. Ses fonctions sont déclarées dans la propriété formulas de l’objet APP Ou nous pouvons déclarer les paramètres d’entrée et décrire le traitement effectué par cette fonction.
- Généralités
- Prérequis
- Définir une fonction
- Types de données
- Formules comportementales
- Quelques bonnes pratiques :
- Pour aller plus loin…
Généralités
Les fonctions UDF s’utilisent de la même manière que les fonctions natives en power FX :
NomFormule( ‘Param. 1’, ‘Param. 2’, …) = Résultat
Les UDFs partagent les mêmes propriétés que les formules nommées :
-
La définition de la fonction est immuable
-
Le résultat est toujours à jour
Les avantages :
-
Le résultat est toujours disponible
-
Le calcul de la fonction peut être différé
-
Moins de code à produire
-
Moins de code à maintenir
Elles ont cependant quelques limitations :
-
Pas de récursivité, ni de séquentiel
-
Les paramètres d’entrée définis ne peuvent pas être optionnels
Prérequis
À l’heure actuelle, les fonctions personnalisées sont encore à l’état expérimental. Il est donc nécessaire de les activer dans les paramètres du studio.
Définir une fonction
Dans une UDF, on devra définir :
-
Le nom de la fonction
-
Les paramètres d’entrée et leur format
-
Le format de sortie
-
Les calculs à opérer
Syntaxe dans l’objet App.Formulas avec quelques exemples de fonctions simples :
// Calcul simple de deux nombres
udfPoucentage( Actuel: Number ; Maxi: Number): Number= IfError(Actuel/Maxi*100;Blank());;
// Conversion du séparateur décimal pour que les valeurs dynamiques dans les images SVG ne soient pas impactées quand le navigateur est en séparateur décimal virgule (fr)
udfSVGv(Valeur:Number):Text=Text(Valeur;"0";"En-US");;
// Génération de QRCodes avec QuickChart.io :
udfQRcode(url:Text):Text="https://quickchart.io/qr?text="&EncodeUrl(url);;
Types de données
Comme nous l’avons vu dans l’exemple ci-dessus. Une fonction a besoin d’un format de données (datatype) pour ses paramètres d’entrée et de sortie. Les formats de données peuvent être de plusieurs types :
DataType de base
Une sélection de types de données de base est disponible nativement.
DataType issu d’une source
Dès qu’une source est ajoutée à l’application, son type de données est reconnu et proposé comme format pour les UDF. Attention, seul le format “table” est proposé : Si vous devez utiliser le format “enregistrement”, il faudra le définir vous-même.
DataType défini par l’utilisateur
Enfin, le type de données peut être défini par l’utilisateur, soit champ par champ, soit à l’aide de fonctions dédiées. Ils sont eux aussi déclarés et définis dans l’objet App.Formulas.
Syntaxe
On définit le type de données avec le symbole := et la fonction Type()
udtStatut := Type({
Code: Number;
Nom: Text;
Couleur: Color;
EnFonction: Boolean
});;
Il est possible de définir un type de données au format table d’après un type de données “enregistrement” en utilisant les symboles [ ]
// Définition du format enregistrement
udtCalJour:=Type({Date:Date;Détail:Text;IsWE:Boolean;IsDim:Boolean;IsHoliday:Boolean});;
// Définition du format table
udtCalendrier:=Type([udtCalJour]);;
On peut définir un type de données “enregistrement” d’après un type de données “Table” avec la fonction RecordOf()
udtCompte := Type(RecordOf(Comptes));;
Formules comportementales
Jusqu’il y a peu, les UDF étaient incapables de. D’exécuter des formules comportementales Par exemple, il était impossible de lancer un ClearCollect() ou un set de variable depuis une fonction définie par l’utilisateur .
Depuis janvier 2025, certaines formules comportementales sont autorisées dans les fonctions définies par les utilisateurs. On peut notamment exécuter un Set() ou un Notify(), exemple :
// Fonction comportementale
udfCountUp( increment : Number ) : Void = {
Set( gblX; gblX+increment );;
Notify( $"Count: {gblX}" );;
};;
Quelques bonnes pratiques :
- Ne pas appeler les paramètres d’un objet ou d’un composant
- Cela pourrait poser des problèmes de performance car l’écran dans lequel se situe cet objet devrait être gardé en mémoire en permanence dans l’application client.
- Nommer les fonctions avec un préfixe (udf_ , uf …)
- Pour éviter toute confusion ou conflit avec les fonctions natives
- Diviser le paramètre App.Formulas en 3 sections :
-
Formules nommées (nf)
-
Types de données définis par l’utilisateur (udt)
-
Fonctions définies par l’utilisateur (udf)
-
- Commentez vos formules !
Pour aller plus loin…
Retrouvez la présentation des UDF, réalisée aux côtés de Tanguy Badier au PPFS 2024 :
https://www.youtube.com/watch?v=IQ8tTxq1wM0
Vous pouvez également télécharger une application démo via ce lien
Échanger autour de cet article
Les commentaires utilisent Giscus et GitHub Discussions. Le service externe n’est contacté qu’après activation.