Paramètres et Modèles Liquid

Ce guide vous montrera comment créer et utiliser des paramètres personnalisés dans vos rapports. Le module « Params » vous permet de définir des champs de saisie en utilisant YAML. Ces paramètres peuvent ensuite être insérés dynamiquement dans vos requêtes en utilisant le langage de modèles Liquid, rendant vos rapports flexibles et interactifs.

Vue d'Ensemble

L'interface « Params » est conçue pour être intuitive. Vous verrez généralement deux sections principales :

Formulaire de Paramètres (Panneau Supérieur) : Cette zone affiche le formulaire interactif généré à partir de vos définitions YAML. Vous ou d'autres utilisateurs finaux utiliserez ce formulaire pour saisir des valeurs pour les paramètres.
Éditeur YAML (Panneau Inférieur) : C'est ici que vous, en tant que concepteur du rapport, définirez la structure et le type de chaque paramètre en utilisant YAML. Les modifications ici sont reflétées dans le Formulaire de Paramètres.

Overall UI Overview

Définir des Paramètres avec YAML

Les paramètres sont définis dans l'éditeur YAML. Chaque paramètre a un nom (qui sera sa clé) et un ensemble de propriétés qui définissent son comportement et son apparence dans le formulaire.

Structure de Base

Voici une structure générale pour définir un paramètre :

parameter_name:
    type: 'inputType'
    description: 'A helpful description for the user.'
    # Other properties specific to the type...

parameter_name : C'est ainsi que vous ferez référence au paramètre dans vos modèles Liquid (p.ex., {{ parameter_name }}).
type : Spécifie le type de champ de saisie. Les types courants incluent text, number, date, select et multiselect.
description : (Optionnel mais fortement recommandé) Fournit une info-bulle ou un texte d'aide à côté du paramètre dans le formulaire. Les utilisateurs peuvent souvent le voir en cliquant sur une icône « i » (information).

Types de Paramètres Courants

1. Saisie de Texte

Pour du texte général, des noms, des titres ou toute donnée de chaîne.

report_title:
    type: 'text'
    description: 'Entrez le titre principal pour votre rapport.'

2. Saisie Numérique

Pour des valeurs numériques, comme des quantités, des montants ou des identifiants.

minimum_amount:
    type: 'number'
    description: 'Filtrer les résultats supérieurs à ce montant.'
item_count:
    type: 'number'
    description: 'Spécifier le nombre d'éléments.'

3. Saisie de Date

Pour sélectionner des dates. Les dates sont généralement attendues au format YYYY-MM-DD.

start_date:
    type: 'date'
    description: 'Sélectionnez la date de début pour la plage de données.'
end_date:
    type: 'date'
    description: 'Sélectionnez la date de fin pour la plage de données.'

Paramètres Select et Multiselect

Ces types permettent aux utilisateurs de choisir parmi une liste prédéfinie d'options.

1. Options Statiques

Vous pouvez définir des options directement dans le YAML.

Liste Simple : Chaque élément de la liste devient à la fois l'étiquette d'affichage et la valeur soumise.

status_filter_simple:
    type: 'select'
    description: 'Filtrer par un statut simple.'
    options:
        - "En attente"
        - "Terminé"
        - "Échoué"

Paires Étiquette-Valeur : Fournissez un tableau où le premier élément est l'étiquette d'affichage et le second est la valeur soumise. C'est utile lorsque le texte d'affichage doit être plus convivial que la valeur réelle utilisée dans une requête.

country_code_selector:
    type: 'select'
    description: 'Sélectionnez un pays.'
    options:
        - [ "États-Unis", "US" ]
        - [ "Canada", "CA" ]
        - [ "Royaume-Uni", "GB" ]
        - [ "Australie", "AU" ]

user_roles_multiselect:
    type: 'multiselect'
    description: 'Sélectionnez un ou plusieurs rôles d'utilisateur.'
    options:
        - [ "Administrator", "admin" ]
        - [ "Editor", "editor" ]
        - [ "Viewer", "viewer" ]

Pour multiselect, la valeur du paramètre sera un tableau des valeurs sélectionnées (p.ex., ["admin", "viewer"]).

