# Les Formules

Une formule est une expression qui effectue des calculs sur des valeurs dans votre base de données. Elle peut être aussi simple que l'addition de deux nombres ou aussi complexe que la transformation de plusieurs champs de données selon des critères spécifiques.

La création d'une formule se fait depuis une page d'un **Workflow** ou d'un **Suivi**. Cela peut aussi se faire directement dans une table depuis la vue Data.\


<div><figure><img src="https://2063331370-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQBQ-Fk5qKATOA2R2_R%2Fuploads%2FpZCaVeO6L2YCmkxFh2Gk%2FCapture%20d%E2%80%99e%CC%81cran%202023-10-25%20a%CC%80%2010.20.05.png?alt=media&#x26;token=47d811bb-905e-42db-932c-aad15421792e" alt="" width="354"><figcaption><p>Ajouter une formule depuis un workflow ou suivi</p></figcaption></figure> <figure><img src="https://2063331370-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQBQ-Fk5qKATOA2R2_R%2Fuploads%2FpxfLX3joglvlJVHSXRP3%2FCapture%20d%E2%80%99e%CC%81cran%202023-10-25%20a%CC%80%2010.20.55.png?alt=media&#x26;token=e78598eb-ba6b-4475-861d-17afd0d9ca79" alt="" width="252"><figcaption><p>Ajouter une formule depuis la vue Data</p></figcaption></figure></div>

<figure><img src="https://2063331370-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQBQ-Fk5qKATOA2R2_R%2Fuploads%2FJm6xGRG1dehLejKuCJld%2FCapture%20d%E2%80%99e%CC%81cran%202023-11-10%20a%CC%80%2010.11.59.png?alt=media&#x26;token=328a7700-03b0-4208-939e-d51ba99bc903" alt=""><figcaption><p>Éditeur de formule</p></figcaption></figure>

### ⬅️ Type de retour

Chaque formule a un type de retour, par exemple la formule `UPPER("hello")` renvoie un texte, et peut alors être utilisée partout où ce type le permet, que ce soit dans les filtres, les conditions ou dans des mises à jour de champs.

{% hint style="warning" %}
Vous devez choisir le type de retour la première fois que vous éditez votre formule et vous ne pourrez plus le changer par la suite.
{% endhint %}

Voici la liste exhaustive des types de retour pouvant être utilisés :&#x20;

* 🔤 **Texte**
* 🔢 **Nombre**
* 📆 **Date** & **Date et heure**
* 🗓️ **Plage de dates** & **Plages de dates avec heure**
* 🎨 **Couleur**
* **⚖️ Booléen**
* 🧾 **JSON**
* 📧 **Email**
* 💻 **HTML**
* Les retours de type “liaisons calculées” doivent retourner un identifiant, sélectionnable depuis les métadonnées :&#x20;
  * 🔗 **Liaison simple**
  * 🔗🔗 **Liaisons multiples**
  * 🙏 **Liaison utilisateur**

{% hint style="info" %}
À noter que pour les types de retour liaison simple et liaisons multiples, il vous sera demandé de spécifier la table liée à la formule ainsi que le champ à afficher dans la vue Data
{% endhint %}

#### 🤓 Focus syntaxe : Formules HTML

Pour une formule de type HTML, il faut surcharger les guillemets du code HTML par des apostrophes et inversement (surcharger des apostrophes par des guillemets). Ceci permet de ne pas interférer avec la syntaxe de la formule et de conserver un code HTML fonctionnel.

Voici des exemples de syntaxe correcte :&#x20;

```
"<p style='color:red;'>" & {nom} & "</p>"
```

Ou

```
'<p style="color:red;">' & {nom} & '</p>'
```

### 🛑 Gestion des erreurs

* **Vérification de la syntaxe** : L'éditeur des formules s'assure de la justesse syntaxique de votre expression. Si la formule est incorrecte, comme dans le cas d'une parenthèse manquante, cela vous sera signalé et elle ne sera pas sauvegardée.
* **Erreurs à l'exécution** : Si une formule génère une erreur lors de son exécution (par exemple si on a  `2 ^ "hello"`), elle retournera une valeur nulle et sera traitée de cette manière.

### ≠ Différence avec les formules de texte

Contrairement aux formules de texte, les formules permettent de manipuler tout type de champs, il est alors nécessaire de placer les variables dans des fonctions ou d'utiliser des opérateurs.

Par exemple, `Utilisateur : {Prénom} {Nom}` dans une formule de texte devient `"Utilisateur : " & {Prénom} & " " & {Nom}` dans une formule.

