Les blocs de champs

⚙️ Accès dans le BO :
Studio > Formulaires > Blocs de champs

Les blocs de champs permettent d'insérer un ensemble de champs dans un ou plusieurs formulaires.
Toute modification d'un bloc de champs est automatiquement répercutée sur les formulaires qui l'utilisent.

🔑 Fonctionnalités clés

Les blocs de champs sont principalement utilisés dans deux situations clés :

1. Comme modèle réutilisable : lorsque vous avez un ensemble de champs que vous souhaitez réutiliser dans plusieurs formulaires.
   Par exemple, un bloc « Identité » contenant des champs Prénom, Nom, Adresse qui sera utilisé dans plusieurs formulaires. Vous modifiez le bloc de champs, la modification est appliquée dans tous les formulaires qui l'utilisent.
2. Pour créer plusieurs occurrences : quand on souhaite permettre à l'usager d'ajouter plusieurs fois un même ensemble de champs.
   Par exemple, si l'usager doit envoyer plusieurs fichiers sans savoir combien à l'avance, ou ajouter plusieurs enfants. Un bloc de champs « Enfant » avec les champs Prénom, Nom et Date de naissance s'affiche une fois dans le formulaire, et l'usager peut le dupliquer autant de fois que nécessaire, en fonction du nombre d'enfants.

Créer un bloc de champs

La gestion des blocs de champs est accessible en barre latérale droite, section “Navigation”, depuis la page backoffice de gestion des formulaires. 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.

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.

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.

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'identifiant 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

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.

Utiliser une condition de sortie de bloc de champ

De la même façon qu'il est possible d'utiliser une condition de sortie de page, il est possible d'utiliser une condition de sortie de bloc. La condition s'écrit dans les paramètres du bloc et s'applique à chaque occurrence du bloc dans une demande.

Pour un bloc de champ qui contient un champ "Date de naissance" avec l'identifiant est date_naissance, si on souhaite limiter la saisie à un âge maximal de 10 ans, la condition qui doit être satisfaite s'écrit   block_var_date_naissance|age_in_years < 10.

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 %}

append=True

{% 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 %}

{{ form_objects|filter_by:"enfant_nom"|filter_value:"martin" }}