2. Options Dynamiques (depuis des Requêtes)

Une fonctionnalité puissante est de remplir les options select ou multiselect à partir des résultats d'une autre requête déjà définie dans votre module « Queries ». C'est extrêmement utile pour garantir que vos menus déroulants ont toujours les dernières données (p.ex., une liste de clients, produits ou catégories).

Pour ce faire, utilisez les clés query, labels et values sous options :

customer_id:
    type: 'select'
    description: 'Sélectionnez un client dans la liste.'
    options:
        query: 'all_customers_query'  # Nom d'une requête existante qui retourne des données clients
        labels: 'customer_name'       # Colonne de 'all_customers_query' à afficher comme étiquettes
        values: 'id'                  # Colonne de 'all_customers_query' à utiliser comme valeurs d'option

product_skus:
    type: 'multiselect'
    description: 'Sélectionnez un ou plusieurs produits.'
    options:
        query: 'active_products_query' # Nom d'une requête existante qui retourne des données produits
        labels: 'product_title'        # Colonne de 'active_products_query' pour l'affichage
        values: 'sku'                  # Colonne de 'active_products_query' pour les valeurs d'option

Important :

Les requêtes spécifiées (p.ex., all_customers_query, active_products_query) doivent être des requêtes de rapport définies et retourner des données.
Les champs labels et values doivent correspondre aux noms de colonnes réels dans la sortie de ces requêtes.

Utilisation des Paramètres dans les Requêtes avec Liquid

