SmartExpressions

De YoWiki
Sauter à la navigation Sauter à la recherche

Cette page est en cours de construction

Sommaire

Introduction

On désigne par "SmartExpressions" la syntaxe permettant de paramétrer les Dynvars et les Visible If.

Paramétrage

Pour mémoire : la syntaxe est basée sur PHP : https://www.php.net/manual/fr/funcref.php

Bases de la syntaxe

Cette page est encore en cours de construction

Principes

La syntaxe SmartExpressions permet d'effectuer des enchaînements logiques de type SI ... ALORS afin de déterminer des règles d'applications, ainsi que des calculs mathématiques

? : Alors

: : Sinon

or, and : OU, ET

~ : Concaténation (entre plusieurs chaînes de caractères)

*+-/=!= : opérateurs mathématiques

Illustration

Smartex complexe.png

Ici la SmartExpression utilisée signifie :

Si la variable TYPE_SOCIETE est égale à "Entreprise unipersonnelle à responsabilité limitée" OU si la variable TYPE_SOCIETE est égale à "Société à responsabilité limitée" OU si la variable TYPE_SOCIETE est égale à "Société civile", ALORS la Dynvar ACTIONS_PARTS devra valoir "parts sociales", sinon SI si la variable TYPE_SOCIETE est égale à "Société par actions simplifiée" OU si la variable TYPE_SOCIETE est égale à "Société par actions simplifiée unipersonnelle", alors la la Dynvar ACTIONS_PARTS devra valoir "actions"

Décomposition @LEO TODO


Exemples d'application

Opérations mathématiques

Les Dynvars peuvent servir à effectuer des opérations mathématiques, en utilisant les opérateurs basiques, comme par exemple :

Dans cet exemple, une variable PRIX_HT est multipliée par 1.20 pour obtenir un prix TTC

Il est possible d'effectuer des opérations mathématiques entre plusieurs variables, et aussi entre plusieurs Dynvars.

Liste des opérateurs mathématiques pouvant être utilisés : *+-/

Factorisation du raisonnement

Factorisation simple

On peut aussi prévoir qu'une Dynvar prenne pour valeur TRUE ou FALSE en fonction de la valeur d'autres variables

Par exemple :

Si une des deux variables vaut "france", alors la variable FISCALITE_FR vaudra "vrai".

Cette formule signifie : la Dynvar nommée FISCALITE_FR vaudra TRUE si NATIONALITE_ACHETEUR ou NATIONALITE_VENDEUR est égal à "france"

Il sera donc possible d'utiliser la Dynvar FISCALITE_FR dans des Visible Ifs, ou même dans les formules d'autres Dynvars.

Pour utiliser la dynvar FISCALITE_FR, on utilisera donc la SmartExpression suivante : FISCALITE_FR = true ou FISCALITE_FR = false

Factorisation et chaînes de caractères
La SmartExpression contenue dans cette dynvar

Dans l'exemple ci-dessus, la SmartExpression signifie : "Si la variable SOCIETE_RESULTAT est supérieure à 0, Alors la Dynvar BENEFICE_PERTE doit valoir "bénéfice", sinon si la variable SOCIETE_RESULTAT est inférieure à 0, Alors la Dynvar BENEFICE_PERTE doit valoir "perte".

Dynvars et chaînes de caractères

Une Dynvar peut avoir pour formule plusieurs chaînes de caractères, par exemple pour reconstruire un nom complet ou une phrase en utilisant plusieurs variables.

Une dynvar FULL_NAME qui reprend grâce à la concaténation : la civilité, le nom, et le prénom.

Les fonctions

Principes

Une fonction prend toujours la forme suivante : nom_de_la_fonction( xxx )


Une fonction est donc toujours composée de trois éléments :

nom_de_la_fonction : on commence toujours par nommer la fonction souhaitée.

( ) : ces parenthèses dites "d'exécution" peuvent contenir plusieurs paramètres, séparés chacun par une virgule. Chaque fonction pourra avoir plus ou moins de paramètres.

xxx : les paramètres de la fonction. Ce sont les paramètres qui vont permettre à la fonction de s'exécuter.

Fonctions sur les Dates

Opération sur une date

