Documentation en ligne

Les blocs de champs

Les blocs de champs permettent de créer un ensemble de champs qui viendra s'insérer dans un ou plusieurs formulaires. Ils fonctionnent de manière dynamique : une modification apportée à un bloc de champs sera automatiquement répercutée sur tous les formulaires utilisant ledit bloc.

Ces blocs ont par ailleurs la particularité de pouvoir être ajoutés plusieurs fois dans une démarche. Lorsque l'on souhaite par exemple permettre à un usager de joindre plusieurs fichiers dans le formulaire sans en connaître le nombre exact, on peut utiliser un bloc de champs contenant uniquement un champ de type fichier et qui permettra à l'usager d'ajouter autant de fichiers que nécessaire.

Un cas d'usage classique est un bloc de champs « Enfant » (prénom, nom, date de naissance), qui ne sera affiché qu'une fois dans le formulaire à l'origine, mais que le demandeur va pouvoir démultiplier autant de fois que nécessaire en fonction de son nombre d'enfants.

Créer un bloc de champs

Un bloc de champs a un nom, un identifiant - qui permettra d'accéder au bloc avec les variables -, et un gabarit de résumé.

L'ajout, la modification et la réorganisation des champs est identique à la construction d'un formulaire. Il est possible d'ajouter à peu près tous les types de champs habituels, sauf une page, un tableau (tableau simple, tableau de liste et tableau de longueur libre) et les éléments classés.

L'ajout d'un identifiant aux champs du bloc permet d'accéder à la valeur d'un champ, mais contrairement à un champ de formulaire, l'identifiant ne sera pas form_var_identifiant mais sera noté ..._identifiant. les ... seront remplacés par l'identifiant du bloc de champs dans le formulaire, comme on va le voir juste après.

exemple d'un bloc de champs avec des identifiants

L'identifiant du bloc va permettre d'accéder aux valeurs des champs du bloc. Ainsi pour un bloc ayant pour identifiant bloc_enfant, les champs du bloc auront pour identifiant bloc_enfant_prenom, bloc_enfant_nom...

Insérer un bloc de champs dans un formulaire

Une fois un bloc de champs défini, il apparaît automatiquement dans la liste des types de champs, après les champs de mise en forme.

liste des types de champs avec un bloc de champ

Une fois le bloc ajouté, il convient de le paramétrer en indiquant les paramètres habituels d'un champ (obligatoire ou facultatif, l'affichage, les classes de styles, les conditions d'affichage...). Il y a trois paramètres spécifiques au bloc :

  • le nombre maximal d'éléments : le nombre de blocs que l'usager pourra ajouter ; vide ou zéro correspond à aucun : l'usager ne pourra pas ajouter de bloc ;
  • le libellé du bouton « Ajouter » : si vide, le bouton permettant d'ajouter un bloc aura le libellé par défaut "Ajouter un autre" ;
  • Le fait d'afficher un bouton permettant la suppression d'un bloc.
https://doc-publik.entrouvert.com/media/uploads/2021/02/19/blocks-zebra.png
Attention quand vous affichez le bouton permettant la suppression, il faut lui laisser la place d'apparaître. Si vous avez deux champs qui utilisent des grid-1-2 sur la même ligne, l'icône de suppression empiétera sur le deuxième champ. Préférez l'utilisation de grid-5-12 pour ces deux champs.

Accéder aux valeurs

Généralités

Les valeurs de chaque bloc sont accessibles avec un indice incrémentiel.

Ainsi, sur notre exemple ci-dessus, les prénoms des enfants seront accessibles (pour un champ de formulaire ayant pour identifiant enfant_scolarise, par exemple) avec

{{ form_var_enfant_scolarise_0_prenom }}
{{ form_var_enfant_scolarise_1_prenom }}
{{ form_var_enfant_scolarise_2_prenom }}

Pour lister les valeurs d'un champ donné quand on ne sait pas combien de blocs ont été ajoutés, on peut utiliser une boucle :

{% for enfant in form_var_enfant_scolarise %}{{ enfant.prenom }} {% endfor %}

Il est également possible de récupérer la liste de toutes les données saisies pour un champ particulier du bloc avec le filtre |getlist :

{{ form_var_enfant_scolarise|getlist:"prenom" }}

Nombre d'occurrences

Il est possible de connaître le nombre d'éléments contenus dans un bloc de champs avec |count

{{ form_var_MON-BLOC|count }}