Une fois que les paramètres sont définis et que les utilisateurs fournissent des valeurs via le formulaire, vous pouvez utiliser ces valeurs dans vos requêtes SQL (ou d'autres types de scripts pris en charge par le module « Queries ») en utilisant des modèles Liquid.

Liquid est un langage de modèles qui vous permet d'intégrer du contenu dynamique. Les valeurs des paramètres sont insérées en utilisant des doubles accolades : {{ parameter_name }}.

Interpolation de Variables de Base

Supposons que vous avez défini les paramètres suivants en YAML :

start_date:
    type: 'date'
end_date:
    type: 'date'
status:
    type: 'select'
    options:
        - "Active"
        - "Inactive"
minimum_value:
    type: 'number'

Et un utilisateur fournit les valeurs suivantes :

start_date : 2024-01-01
end_date : 2024-03-31
status : Active
minimum_value : 100

Vous pouvez les utiliser dans une requête SQL comme ceci :

SELECT *
FROM transactions
WHERE transaction_date BETWEEN '{{start_date}}' AND '{{end_date}}'
  AND account_status = '{{status}}'
  AND amount >= {{minimum_value}};

Lorsque la requête s'exécute, Liquid la traitera et le SQL réel envoyé à la base de données sera :

SELECT *
FROM transactions
WHERE transaction_date BETWEEN '2024-01-01' AND '2024-03-31'
  AND account_status = 'Active'
  AND amount >= 100;

Note sur les Guillemets SQL :

Liquid insère la valeur du paramètre directement.
Pour les valeurs de chaîne ou de date en SQL, assurez-vous d'envelopper la balise Liquid dans des guillemets simples : '{{parameter_name}}'.
Pour les valeurs numériques, les guillemets ne sont généralement pas nécessaires : {{numeric_parameter}}.

Modèles Liquid Avancés

Liquid offre plus que la simple substitution de variables. Vous pouvez utiliser des balises pour la logique (comme les conditions if et les boucles for) et des filtres pour modifier les variables.

Logique Conditionnelle : `if`, `elsif`, `else`

Vous pouvez inclure conditionnellement des parties de votre requête en utilisant des balises {% if %}. C'est très utile pour les filtres optionnels.

Syntaxe : {% if condition %} ... partie SQL à inclure si la condition est vraie ... {% elsif another_condition %} ... partie SQL si la première condition est fausse et celle-ci est vraie ... {% else %} ... partie SQL si toutes les conditions précédentes sont fausses ... {% endif %}

Exemple : Filtre client optionnel.

Supposons que vous avez un paramètre customer_id qui pourrait être vide si l'utilisateur veut voir les données pour tous les clients.

# Parameter definition
optional_customer_id:
    type: 'number'
    description: 'Entrez l'ID client (optionnel). Laissez vide pour tous les clients.'
# Supposons également un paramètre 'department' (texte)
department:
    type: 'text'
    description: 'Filtrer par département (p.ex., Ventes, RH).'

Query:

SELECT *
FROM employee_data
WHERE 1 = 1 -- Une astuce courante pour garantir que les clauses AND peuvent toujours être ajoutées
    {% if department and department != "" %}
  AND department_name = '{{department}}'
{% endif %}
{% if optional_customer_id %}
  AND customer_id = {{optional_customer_id}}
{% endif %}

Si department est "Ventes" et optional_customer_id est 123, cela rend :

SELECT *
FROM employee_data
WHERE 1=1
  AND department_name = 'Sales'
  AND customer_id = 123

Si department est vide et optional_customer_id est également vide, cela rend :
```
SELECT *
FROM employee_data
WHERE 1=1
```
(La vérification department != "" gère les cas où une chaîne vide pourrait être passée pour un champ de texte.)

Boucles : `for`

Les boucles sont essentielles lors du traitement de paramètres qui peuvent avoir plusieurs valeurs, comme ceux d'une entrée multiselect. Un cas d'utilisation courant est la construction de clauses SQL IN.

Syntaxe : {% for item in collection %} ... contenu à répéter pour chaque élément ... {{ item }} ... {{ forloop.index }} ... {{ forloop.last }} {% endfor %}

Exemple : Filtrage par plusieurs SKU de produits à partir d'un paramètre multiselect.

# Parameter definition
selected_skus:
    type: 'multiselect'
    description: 'Sélectionnez un ou plusieurs SKU de produits.'
    options:
        query: 'all_products'
        labels: 'product_name'
        values: 'sku'

Si un utilisateur sélectionne des SKU : ["ABC-1001", "XYZ-2002", "DEF-3003"], le paramètre selected_skus contiendra ce tableau.

Query:

SELECT *
FROM products
WHERE 1 = 1 {% if selected_skus and selected_skus.size > 0 %}
  AND sku IN (
    {% for current_sku in selected_skus %}
      '{{ current_sku }}'{% unless forloop.last %},{% endunless %}
    {% endfor %}
  )
{% endif %}

selected_skus.size > 0 : Vérifie si le tableau n'est pas vide. (.size est une façon courante en Liquid d'obtenir la longueur du tableau ou la longueur de la chaîne).
{% for current_sku in selected_skus %} : Parcourt chaque SKU dans le tableau.
'{{ current_sku }}' : Met chaque SKU entre guillemets simples (en supposant que les SKU sont des chaînes).
{% unless forloop.last %},{% endunless %} : Ajoute une virgule après chaque SKU, sauf s'il s'agit du dernier élément de la boucle. Cela crée une liste SQL correctement formatée.

SQL rendu si selected_skus est ["ABC-1001", "XYZ-2002"] :

SELECT *
FROM products
WHERE 1 = 1
  AND sku IN (
              'ABC-1001',
              'XYZ-2002'
    )

Filtres Liquid

Les filtres modifient la sortie des variables ou des objets Liquid. Ils sont utilisés avec un caractère de barre verticale |. {{ variable | filter_name: argument }}

Voici quelques filtres courants et utiles :

default : Fournit une valeur de secours si la variable est vide ou non définie.

-- Traitement pour la région : {{ region_param | default: 'Amérique du Nord' }}
WHERE start_date >= '{{ start_date_param | default: "2024-01-01" }}'