Cette fonction permet de réaliser des opérations (somme et soustraction) sur une date. C'est à dire que pour une date donnée, la fonction permet d'obtenir une date antérieur ou postérieure de N jours / années / heures (etc.). Cette fonction est utile pour calculer une date d'échéance (ex : "3 mois après la date de signature…"), ou parler d'une date en fonction d'une autre (Ex : "12 jours avant la date…").

  1. Nom de la fonction : date_sum
  2. Nombre de paramètres : 3
  • 1 - Date à traiter (variable provenant d'un DateInput, ou chaîne format "d-m-Y H:i")
  • 2 - Un nombre entier (positif ou négatif)
  • 3 - L'unité sous forme d'une chaîne de caractères parmi : "year"; "month"; "day"; "hour"; "minute"; "second".
    + Unité spéciale pour la France et ses territoires : "jour_ouvrable", "jour_ouvré", "jour_franc", "mois_franc" (tenant compte des jours fériés Français)
    + Mais aussi l'unité particulière `month_quant` qui correspond à une règle administrative courante dîtes de "mois de même quantième". On parle par exemple d'un délais de 3 mois au même quantième. Cela signifie que l'on avance de 3 mois et que le jour de destination doit être le même que celui de départ (Ex: 15 Mars + 3 mois = 15 juin). Néanmoins, cette unité prend aussi en compte le fait que si la date de destination n'existe pas (ex: 31 Aout + 1 mois), alors on renvoie le dernier jour du mois de destination (= ici le 30 Septembre).
  • 4 - (facultatif) La zone géographique qui doit être utilisée pour calculer les jours fériés (utile uniquement pour le calcul des jours spéciaux tel que jour_ouvré etc.). À choisir parmi : Métropole, Alsace-Moselle, Guadeloupe, Guyane, Martinique, Mayotte, Nouvelle-Calédonie, La Réunion, Polynésie Française, Saint-Barthélémy, Saint-Martin, Wallis-et-Futuna, Saint-Pierre-et-Miquelon.

Par exemple :

Soit une date de signature (DATE_SIGNATURE) ayant pour valeur le 12/05/2020, et l'on veut rajouter 3 jours à cette date :

▷ date_sum(DATE_SIGNATURE, 3, "day") => renvoie 15/05/2020

Ou avec une valeur négative, pour soustraire 3 ans par exemple :

▷ date_sum(DATE_SIGNATURE, -3, "year") => renvoie 12/05/2017

Avec un calcul de jour ouvré (ajout de 4 jours ouvrés à la date de signature en tenant compte des jours fériés de l'Alsace-Moselle) :

▷ date_sum(DATE_SIGNATURE, 4, "jour_ouvré", "Alsace-Moselle") => renvoie 18/05/2017 (car il saute le week-end)

Pour aller plus loin :

Dans les exemples précédents, la seule variable était DATE_SIGNATURE (avec pour valeur 12/05/2020). Cependant, comme dans toute SmartExpression, les valeurs statiques (nombre, chaîne…) peuvent toujours être substituées par une valeur variable. Pour l'exemple, on aurait très bien pu utiliser deux autres variables et les utiliser dans le date_sum(…). Par exemple, avec AJOUT_NUM qui vaudrait 3 (issue d'un champ numérique), et la variable AJOUT_UNITÉ qui vaudrait day (issue d'un champ de choix par exemple), :

▷ date_sum(DATE_SIGNATURE, AJOUT_NUM, AJOUT_UNITÉ) => renvoie 15/05/2020

savoir si une date est avant une autre date
  1. Fonction : date_before
  2. Nombre de paramètres : 2
  3. Paramètres attendus : Date 1, Date 2

Renvoie VRAI si la Date 1 est antérieure à la Date 2. Renvoie FAUX sinon.

Notez que la Date 1 ou la Date 2 peuvent provenir d'une variable complétée par la valeur d'un champ "date-input" d'un SmartForm, ou correspondre à une date fixe fournie sous la forme d'une chaîne de caractère au format j-m-A (la précision peut aller jusqu'à la seconde : j-m-A h:m:s)

Par exemple :

Soit une date de signature (DATE_SIGNATURE) ayant pour valeur le 12/05/2020, et l'on veut vérifier que la signature soit antérieure à la date du 1er Janvier 2020 :

▷ date_before(DATE_SIGNATURE,"01-01-2020") => renvoie FAUX
▷ Alors que date_before(DATE_SIGNATURE,"01-01-2021") => renvoie VRAI

calcul de la différence entre deux dates
  1. Fonction : date_diff
  2. Nombre de paramètres : 3
  • 1 - Date de départ (variable provenant d'un DateInput, ou chaîne format "d-m-Y H:i")
  • 2 - Date de fin (variable provenant d'un DateInput, ou chaîne format "d-m-Y H:i")
  • 3 - L'unité dans laquelle renvoyer la différence entre les deux dates. L'unité est fournie sous la forme d'une chaîne de caractères parmi : "year"; "month"; "day"; "hour"; "minute"; "second".
    + Unité spéciale pour la France et ses territoires : "jour_ouvrable", "jour_ouvré"
  • 4 - (facultatif) La zone géographique qui doit être utilisée pour calculer les jours fériés (utile uniquement pour le calcul des jours spéciaux tel que jour_ouvré etc.). À choisir parmi : Métropole (par défaut), Alsace-Moselle, Guadeloupe, Guyane, Martinique, Mayotte, Nouvelle-Calédonie, La Réunion, Polynésie Française, Saint-Barthélémy, Saint-Martin, Wallis-et-Futuna, Saint-Pierre-et-Miquelon.

Renvoie un nombre (valeur absolue) correspondant à la différence, entre la Date de début et la Date de fin, dans l'unité spécifiée. Notez que la date de fin n'est généralement pas inclue dans la comptage de la différence.

Par exemple :

Soit une date de signature (DATE_SIGNATURE) ayant pour valeur le 31/05/2020, et l'on veut savoir combien d'années de différence entre les 2 dates :

▷ date_diff(DATE_SIGNATURE,"20-09-2004","year") => renvoie 15 car 15 années se sont écoulées
▷ date_diff("20-09-2004",DATE_SIGNATURE, "year") => renvoie aussi 15 (la valeur est absolue, peu importe l'ordre des dates)
▷ date_diff("20-09-2004",DATE_SIGNATURE, "day") => renvoie 5732 (le nombre total de jour entre les deux dates)
▷ date_diff("01-05-2020","31-05-2020", "day") => renvoie 30 (le nombre total de jour entre le 01 et le 31 Mai, le 31 Mai n'étant pas inclu).
▷ date_diff("01-05-2020","31-05-2020", "jour_ouvré") => renvoie 18 (le nombre de jours ouvrés entre le 01 et le 31 Mai 2020).
▷ date_diff("01-05-2020","31-05-2020", "jour_ouvré", "Martinique") => renvoie 17 (le nombre de jours ouvrés entre le 01 et le 31 Mai 2020 en Martinique, car contrairement à la Métropole, le 22 Mai est aussi férié).

renvoyer automatiquement la date du jour

Spécificité : fonction unaire, ne possède pas de paramètres

  1. Fonction : now()
  2. Nombre de paramètres : 0
  3. Paramètres attendus : N/A

Par exemple :

Now().png

trouver automatiquement l'âge d'un individu
  1. Fonction : years_old
  2. Nombre de paramètres : 1
  3. Paramètres attendus : Une date

Par exemple :

years_old(DATE_NAISSANCE)

isoler le jour, le mois, l'année d'une date
  1. Fonction : date_day date_month date_year
  2. Nombre de paramètres : 1
  3. Paramètres attendus : Une date

Par exemple : date_month(DATE_SIGNATURE)

Connaître le jour de la semaine
  1. Fonction : date_weekday , renvoie la valeur numérique du jour de la semaine (1 pour lundi, 7 pour dimanche).
  1. Nombre de paramètres : 1
  2. Paramètres attendus : Une date

Par exemple : date_weekday(DATE_SIGNATURE) => Renvoie 1 pour lundi, 2 pour mardi…, 6 pour samedi, 7 pour dimanche

Savoir si le jour est ouvrable, ouvré, ou férié
  1. Fonction : day_is , renvoie un booléen (VRAI ou FAUX) si la date est du type demandé.
  1. Paramètres attendus : 2 ou 3
  • 1 - La date questionnée (variable provenant d'un DateInput, ou chaîne format "d-m-Y H:i")
  • 2 - Le type de jour demandée parmi : weekend, ouvré, ouvrable, férié
  • 3 - (facultatif) La zone géographique qui doit être utilisée pour calculer les jours fériés (utile uniquement pour le calcul des jours spéciaux tel que jour_ouvré etc.). À choisir parmi : Métropole (par défaut), Alsace-Moselle, Guadeloupe, Guyane, Martinique, Mayotte, Nouvelle-Calédonie, La Réunion, Polynésie Française, Saint-Barthélémy, Saint-Martin, Wallis-et-Futuna, Saint-Pierre-et-Miquelon.

Par exemple :

▷ day_is("25-12-2021", "férié") => renvoie TRUE car le jour de Noël est férié
▷ day_is("26-12-2021", "férié") => renvoie FALSE
▷ day_is("26-12-2021", "weekend") => renvoie TRUE car ce jour est un dimanche.
▷ day_is("23-12-2021", "ouvré") => renvoie TRUE car ce jour est un jeudi, non-férié.
▷ day_is("22-05-2021", "ouvré") => renvoie TRUE car ce jour est un vendredi, non-férié (en Métropole du moins).
▷ day_is("22-05-2021", "ouvré", "Martinique") => renvoie FALSE car ce jour est férié en Martinique contrairement à la Métropole.

changer le format d'une date
  1. Fonction : date_format
  2. Nombre de paramètres : 2
  3. Paramètres attendus : Une date, Un format de date

Par exemple :

Passer d'une date complète à un format jour/mois

date_format(DATE_NAISSANCE, "d/m")

Fonctions sur les Nombres

Introduction : notez bien que les traitements sur les nombres peuvent être effectués aussi bien sur des variables que sur d'autres dynvars


Arrondir un nombre en choisissant le nombre de chiffres souhaités après la virgule
  1. Fonction : round
  2. Nombre de paramètres : 2
  3. Paramètres attendus : Un nombre, Un autre nombre

La fonction enregistre le premier nombre, puis l'arrondit en fonction du deuxième paramètre

La méthode utilisée est celle de l'arrondi arithmétique.

Par exemple :

Pour arrondir un prix d'achat à 3 chiffres après la virgule

round(PRIX_ACHAT, 3)


Arrondir un nombre entier à l'entier inférieur
  1. Fonction : floor
  2. Nombre de paramètres : 1
  3. Paramètres attendus : Un nombre

La fonction attend un nombre et lui retire ses décimales en arrondissant à l'entier inférieur

Par exemple :

Pour arrondir un prix d'achat à l'entier inférieur

floor(PRIX_ACHAT)


Arrondir un nombre entier à l'entier supérieur
  1. Fonction : ceil
  2. Nombre de paramètres : 1
  3. Paramètres attendus : Un nombre

La fonction attend un nombre et lui retire ses décimales en arrondissant à l'entier supérieur

Par exemple :

Pour arrondir un prix d'achat à l'entier supérieur

ceil(PRIX_ACHAT)


Tronquer le nombre de décimale (sans arrondir)
  1. Fonction : truncate
  2. Nombre de paramètres : 1
  3. Paramètres attendus : Deux nombres. Le premier est la valeur à tronquer (ex: 3.1415) et le second est le nombre de décimale à garder après la virgule (Ex: 2).

La fonction va tronquer les décimales au nombre de décimales indiqué dans le second paramètre.

Par exemple :
Avec PRIX_ACHAT qui est issu d'un calcul et vaut 1.336666, alors truncate(PRIX_ACHAT, 2) vaudra 1.33.


Valeur absolue
  1. Fonction : abs
  2. Nombre de paramètres : 1
  3. Paramètres attendus : le nombre (positif ou négatif) à convertir en valeur absolue.

La fonction va permettre de ramener les nombres négatifs à leur valeur positive (nombre absolu).

Par exemple :
Avec une variable VARIATION qui est issu d'un calcul et qui vaut -6.34, alors abs(VARIATION) vaudra 6.34.


Minimum ou Maximum
  1. Fonction : max ou min
  2. Nombre de paramètres : 2
  3. Paramètres attendus : les deux nombres à comparer.

La fonction va permettre de renvoyer la valeur maximale (ou minimale) entre le paramètre 1 et 2.

Par exemple :

- max(-6, 55) vaut 55.
- max(100, 8) vaut 100.
- min(100, 8) vaut 8.
- min(-99, 300) vaut -99.


Formater un nombre en chaîne de caractère
  1. Fonction : numFormat
  2. Nombre de paramètres : 4 mais seulement le 1er est obligatoire.
  3. Paramètres :
    1. - (numérique) le nombre à formater (obligatoire)
    2. - (numérique) le nombre de décimales à forcer (par défaut, le nombre de décimale d'origine)
    3. - (string) le caractère pour le séparateur des milliers (ex: "," ou " ", ou "" etc.). Par défaut: " ".
    4. - (string) le caractère pour le séparateur de l'entier/décimale (ex: "." ou "," etc.). Par défaut: ","


La fonction va permettre de formater un nombre, par exemple pour faire apparaitre des séparateurs de milliers, ou personnaliser les décimales etc.
Le fonctionnement est très similaire au traitement :num-format des SmartDocs.


Par exemple :

- numFormat(1003.1415, 2) vaut 1 003,14.
- numFormat(8133003.1415, 0) vaut 8 133 003.
- numFormat(3500) vaut 3 500.
- numFormat(3500.999) vaut 3 500,999.
- numFormat(3000.50, 4, ',', '.') vaut 3,500.5000.

Fonctions sur les Chaînes de caractères

Compter le nombre de caractères d'une chaîne
  1. Fonction : stringLength
  2. Nombre de paramètres : 1
  3. Paramètres attendus : Une Chaîne de caractères (string).

Renvoie le nombre de caractère de la chaîne.

Exemple : stringLength('Hercule !') renvoie 9 (entier numérique).

Les espaces ou les sauts de lignes comptent aussi pour 1 caractère, même s'ils apparaissent en début ou en fin de la chaîne.

Spécial : si la valeur passée en paramètre est une valeur numérique, la fonction renverra le nombre de "digit" de ce nomnre.
Ex : Avec CODE_POSTAL qui vaut 34700 (entier numérique), alors stringLength(CODE_POSTAL) renvoie 5.

Si par contre la valeur passée en paramètre est d'un autre type (exemple : une liste, un booléen), ces types n'étant pas pris en charge, la fonction renverra systématiquement 0.

Trouver si une chaîne de caractères commence par une autre chaîne de caractères
  1. Fonction : begins_with
  2. Nombre de paramètres : 2
  3. Paramètres attendus : Une Chaîne de caractères (string), une autre Chaîne de caractères

La première chaîne de caractères est la chaîne dans laquelle rechercher, la deuxième chaîne de caractère est la chaîne à rechercher

La Dynvar paramétrée avec cette fonction vaudra TRUE si la chaîne du premier paramètre commence par la chaîne du second paramètre

Trouver si une chaîne de caractères se finit par une autre chaîne de caractères
  1. Fonction : ends_with
  2. Nombre de paramètres : 2
  3. Paramètres attendus : Une Chaîne de caractères (string), une autre Chaîne de caractères

La première chaîne de caractères est la chaîne dans laquelle rechercher, la deuxième chaîne de caractère est la chaîne à rechercher

La Dynvar paramétrée avec cette fonction vaudra TRUE si la chaîne du premier paramètre se finit par la chaîne du second paramètre


Un élément en contient-il un autre ?
  1. Fonction : contains
  2. Nombre de paramètres : 2
  3. Paramètres attendus :
1er paramètre : une Chaine A (string) ou une Liste (list)
Paramètre 2 : une chaîne B (string)

Si le 1er paramètre est une chaîne : renvoie VRAI si la chaîne A contient la chaîne B.

Si le 1er paramètre est une liste : renvoie VRAI si la liste contient la valeur B correspondante à la chaîne B.

Si le 1er paramètre est null ou d'un autre format non-attendu (booléen, nombre…) : la fonction renverra null par défaut.

Exemple :

Soit une chaîne NUM_FACTURE correspondant à un numéro de facture tel que : '2020F01'.
Et soit une Liste HOBBIES correspondants à 3 choix : ["sport", "cinema", "music"] (saisis par exemple via un champ de choix multiple).

▷ contains(NUM_FACTURE,"F") => renvoie VRAI car la chaine "2020F01" contient la chaine "F"
▷ contains(NUM_FACTURE,"2020F") => renvoie VRAI car la chaine "2020F01" contient aussi la chaine "2020F"
▷ contains(NUM_FACTURE,"20 Euros") => renvoie FALSE car la chaine "2020F01" ne contient pas "20 Euros"
▷ contains(HOBBIES,"cinema") => renvoie VRAI et c'est d'ailleurs le 2ème élément
▷ contains(HOBBIES,"cine") => renvoie FALSE car aucun élément est exactement nommé "cine" parmi ceux de la liste

Tronquer une chaîne de caractères
  1. Fonction : substring
  2. Nombre de paramètres : 3
  3. Paramètres attendus : Une Chaîne de caractères (string), le nombre à partir duquel la fonction doit tronquer, le nombre de caractères à prendre en compte après la troncation

À noter : le troisième paramètre est facultatif. S'il n'est pas présent, la fonction renverra tous les caractères situés après la troncation

Par exemple :

Pour une dynvar paramétrée de la manière suivante : substring(DENOMINATION, 2, 3);

Si la variable DENOMINATION vaut "Hercule";

La Dynvar ainsi paramétrée vaudra "rcu"


Ou encore :

Pour une dynvar paramétrée de la manière suivante : substring(DENOMINATION, 0, 4);

Si la variable DENOMINATION vaut "Hercule";

La Dynvar ainsi paramétrée vaudra "Herc"


Ou enfin :

Pour une dynvar paramétrée de la manière suivante : substring(DENOMINATION, 2);

Si la variable DENOMINATION vaut "Hercule";

La Dynvar ainsi paramétrée vaudra "rcule"

Connaître la position d'une sous-chaîne
  1. Fonction : stringPos
  2. Nombre de paramètres : 2 obligatoires, et un dernier facultatif.
  3. Paramètres attendus :
    1. La chaîne de caractères dans laquelle rechercher. (Ex: "Maison d'été")
    2. La chaîne de caractères (ou simplement le caractère) à rechercher (Ex: la lettre "n")
    3. (Optionnel) un nombre entier correspondant à la position de début de recherche. S'il est omis, zéro sera utilisé. Une position négative compte à partir de la fin de la chaîne de caractères n°1.

Notez que le premier caractère est comptabilisé comme à la position n°0.

Ex: stringPos("Maison d'été", "n") va retourner 5 car la lettre n se trouve à la 5ème position de la chaîne fournie (la lettre M étant comptée comme la position n°0)

Ex: stringPos("Maison d'été", "été") va retourner 9 car le terme été se trouve à la 9ème position de la chaîne fournie.

Ex: stringPos("Blablabla", "a", 3) va retourner 5 car, si on omet les 3 premiers caractères, la prochaine lettre a se trouve à la 5ème position de la chaîne fournie.


Tronquer la chaîne avec tout ce qui est "avant" une sous-chaîne
  1. Fonction : stringBefore
  2. Nombre de paramètres : 1 obligatoire, 1 facultatif.
  3. Paramètres attendus :
    1. La chaîne de caractères dans laquelle rechercher.
    2. (Optionnel) La chaîne de caractères (ou simplement le caractère) à partir duquel il faut tronquer. Si rien n'est précisé, le caractère , sera utilisé.

Ex: stringBefore("Maison d'été", " ") va retourner Maison car on lui demande de ne retourner que ce qui est avant l'espace.

Ex: stringBefore("Damien, Jean, Paul") va retourner Damien car on lui demande de ne retourner que ce qui est avant la virgule (la virgule étant la valeur par défaut du second paramètre quand il n'est pas précisé).


Tronquer la chaîne avec tout ce qui est "après" une sous-chaîne
  1. Fonction : stringAfter
  2. Nombre de paramètres : 1 obligatoire, 1 facultatif.
  3. Paramètres attendus :
    1. La chaîne de caractères dans laquelle rechercher.
    2. (Optionnel) La chaîne de caractères (ou simplement le caractère) jusqu'auquel il faut tronquer. Si rien n'est précisé, le caractère , sera utilisé.

Ex: stringAfter("Maison d'été", " ") va retourner d'été car on lui demande de ne retourner que ce qui est après l'espace.

Ex: stringAfter("Damien, Jean, Paul") va retourner Jean, Paul car on lui demande de ne retourner que ce qui est après la virgule (la virgule étant la valeur par défaut du second paramètre quand il n'est pas précisé).


Rechercher et remplacer dans une chaîne
  1. Fonction : stringReplace
  2. Nombre de paramètres : 2 obligatoires, 1 facultatif.
  3. Paramètres attendus :
    1. La chaîne de caractères dans laquelle rechercher et remplacer ;
    2. La chaîne de caractères de remplacement (celle qui sera "insérée") ;
    3. (Optionnel) La chaîne de caractères qui sera recherchée (celle qui sera remplacée). Par défaut, si rien n'est précisé, ce sont des sauts de ligne (\n) qui seront recherchés.

Ex: stringReplace("Damien", "F", "D") va retourner Famien car on lui demande de remplacer D par F dans la chaîne Damien.

Ex: par exemple une variable ADDRESS qui contient une adresse postale sur plusieurs lignes, stringReplace(ADDRESS, ", ") va permettre de la renvoyer sur une seule et même ligne (séparée par des virgules). Le troisième paramètre n'est pas précisé car par défaut, ce sont des sauts de ligne qui sont recherchés et remplacés.

A l'inverse, pour remplacer des virgules par des sauts de ligne, il faudra écrire l'expression de cette façon : stringReplace(ADDRESS, "\n", ",").

Fonctions sur des listes

Obtenir la valeur d'un élément d'une liste à partir de clés
  1. Fonction : get_value
  2. Nombre de paramètres : min 2
  3. Paramètres attendus :
    1. - Une variable de type List ;
    2. - De 2 à N : la clé de l'élément antérieur ;
Cas pratique

Cas d'une liste EMPLOYES, utilisée dans un Repeater, dont chaque élément défini 3 sous-variables: EMPLOYES.NOM, EMPLOYES.DATE_ENTREE, EMPLOYES.SALAIRE.

Ceci étant, l'utilisateur a renseigner dans un formulaire 2 fiches correspondante à EMPLOYES. Elles ont respectivement les clés '_abc123' et '_xyz987' :

   [
     '_abc123' => [ 'NOM': 'Jean', 'DATE_ENTREE': '13-08-2020', 'SALAIRE': 32000.00 ],
     '_xyz987' => [ 'NOM': 'Sylvie', 'DATE_ENTREE': '11-12-2019', 'SALAIRE': 39500.00 ]
   ]
Usage

- get_value(EMPLOYES, '_abc123', 'NOM') => va renvoyer "Jean"
- get_value(EMPLOYES, '_xyz987', 'SALAIRE') => va renvoyer 39500.0

Mais là où cette fonction prend tout son intérêt, c'est quand le second paramètre est dynamique, c'est à dire qu'il est fourni au travers d'une variable.
Prenons par exemple, une variable "MEILLEUR_EMPLOYE", qui serait utilisée dans un formulaire avec un champ "choice-list", et qui prendra pour valeur la clé correspondante au meilleur employé de l'entreprise (= c'est à dire '_abc123' ou '_xyz987' dans notre exemple).


- get_value(EMPLOYES, MEILLEUR_EMPLOYE, 'SALAIRE') => va renvoyer le salaire du meilleur employé selon le choix effectué.



Obtenir la valeur d'un élément d'une liste à partir de son index
  1. Fonction : get_value_by_index
  2. Nombre de paramètres : 2
  3. Paramètres attendus :
    1. - Une variable de type List ;
    2. - L'index de l'élément à retourner (1,2,3…)


Cette fonction est similaire au get_value mais en utilisant l'index de l'élément au lieu de sa clé.
Le paramètre `index` peut être fourni au travers d'une variable ou directement "en dur".
Exemple sans variable : get_value_by_index(EMPLOYES, 3)
Exemple avec variable : get_value_by_index(EMPLOYES, INDEX_MEILLEUR_EMPLOYE)


Notez que dans le cas d'une liste structuré, l'élément retourné sera lui même une liste avec des sous-variables. Il faudra donc parfois combiner cette fonction avec un `get_value` :
Exemple : Obtenir le NOM du 3ème employé de la liste EMPLOYES : get_value( get_value_by_index(EMPLOYES, 3), 'NOM')



Savoir si une liste contient ou pas une certaine clé
  1. Fonction : has_key
  2. Nombre de paramètres : 2
  3. Paramètres attendus :
    1. - Une variable de type List ;
    2. - La clé à rechercher ;

Usage

- has_key(EMPLOYES_CDI, '_abc123') => va renvoyer TRUE si la liste EMPLOYES_CDI contient bien la clé '_abc123'

Tout comme pour la fonction get_value cette fonction prend tout son intérêt quand le second paramètre est dynamique, c'est à dire qu'il est fourni au travers d'une variable.
Prenons par exemple, une variable "MEILLEUR_EMPLOYE", qui serait utilisée dans un formulaire avec un champ "choice-list", et qui prendra pour valeur la clé correspondante au meilleur employé de l'entreprise (= c'est à dire '_abc123' ou '_xyz987' dans notre exemple).
S'il on veut savoir si cet employé fait parti de la liste de ceux qui sont en CDI, on pourrait faire :
- has_key(EMPLOYES_CDI, MEILLEUR_EMPLOYE) => va renvoyer TRUE si la clé renseignée dans MEILLEUR_EMPLOYE se trouve bien dans la liste EMPLOYES_CDI.



Assigner un nouveau couple clé-valeur dans une liste
  1. Fonction : set_in_struct
  2. Nombre de paramètres : 3
  3. Paramètres attendus :
    1. - Une variable de type List ;
    2. - La clé à créer ou mettre à jour (string);
    3. - La valeur a assigner ;


Usage

- set_in_struct(PRODUITS, CODE_PRODUIT, PRIX) => va renvoyer la liste PRODUITS avec la nouvelle valeur assignée.

Explication

Dans l'exemple ci-dessous, nous avons imaginé une liste PRODUITS qui serait de la forme : 

[ '_abc123' => 12.50,  '_xyz985' => 89.99 ]

- CODE_PRODUIT est une variable "string", par exemple "_bcd456" ;
- PRIX est une variable "numerique", par exemple 13.50 ;

Ceci étant, l'instruction ci-dessus, va retourner une liste de la forme : 

[
'_abc123' => 12.50,
'_xyz985' => 89.99,
'_bcd456' => 13.50,
]


Ajouter une valeur dans une liste plate
  1. Fonction : add_to_list
  2. Nombre de paramètres : 2 à N
  3. Paramètres attendus :
    1. - Une variable de type List plate (ex: ["jaune", "vert", "bleu"]) ;
    2. - La valeur à ajouter à la liste (string, nombre…) ;

Usage

Soit la liste plate PRODUITS qui vaut ["voiture", "sac"] :
- add_to_list(PRODUITS, "pomme") => va renvoyer la liste ["voiture", "sac", "pomme"] (la nouvelle valeur est ajoutée à la fin).
- add_to_list(PRODUITS, "pomme", "poire") => va renvoyer la liste ["voiture", "sac", "pomme", "poire"] (on peut passer autant de valeur qu'on le souhaite à la fonction, elles seront ajoutées à la fin).

Usage avancé

Cette fonction peut-être très utile, combinée à un #reduce, pour fabriquer des listes plates dynamiques.
Par exemple, si je veux lister les prénoms des associés ayant plus de 25% des parts :
#reduce list ASSOCIES as ASSOCIE_ITEM, [] as _PREV :
ASSOCIE_ITEM.PARTS > 25 ? add_to_list(_PREV, ASSOCIE_ITEM.PRENOM) : _PREV

Renvoie par exemple : ["Olivier", "Bruno"]


Ou, autre exemple, lister les clés des associés qui ont plus de 50% des parts :
#reduce list ASSOCIES as ASSOCIE_ITEM, [] as _PREV :
ASSOCIE_ITEM.PARTS > 30 ? add_to_list(_PREV, _KEY) : _PREV

Renvoie par exemple : ["_abc123", "_ac9876"]

Additionner les répétitions d'une sous-variable d'une liste structurée
  1. Fonction : list_sum
  2. Nombre de paramètres : 2
  3. Paramètres attendus :
    1. - Une variable de type List (utilisée par exemple dans un Repeater) ;
    2. - Le nom de la sous-variable qui devra être additionnée ;

Contexte

Il est parfois nécessaire d'additionner les différentes répétitions d'une même sous-variable.

Par exemple, dans cette situation :

Une sous-variable répétée demande ici le prix d'une chemise. Comment faire pour obtenir la somme des prix de toutes les chemises ?

Paramétrage

Le paramétrage prend la forme suivante :

list_sum(VARIABLE_LISTE,"SOUS_VARIABLE")

Pour obtenir le prix de toutes les Chemises dans l'exemple ci-dessus, il faudra paramétrer une Dynvar dont la formule sera list_sum(CHEMISES,"prix")



Obtenir une copie filtrée d'une liste à partir d'une série de clés
  1. Fonction : filter_by_keys
  2. Nombre de paramètres : 2
  3. Paramètres attendus :
    1. - Une liste avec des clés et des valeurs (ex: ASSOCIES);
    2. - Une liste de clés ;
Exemple de paramétrage :

Pour obtenir une copie de la liste des associés mais avec uniquement ceux qui ont été cochés comme "présents" :

filter_by_keys(ASSOCIES, ASSOCIES_PRESENTS)



Obtenir une copie filtrée d'une liste à partir sous-expression
  1. Fonction : filter_by_expr
  2. Nombre de paramètres : 2 ou N
  3. Paramètres attendus :
    1. - Une liste avec des clés et des valeurs (ex: ASSOCIES);
    2. - Une liste de clés ;
    3. - D'éventuels paramètres pour la sous-expression, paramètres au format numérique ou chaine de caractères, qui seront accessbible via les variables PARAM1, PARAM2, PARAM3 etc.
Exemple de paramétrage :
Pour obtenir une copie de la liste des associés mais avec uniquement ceux qui ont plus de 30 ans :
filter_by_expr(ASSOCIES, "ITEM.AGE > 30")

Pour obtenir ce même filtre avec un age dynamique :

filter_by_expr(ASSOCIES, "ITEM.AGE > PARAM1", AGE_MAX)



Tranformer une liste en chaine de caractère (jointure)
  1. Fonction : join
  2. Nombre de paramètres : 5
  3. Paramètres attendus :
    1. - Une variable de liste (paramètre obligatoire) ;
    2. - Séparateur de jointure (facultatif) ;
    3. - Dernier séparateur (facultatif) ;
    4. - Préfixe (facultatif) ;
    5. - Suffixe (facultatif)
Exemple de paramétrage :

join(COULEURS, ", ") donnera "jaune, rouge, bleu"

Il est possible de combiner "join" avec la fonction "filter_by_keys".

Par ex : join( filter_by_keys(FILIALES_DISPLAY, CONV.TRESO_FILIALES_PARTICIPANTES) , "", "", "\t - ", " ; \n")



Obtenir une copie filtrée d'une liste à partir sous-expression
  1. Fonction : filter_by_expr
  2. Nombre de paramètres : 2 ou N
  3. Paramètres attendus :
    1. - Une liste avec des clés et des valeurs (ex: ASSOCIES);
    2. - Une liste de clés ;
    3. - D'éventuels paramètres pour la sous-expression, paramètres au format numérique ou chaine de caractères, qui seront accessbible via les variables PARAM1, PARAM2, PARAM3 etc.
Exemple de paramétrage :
Pour obtenir une copie de la liste des associés mais avec uniquement ceux qui ont plus de 30 ans :
filter_by_expr(ASSOCIES, "ITEM.AGE > 30")

Pour obtenir ce même filtre avec un age dynamique :

filter_by_expr(ASSOCIES, "ITEM.AGE > PARAM1", AGE_MAX)



Obtenir une copie filtrée d'une liste à partir sous-expression
  1. Fonction : filter_by_expr
  2. Nombre de paramètres : 2 ou N
  3. Paramètres attendus :
    1. - Une liste avec des clés et des valeurs (ex: ASSOCIES);
    2. - Une liste de clés ;
    3. - D'éventuels paramètres pour la sous-expression, paramètres au format numérique ou chaine de caractères, qui seront accessbible via les variables PARAM1, PARAM2, PARAM3 etc.
Exemple de paramétrage :
Pour obtenir une copie de la liste des associés mais avec uniquement ceux qui ont plus de 30 ans :
filter_by_expr(ASSOCIES, "ITEM.AGE > 30")

Pour obtenir ce même filtre avec un age dynamique :

filter_by_expr(ASSOCIES, "ITEM.AGE > PARAM1", AGE_MAX)



Fusionner plusieurs listes
  1. Fonction : merge_list
  2. Nombre de paramètres : 2 ou N
  3. Paramètres attendus :
    1. - 2 ou N listes (ex: ASSOCIES);
Si une clé existe dans la liste 1 et la liste 2, la valeur de la liste 1 sera remplacée par celle de la liste 2.
Exemple de paramétrage :
merge(GERANTS, MANDATS_NOMINATION)

Fonctions autres

Vérifier si une variable est "vide"
  1. Fonction : is_empty
  2. Nombre de paramètres : 1
  3. Paramètres attendus : Une variable de n'importe quel type
  4. Exemple : is_empty(MY_VAR) == true

Pour savoir si une variable ne possède aucun valeur, il est préférable de tester cela avec la fonction is_empty.

La fonction renverra VRAI pour n'importe quelle variable vide : (chaîne vide), liste vide …

Par contre, la fonction renverra FALSE si une valeur est présente, même si cette valeur est un 0 ou le booléen "false" (c'est d'ailleurs pour cela qu'il est préférable d'utiliser `is_empty(MY_VAR)` au lieu de, par exemple, `MY_VAR = null`.

Vérifier si une variable est "non vide"
  1. Fonction : is_set
  2. Nombre de paramètres : 1
  3. Paramètres attendus : Une variable de n'importe quel type
  4. Exemple : is_set(MY_VAR) == true

A l'inverse de la fonction is_empty, la fonction is_set permet de savoir si une variable possède une valeur.

La fonction renverra VRAI pour n'importe quelle variable non-vide : "une chaîne", un nombre tel que 12.45 ou même 0 (zéro), une liste non-vide etc.

Récupérée de « https://wiki.hercule.co/index.php?title=SmartExpressions&oldid=1211 »