### 🔗 🔗 Liaisons multiples dans les formules

Il est possible d'utiliser un champ issu d'une **liaison multiple** dans les formules. En passant par une **liaisons multiple**, on obtient la liste des valeurs des enregistrements liés pour le champ choisi, qui peut être manipulé avec les fonctions sur les listes.

Par exemple, `{Liaisons multiples -> Nombre}` peut donner `[5,2,3,2,4]` s'il y a 5 enregistrements dans la liaison, avec ces valeurs pour le champ Nombre.\
Donc `SUM({Liaisons multiples -> Nombre})` donne ici `16`, la somme des nombres des enregistrements qui sont dans cette **liaison multiple**.

{% hint style="info" %}
Depuis une liaison multiple, il n’est pas possible d’aller sélectionner des variables au delà du premier niveau de liaison&#x20;
{% endhint %}

### 🧱 Les littéraux

Les littéraux sont des valeurs écrites en dur dans une formule, par opposition à des champs ou des variables dynamiques. Ces éléments sont importants car chaque fonction Ksaar attend un littéral d'un certain type.

**Les différents types de littéraux possibles avec exemples :**&#x20;

* Texte : `"Bonjour"` ou `"2025"`
* Nombre : `42`, `3.14`
* Booléen : `true`, `false`
* Liste : `[1, 2, 3]`, `["pomme", "banane"]`
* Objet : `{nom: "Jean", age: 30}`
* Objet tableau : `{Liaison multiple -> ville}`

### 🚧 Cas d’usage : Liaisons Calculées

Une table Élève contient une liaison simple vers les enregistrements d’une table Classe. Cette table Classe contient une liaison simple vers une table Niveau.

<figure><img src="https://2063331370-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQBQ-Fk5qKATOA2R2_R%2Fuploads%2Fnz0dZiLjVHenta71W7VM%2FUntitled%20(4).png?alt=media&#x26;token=cf7448d3-1737-445e-b8d3-303204bb0f50" alt=""><figcaption><p>Graphique des tables</p></figcaption></figure>

On voudrait conditionner l’affichage d’une ligne en fonction du Niveau auquel les enregistrements de notre table Élève appartiennent.

Pour ce faire, on ajoute un champ Formule de type Liaison Simple dans la table Élève. Cette formule passe par les deux niveaux de liaisons et vient récupérer l’identifiant de l’enregistrement lié :&#x20;

<figure><img src="https://2063331370-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQBQ-Fk5qKATOA2R2_R%2Fuploads%2F75IUfIZCV6AfMyBiJN8R%2FUntitled%20(17).png?alt=media&#x26;token=18cffc46-084a-4942-a93d-b04f2df2ffe5" alt="" width="536"><figcaption><p>Variables à sélectionner dans la formule</p></figcaption></figure>

On lie donc notre formule à la table Niveau et le champ à afficher au nom du Niveau.

Dans les conditions d’affichage de la ligne, il est maintenant possible d’aller chercher le nom du Niveau de l’enregistrement en cours de la table Élève.

<figure><img src="https://2063331370-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MQBQ-Fk5qKATOA2R2_R%2Fuploads%2FD0t3Kd6KHw3dOcP43VRC%2FUntitled%20(18).png?alt=media&#x26;token=65ab9d04-15bd-4eb3-8297-d60e9f52eadb" alt=""><figcaption><p>Condition d’affichage de la ligne</p></figcaption></figure>

### 📖 Fonctions disponibles dans les formules

{% hint style="success" %}
Les fonctions sur les formules sont disponibles dans chacune des sous-pages dédiées :&#x20;

* [operateurs](les-formules/operateurs "mention")
* [fonctions-de-texte](les-formules/fonctions-de-texte "mention")
* [fonctions-mathematiques](les-formules/fonctions-mathematiques "mention")
* [fonctions-de-date](les-formules/fonctions-de-date "mention")
* [fonctions-de-formatage](les-formules/fonctions-de-formatage "mention")
* [fonctions-de-liste](les-formules/fonctions-de-liste "mention")
* [fonctions-sur-des-champs-ksaar](les-formules/fonctions-sur-des-champs-ksaar "mention")
* [fonctions-de-logique-et-autres](les-formules/fonctions-de-logique-et-autres "mention")

Des exemples de formules prêtes à l'emploi se trouvent ici : [bibliotheque-de-formules-classiques](les-formules/bibliotheque-de-formules-classiques "mention")
{% endhint %}
