Skip to content

Commit

Permalink
add substr
Browse files Browse the repository at this point in the history 
+ improve simple response
+ move example from vtl to vtl functions
+ add example from Demo
  • Loading branch information
@JulienCarmona
JulienCarmona committed Feb 12, 2025
1 parent d2a99c6 commit 35fbdad
Show file tree
Hide file tree
Showing 6 changed files with 121 additions and 86 deletions.
74 changes: 70 additions & 4 deletions bowiedocs/docs/1._Pogues/Le VTL dans Pogues/fonctions-vtl.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,11 @@
# Fonctions VTL et usages

## Liste de fonctions
### Les plus utilisés
| Method | Description |
| ----------- | ------------------------------------ |
| [**`nvl()`**](fonctions-vtl.md/#nvl) | Permet de gérer la nullité |
| [**`cast()`**](fonctions-vtl.md/#cast) | Permet de changer le tye de la donnée |
| [**`substr()`**](fonctions-vtl.md/#substr) | :construction: Coming soon ... |
| [**`cast()`**](fonctions-vtl.md/#cast) | Permet de changer le type de la donnée |
| [**`substr()`**](fonctions-vtl.md/#substr) | Permet d'extraire un sous ensemble de caractère d'un texte
| [**`isnull()`**](fonctions-vtl.md/#isnull) | :construction: Coming soon ... |
| [**`in`**](fonctions-vtl.md/#in) | Permet de tester l'appartenance d'une valeur à un ensemble |
| [**`if ... then ...`**](fonctions-vtl.md/#if-then) | :construction: Coming soon ... |
Expand Down Expand Up @@ -163,9 +162,75 @@
Renvoie `true` si la date d'arrivée est postérieure à la date de départ et `false` sinon.

##### substr
:construction: Coming soon ...

!!! question "Utilité"
Retourne la partie d'une chaîne de caractères comprise entre l'indice de départ et un certain nombre de caractères après celui-ci. <br>
Par exemple pour une Date qui est une chaîne de caractère au format `"AAAA-MM-JJ"`, on veut récupérer uniquement l'année. On va donc récupérer uniquement les 4 premiers caractères de cette chaîne : `substr("AAAA-MM-JJ", 1, 4)` renvoie la chaîne `"AAAA"`

!!! abstract "Syntaxe"
```
substr(<var>, <index>, <longueur>)
```

- `var` : variable de type `string` (texte/chaîne de caractère) sur laquelle on veut extraire un sous ensemble caractères
- `index` : position, dans la chaîne de caractères `var`, du départ du sous ensemble à extraire
- `longueur` : taille du sous ensemble à extraire

=== "Texte"
| Valeur de `MA_VARIABLE` | Fonction | Résultat |
| --- | ---| --- |
| `"mon texte complet !"` | `substr($MA_VARIABLE$, 1, 5)` | `"mon t"` |
| `"mon texte complet !"` | `substr($MA_VARIABLE$, 3, 5)` | `"on te"` |
| `"mon texte complet !"` | `substr($MA_VARIABLE$, 3, 11)` | `"on texte co"` |


??? example "Exemple d'utilisation"
=== "Date"
On a créé une question dont la réponse est au format Date `"AAAA-MM-JJ"` dans Pogues, la variable collectée est `DATE_NAISSANCE` avec la valeur `"1995-02-15"`.
On peut extraire les éléments suivant :
=== "l’année"
```
substr($DATE_NAISSANCE$, 1, 4) -> "1995"
```
=== "le mois"
```
substr($DATE_NAISSANCE$, 6, 2) -> "02"
```
=== "le jour"
```
substr($DATE_NAISSANCE$, 9, 2) -> "15"
```

=== "Formater l'affichage d'une date"
Comme vu plus haut, le format des variables Date n'est pas forcément idéal pour l'affichage, on veut pouvoir présenter l'information avec le motif `"JJ/MM/AAAA"` (jour, mois, année).

Le code suivant permet cette transformation :
```
substr(cast($DATE$, string, "YYYY-MM-DD"), 9, 2) ||
"/" ||
substr(cast($DATE$, string, "YYYY-MM-DD"), 6, 2) ||
"/" ||
substr(cast($DATE$, string, "YYYY-MM-DD"), 1, 4)
```

Si `DATE` vaut `"1995-02-15"`, alors la function ci dessus renvoie `"15/02/1995"`

=== "Gestion des majuscules"
Imaginons que l'on collecte un prénom à travers la bien nommée variable `PRENOM`. On souhaite que quelque soit la casse de la réponse, on affiche le prénom sous la forme `Prénom`. <br>
Voici une formule pour le cas d'un prénom simple:
```
upper(substr(PRENOM, 1, 1)) || lower(substr(PRENOM, 2, length(PRENOM)))
```

!!! warning ""
:warning: cela ne fonctionnera pas pour les prénoms composés pour lesquels il sera nécessaire de rendre compte d'un séparateur (un espace, un tiret).



##### isnull

:construction: Coming soon ...

##### in

!!! question "Utilité"
Expand Down Expand Up @@ -200,5 +265,6 @@
```

##### if ... then ...

:construction: Coming soon ...

49 changes: 4 additions & 45 deletions bowiedocs/docs/1._Pogues/Le VTL dans Pogues/vtl.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -167,51 +167,12 @@ C’est l’état d’avancement de cette dernière qui permet de connaître les
| ------------ | ------- | ---------------------------------- |
| Remplacement | replace | `replace("bag", "g", "c") # → bac` |

## Cookbook

### Chaînes de caractères

#### Gestion des majuscules

Imaginons que l'on collecte un prénom à travers la bien nommée variable `PRENOM`. On souhaite que quelque soit la casse de la réponse, on affiche le prénom sous la forme `Prénom`.

Voici une formule pour le cas d'un prénom simple:

```
upper(substr(PRENOM, 1, 1)) || lower(substr(PRENOM, 2, length(PRENOM)))
```

Attention, cela ne fonctionnera pas pour les prénoms composés pour lesquels il sera nécessaire de rendre compte d'un séparateur (un espace, un tiret).

### Dates

#### Récupérer l'année

On a créé une question dont la réponse est au format Date dans Pogues, la variable collectée `DATE_NAISSANCE`.

Voici comment obtenir l’année :
!!! tip "Aide"
Une page référençant les fonctions les plus utilisées avec des exemples est disponible [ici](fonctions-vtl.md)

```
substr(cast($DATE_NAISSANCE$, string, "YYYY-MM-DD"), 1, 4)
```

On transforme la variable de type date en chaîne de caractères, puis on extrait les 4 premiers caractères. Le motif "YYYY-MM-DD" permet de la traduction

<span class="label label-rounded label-warning">Attention !</span> Si Pogues permet de choisir trois types de formats de date, seul le format JJMMAAAA (jour, mois, année) est aujourd’hui proposé à l’enquêté. Par ailleurs, si le format présenté lui-même est JJMMAAAA, la variable collectée est au format AAAAMMJJ, ce qui explique le code VTL précédent.

#### Formater l'affichage de la date

Comme vu plus haut, le format des variables Date n'est pas forcément idéal pour l'affichage, on veut pouvoir présenter l'information avec le motif `JJ/MM/AAAA` (jour, mois, année).

Le code suivant permet cette transformation :
## Cookbook

```
substr(cast($DATE$, string, "YYYY-MM-DD"), 9, 2) ||
"/" ||
substr(cast($DATE$, string, "YYYY-MM-DD"), 6, 2) ||
"/" ||
substr(cast($DATE$, string, "YYYY-MM-DD"), 1, 4)
```
### Durée

#### Calcul de durée

Expand All @@ -233,8 +194,6 @@ Pour plus de clarté, le calcul de la durée brute pourra être déportée dans
$DUREE$ / 86400000
```

### Durée

#### Contrôler un dépassement de borne

Une variable de type Durée aura une des formes suivantes :
Expand Down
69 changes: 40 additions & 29 deletions bowiedocs/docs/1._Pogues/Le guide/13-reponse-simple.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,41 +6,44 @@ Pour créer une question de type **Réponse simple**, remplir, pour toutes les v
- le _type de réponse_ (Texte, Date, Nombre, Booléen, Durée)

## Type de réponse Texte
Renseigner aussi :
**Paramètres :**

- la _longueur maximale_ de la réponse (nombre de caractères)
- le _motif_ (non fonctionnel pour l'instant, il permettra de spécifier des expressions régulières comme un Siret, un mèl etc.)

!!! info
- A l'initialisation du questionnaire, tout champ texte vaut `null`
- Quand on saisie une valeur, ex `"mon texte"`, puis qu'on efface cette valeur du champ, alors le champ texte vaut `""` et non pas `null` comme au début.

C'est pourquoi quand on veut **[gérer la nullité](../Le%20VTL%20dans%20Pogues/vtl.md/#gestion-de-la-nullite)**, on remplace les valeurs `null` par `""` pour gérer les cas de champ texte vide. <br>
C'est pourquoi, pour gérer les cas de champ texte vide, il faut **[gérer la nullité](../Le%20VTL%20dans%20Pogues/vtl.md/#gestion-de-la-nullite)**. On remplace ainsi les valeurs `null` par `""` . <br>
Ex de condition d'affichage d'un contrôle pour indiquer qu'un champ texte est vide
```
nvl($VAR$, "") = ""
```

## Type de réponse Date
Renseigner aussi :
**Paramètres :**

- le _format_ parmi `AAAA-MM-JJ`, `AAAA-MM` et `AAAA`
- un _minimum_ et un _maximum_

!!! info
- A l'initialisation du questionnaire, tout champ date vaut `null`
- Quand on saisie une valeur, ex pour juste une année `2025`, puis qu'on efface cette valeur du champ, alors le champ date vaut `null` comme au début.

!!! warning "Type d'une point de vu VTL"
- D'un point de vu Pogues, on parle bien d'un type *Date*, mais d'un point de vu VTL, une variable de type *Date* va en réalité être collecté en tant que **texte** sous l'un des formats cités plus haut.
- Quand on saisit une valeur, ex pour juste une année `2025`, puis qu'on efface cette valeur du champ, alors le champ date vaut `null` comme au début.
- Pour gérer un champ Date vide il suffit d'utiliser [isnull()](../Le%20VTL%20dans%20Pogues/fonctions-vtl.md/#isnull)
```
isnull($DATE$)
```

!!! warning "Type d'une point de vue VTL"
- D'un point de vue Pogues, on parle bien d'un type *Date*, mais d'un point de vue VTL, une variable de type *Date* va en réalité être collectée en tant que **texte** sous l'un des formats cités plus haut.

??? example "Exemple"
Si on collecte une date `ANNEE_NAIS` sous le format `AAAA-MM-JJ` et que l'on saisie les valeurs suivantes
![alt text](../../img/pogues/date_input.png)

alors la variabel `ANNEE_NAIS` aura la valeur `"2025-02-01"` est sera un texte

C'est pourquoi il est nécessaire de [cast()](../Le%20VTL%20dans%20Pogues/fonctions-vtl.md/#cast) ces variables en `date` pour les comparer. Voir [exemple d'utilisation](../Le%20VTL%20dans%20Pogues/fonctions-vtl.md/#__tabbed_5_3)
C'est pourquoi il est nécessaire de transtyper en utilisant la fonction [cast()](../Le%20VTL%20dans%20Pogues/fonctions-vtl.md/#cast) ces variables en `date` pour les comparer. Voir [exemple d'utilisation](../Le%20VTL%20dans%20Pogues/fonctions-vtl.md/#__tabbed_5_3)

- Dans cette même logique, cela veut dire que l'on peut directement afficher une variable de type date dans un libellé dans utiliser

Expand All @@ -49,33 +52,36 @@ Renseigner aussi :
![alt text](../../img/pogues/incomplete_date.png)<br>
_Dans cet exemple Quand on regarde la valeur de la variable collecté correspondante, on a `null` car il manque le mois_

- Comme le champ date est incorrect, si on clique sur continuer et qu'on fait précédent, tout les champs de date sont vide
- Comme le champ date est incorrect, si on clique sur continuer et qu'on fait précédent, tous les champs de date sont vides


## Type de réponse Nombre
Renseigner aussi :
**Paramètres :**

- le _minimum_ et le _maximum_
- la _précision_ (nombre de chiffres après la virgule, par défaut : aucun)
- l'_unité_ de mesure fixe ou personnalisée

??? example "Example d'utilisation d'une unité de mesure personnalisée"
___Choix de l'unité de mesure___
![choix unite de mesure perso](../../img/pogues/choix-unite-de-mesure-perso.png)
___Exemple d'une expression VTL pour l'unité de mesure. `(if $DEST$ = "1" then "Dirhams" else "Euros")`___
![unite mesure perso](../../img/pogues/unite-mesure-perso.png)
___Si on choisi "Espagne" (`DEST=2`) alors on tombe dans le `else` et l'unité mesurée est "Euros"___
![unite mesure perso euro](../../img/pogues/unite-mesure-perso-euro.png)
___Si on choisi "Maroc" (`DEST=1`) alors on tombe dans la condition du `if` et l'unité mesurée est "Dirham"___
![unite mesure perso dirham](../../img/pogues/unite-mesure-perso-dirhams.png)
- l'_unité de mesure_ fixe ou personnalisée

??? example "Exemple d'utilisation d'une unité de mesure personnalisée"
___Choix de l'unité de mesure___
![choix unite de mesure perso](../../img/pogues/choix-unite-de-mesure-perso.png)
___Exemple d'une expression VTL pour l'unité de mesure. `(if $DEST$ = "1" then "Dirhams" else "Euros")`___
![unite mesure perso](../../img/pogues/unite-mesure-perso.png)
___Si on choisi "Espagne" (`DEST=2`) alors on tombe dans le `else` et l'unité mesurée est "Euros"___
![unite mesure perso euro](../../img/pogues/unite-mesure-perso-euro.png)
___Si on choisi "Maroc" (`DEST=1`) alors on tombe dans la condition du `if` et l'unité mesurée est "Dirham"___
![unite mesure perso dirham](../../img/pogues/unite-mesure-perso-dirhams.png)

!!! info
- A l'initialisation du questionnaire, tout champ nombre vaut `null`
- Quand on saisie une valeur, ex `86`, puis qu'on efface cette valeur du champ, alors le champ nombre vaut `null` comme au début.

- Pour gérer un champ Nombre vide il suffit d'utiliser [isnull()](../Le%20VTL%20dans%20Pogues/fonctions-vtl.md/#isnull)
```
isnull($NOMBRE$)
```

## Type de réponse Booléen
On ne renseigne rien (unique cache à cocher cochable/décochable).

**Pas de paramètres**
!!! info
- A l'initialisation du questionnaire, tout champ booléen vaut `null`. La case est visuellement décochée.
- Quand on coche la case, alors la valeur collectée est `true`, puis quand on décoche, alors la valeur collectée est `false`.
Expand All @@ -87,13 +93,18 @@ On ne renseigne rien (unique cache à cocher cochable/décochable).
```

## Type de réponse Durée
Renseigner aussi le _format_ parmi heures-minutes ou années-mois.
**Paramètres :**

- le _format_ parmi

- pour une mesure en "années/mois" : `PnaYnmM` où `na` sera le nombre d'années et `nm` le nombre de mois (ex : `P3Y10M` pour "trois ans et dix mois")
- pour une mesure en "heures/mois" : `PTnhHnmM` avec `nh` le nombre d'heures et `nm` le nombre de minutes (ex : `PT12H30M` pour "douze heures et trente minutes").
- **années/mois** : `PnaYnmM` où `na` sera le nombre d'années et `nm` le nombre de mois (ex : `P3Y10M` pour "trois ans et dix mois")
- **heures/minutes** : `PTnhHnmM` avec `nh` le nombre d'heures et `nm` le nombre de minutes (ex : `PT12H30M` pour "douze heures et trente minutes").


!!! info
- A l'initialisation du questionnaire, tout champ durée vaut `null`.
- Quand on saisie une valeur, ex `2025` et `12` pour année/mois, puis qu'on efface ces deux valeurs des champs, alors le champ durée vaut `null` comme au début.

- Pour gérer un champ Durée vide il suffit d'utiliser [isnull()](../Le%20VTL%20dans%20Pogues/fonctions-vtl.md/#isnull)
```
isnull($DUREE$)
```
4 changes: 4 additions & 0 deletions bowiedocs/docs/1._Pogues/Le guide/15b-suggester.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,3 +68,7 @@ Je peux ensuite afficher cette valeur, par exemple dans une déclaration, en app
Elle est bien considérée comme une variable collectée dans Lunatic. On peut la récupérer en téléchargeant les données depuis la visualisation DSFR. <br>
A terme, on aura un UX dans Pogues qui sera plus cohérent avec ce concept. <br>
Ex : Un bouton qui permet d'ajouter une paire clé/valeur qui indique le nom de la nouvelle variable collecté et le nom de la colonne dans la nomenclature

### Questionnaire exemple

Pour référence, un [questionnaire implémentant cette solution](https://conception-questionnaires.demo.insee.io/questionnaire/m1holrzlDOC) est disponible dans l'environnement de demo, sous le timbre DOCUMENTATION
8 changes: 1 addition & 7 deletions bowiedocs/docs/1._Pogues/Quelques cas pratiques/declarations-complexes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,10 +51,4 @@ Dépense 4 : " || nvl(cast($VAR4$,string),"///") ```
```

!!!note

La déclaration n'a cependant pas vocation à être trop complexe car trop longue, elle pourrait ne pas être lue par l'enquêté.


## Questionnaire exemple

A venir
La déclaration n'a cependant pas vocation à être trop complexe car trop longue, elle pourrait ne pas être lue par l'enquêté.
3 changes: 2 additions & 1 deletion bowiedocs/docs/1._Pogues/Quelques cas pratiques/kish.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -82,4 +82,5 @@ Le filtre a pour formule `$KISH_INDICATOR$ = 1`.

## Questionnaire exemple

Pour référence, [un questionnaire implémentant cette solution](https://pogues.demo.insee.io/questionnaire/l8lfytfu).
Pour référence, un [questionnaire implémentant cette solution](https://conception-questionnaires.demo.insee.io/questionnaire/l8lfytfu) est disponible dans l'environnement de demo, sous le timbre DOCUMENTATION

0 comments on commit 35fbdad

Please sign in to comment.