date : Formate une date. L'entrée peut être un timestamp, une chaîne de date reconnue par Liquid, ou le mot spécial "now" (ou "today").
```
-- Rapport généré le : {{ "now" | date: "%Y-%m-%d %H:%M:%S" }}
-- Mois de transaction : {{ transaction_date_param | date: "%B %Y" }}
```
(Note : Les paramètres de date du formulaire peuvent déjà être au format compatible SQL YYYY-MM-DD, donc le reformatage pourrait ne pas toujours être nécessaire pour les clauses SQL WHERE mais peut être utile pour les commentaires ou l'affichage.)
Manipulation de Chaînes :
- upcase, downcase, capitalize:
```
WHERE product_category = '{{ category_param | upcase }}'
```
- append, prepend : Ajoute du texte au début ou à la fin.
```
{% assign log_prefix = user_id_param | prepend: "User_" %}
-- Préfixe de Log : {{ log_prefix }}
```
- replace, replace_first : Remplace les occurrences d'une sous-chaîne.
```
-- {{ 'Rapport des Ventes pour T1' | replace: 'T1', 'T2' }}
-- Rend : Rapport des Ventes pour T2
```
- strip, lstrip, rstrip : Supprime les espaces blancs.
- truncate : Raccourcit une chaîne à une longueur spécifiée. {{ long_description | truncate: 25, "..." }} (affiche les 25 premiers caractères, puis "...")
- escape : Échappe une chaîne (p.ex., pour HTML ou XML, moins courant directement dans les valeurs SQL mais utile pour les commentaires ou le code généré). -- Commentaire utilisateur : {{ user_comment_param | escape }}

Filtres de Tableau/Collection :

size : Retourne le nombre d'éléments dans un tableau ou de caractères dans une chaîne. (Déjà utilisé dans l'exemple de boucle for).

join : Joint les éléments du tableau en une chaîne avec un séparateur.