Faire un total

Il existe un filtre qui permet d'additionner les valeurs d'un champ du bloc : |sum. Pour additionner toutes les valeurs du champs dont l'identiant est « montant », on écrira ;

form_var_MON-BLOC|getlist:"montant"|sum

Afficher les valeurs

Afin d'afficher les différentes valeurs du bloc au sein d'une colonne dans les tableaux de traitement ou encore dans la variable {{ form_details }}, il faut définir un « Gabarit du résumé » dans les « Paramètres » du bloc.

Ainsi, sur notre exemple ci-dessus, les noms complets des enfants seront affichés si le gabarit de résumé du bloc est configuré avec {{ block_var_prenom }} {{ block_var_nom }} et apparaîtront ainsi dans la colonne : Zoé Durand, Marius Martin. Cette valeur sera accessible avec form_var_enfant_scolarise.

La classe css pk-blocks-zebra permet d'alterner les couleurs de fond d'une occurrence à l'autre.

Afficher (ou pas) le titre du bloc de champs dans un formulaire

Une option « Affichage du libellé » sur les blocs de champs contenu dans les formulaires permet d’afficher le libellé normalement ou sous forme de sous-titre, ou encore de ne pas l’afficher du tout.

Afficher le numéro d'une ligne (occurrence)

Il est possible d'afficher le numéro de l'occurrence d'un bloc mais uniquement dans les champs de type titre, sous-titre et commentaire. Il faut pour cela utiliser la variable block_counter.index.

Par exemple écrire « Enfant {{ block_counter.index}} » dans un champ titre permettra d'afficher dans un formulaire avec deux enfants renseignés :

Enfant 1
[...]
Enfant 2
[...]

Utiliser une condition dans un bloc de champ

Il est possible de masquer/afficher un champ du bloc en fonction d'une réponse à un autre champ du bloc. Il faut utiliser le préfixe block_var_.

block_var_IDENTIFIANT permettra de désigner un champ du bloc sur lequel on va vouloir faire porter une condition. Ce même préfixe, qui n'est utilisable que dans le contexte du bloc, est à privilégier dans la définition du gabarit du résumé du bloc de champ.

Remplir un bloc de champ

Il est possible de remplir facilement un bloc de champ (typiquement dans une donnée de traitement ou une fiche) grâce au contenu d'un bloc de champ identique (provenant typiquement d'un formulaire), il suffira d'indiquer pour cela au niveau du pré-remplissage le nom de variable du bloc concerné.

{{ form_var_IDENTIFIANT-DU-BLOC-DANS-LE-FORMULAIRE }}

Mais il est également possible d'assigner à un bloc de champs une valeur construite adhoc grâce à l'utilisation de la balise {% block_value ... %} pour lui assigner une ou plusieurs lignes.

Remplir le bloc avec une seule ligne

{% block_value responsable=form_var_quelquechose relation=form_var_autre_chose %}
Cette expression va pré-remplir les deux champs du bloc ayant pour identifiant « responsable » et « relation » avec respectivement les valeurs de form_var_quelquechose et form_var_autre_chose.

Cette façon de procéder effacera tout contenu préexistant du bloc. Si, à la place, on souhaite ajouter une occurrence supplémentaire (une « ligne ») au bloc, il faudra ajouter dans la balise :

append=True

Remplir le bloc avec plusieurs lignes

Pour remplir un bloc de champ avec plusieurs ligne il faut utiliser la formule suivante :
{% block_value init=True as MON-BLOC %}
{% for ITEM in LISTE.ITEM %}
{% block_value MON-CHAMP-DU-BLOC=ITEM append=MON-BLOC as MON-BLOC %}
{% endfor %}
{% block_value output=MON-BLOC %}
Le init et le output servent respectivement à initier le bloc et à renvoyer la valeur finale agrégeant les différentes lignes.
Attention quand on veut pré-remplir un bloc, cette expression doit être saisie sur une seule ligne et sans espaces.

Utiliser des filtres de requêtes

Pour pouvoir utiliser les filtres de requête dans un bloc il faut utiliser une expression de la forme :
IDENTIFIANT-BLOC_IDENTIFIANT-CHAMP
Pour un bloc de champ « enfant » comprenant un champ « nom », on pourra utiliser
{{ form_objects|filter_by:"enfant_nom"|filter_value:"martin" }}

Dernière mise à jour le 17 octobre 2023 14:29 — Éditer