{% comment %} Si selected_tags_param est ("urgent", "révision"( {% endcomment %}
-- Étiquettes : {{ selected_tags_param | join: ", " }}
-- Rend : Étiquettes : urgent, révision

first, last : Obtient le premier ou le dernier élément d'un tableau.

map : Itère sur un tableau et extrait une propriété de chaque élément (si les éléments sont des objets) ou applique un filtre à chaque élément.

{% comment %}
  Si items_param est ({id:1, name:"A"}, {id:2, name:"B"})
  Cela créerait un tableau comme (1, 2)
{% endcomment %}
{% assign item_ids = items_param | map: "id" %}

{% comment %}
  Si string_numbers_param est ("10", "20", "30")
  Cela peut tenter de les convertir (le comportement dépend de la variante de Liquid)
  Une astuce courante pour convertir une chaîne en nombre est 'plus: 0' si 'to_number' n'est pas disponible.
{% endcomment %}
{% assign numeric_values = string_numbers_param | map: plus: 0 %}

{% comment %}
  Si categories_param est ("électronique", "livres")
  Cela crée ("ÉLECTRONIQUE", "LIVRES")
{% endcomment %}
{% assign uppercased_categories = categories_param | map: 'upcase' %}

uniq : Supprime les éléments en double d'un tableau.
sort : Trie un tableau. Peut prendre un nom de propriété pour les objets. {% endraw %}

Filtres Mathématiques :

plus, minus, times, divided_by, modulo : Effectuent des opérations arithmétiques.

{% assign page_size = 20 %}
{% assign current_page = page_number_param | default: 1 %}
{% assign offset_value = current_page | minus: 1 | times: page_size %}
LIMIT {{ page_size }} OFFSET {{ offset_value }}

Affectation de Variables : `assign`

Vous pouvez créer de nouvelles variables Liquid dans votre modèle.

{% assign default_records_limit = 50 %}
{% assign records_to_fetch = user_limit_param | default: default_records_limit %}
SELECT * FROM data_table LIMIT {{ records_to_fetch }};

Capture de Sortie : `capture`

Vous pouvez capturer un bloc de sortie Liquid rendue dans une variable.

{% capture filename %}report_{{ report_type_param | default: 'generic' }}_{{ "now" | date: "%Y%m%d" }}.csv{% endcapture %}
-- Nom de fichier suggéré : {{ filename }}

Logique Case/When (Instruction Switch)

Pour une logique conditionnelle plus complexe basée sur la valeur d'une seule variable.

{% assign status_id_value = 0 %}
{% case status_param %}
  {% when "Pending" %}
    {% assign status_id_value = 1 %}
  {% when "Active" %}
    {% assign status_id_value = 2 %}
  {% when "Closed" %}
    {% assign status_id_value = 3 %}
  {% else %}
    {% assign status_id_value = -1 %}
{% endcase %}

SELECT * FROM items WHERE status_identifier = {{ status_id_value }};

Sauvegarde de vos Paramètres

Après avoir défini ou modifié vos paramètres dans l'éditeur YAML, ou lorsque les valeurs par défaut du formulaire doivent être persistées, vous devrez les sauvegarder. Recherchez un bouton ou une icône « Sauvegarder », souvent un symbole de nuage ou de disque. Cette action stockera votre configuration YAML et toutes les valeurs par défaut actuelles que vous avez définies dans le formulaire.

Conseils et Bonnes Pratiques

Noms Descriptifs : Utilisez des noms clairs et significatifs pour vos paramètres. start_date est mieux que d1.
Toujours Ajouter des Descriptions : Le champ description est inestimable pour les utilisateurs finaux qui pourraient ne pas connaître le but de chaque paramètre.
Tester Soigneusement : Après avoir configuré les paramètres et les avoir utilisés dans les requêtes, testez avec diverses entrées :
- Valeurs valides.
- Valeurs vides (si optionnelles).
- Cas limites.
Guillemets SQL : Rappelez-vous que Liquid insère les valeurs telles quelles. Les valeurs de chaîne et de date dans les requêtes SQL doivent généralement être entourées de guillemets simples ('{{my_string_param}}'). Les valeurs numériques n'en ont généralement pas besoin.
multiselect et Clauses IN : Lors de l'utilisation de multiselect pour les clauses SQL IN, utilisez la boucle for avec forloop.last pour formater correctement la liste séparée par des virgules, et assurez-vous que les valeurs de chaîne dans la liste sont individuellement entre guillemets si nécessaire.
Commencer Simple : Si vous êtes nouveau avec Liquid, commencez par des interpolations de variables de base et introduisez progressivement une logique plus complexe comme les conditions if et les boucles for selon les besoins.
Consulter la Documentation Liquid : Liquid a beaucoup plus de fonctionnalités. Si vous avez une transformation spécifique en tête, la documentation officielle de Liquid (ou celle spécifique à l'implémentation Liquid de votre plateforme) peut être une excellente ressource.

En maîtrisant les paramètres et les modèles Liquid, vous pouvez créer des rapports hautement dynamiques et conviviaux qui s'adaptent à divers besoins analytiques.

Aperçu

Commencer

Rapports

Intégrations

Paramètres et Modèles Liquid

Vue d'Ensemble

Définir des Paramètres avec YAML

Structure de Base

Types de Paramètres Courants

1. Saisie de Texte

2. Saisie Numérique

3. Saisie de Date

Paramètres Select et Multiselect

1. Options Statiques

2. Options Dynamiques (depuis des Requêtes)

Utilisation des Paramètres dans les Requêtes avec Liquid

Interpolation de Variables de Base

Modèles Liquid Avancés

Logique Conditionnelle : `if`, `elsif`, `else`

Boucles : `for`

Filtres Liquid

Affectation de Variables : `assign`

Capture de Sortie : `capture`

Logique Case/When (Instruction Switch)

Sauvegarde de vos Paramètres

Conseils et Bonnes Pratiques

Aperçu

Commencer

Rapports

Intégrations

Paramètres et Modèles Liquid

Vue d'Ensemble

Définir des Paramètres avec YAML

Structure de Base

Types de Paramètres Courants

1. Saisie de Texte

2. Saisie Numérique

3. Saisie de Date

Paramètres Select et Multiselect

1. Options Statiques

2. Options Dynamiques (depuis des Requêtes)

Utilisation des Paramètres dans les Requêtes avec Liquid

Interpolation de Variables de Base

Modèles Liquid Avancés

Logique Conditionnelle : if, elsif, else

Boucles : for

Filtres Liquid

Affectation de Variables : assign

Capture de Sortie : capture

Logique Case/When (Instruction Switch)

Sauvegarde de vos Paramètres

Conseils et Bonnes Pratiques

Logique Conditionnelle : `if`, `elsif`, `else`

Boucles : `for`

Affectation de Variables : `assign`

Capture de Sortie : `capture`