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.
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.
![https://doc-publik.entrouvert.com/media/uploads/2021/02/19/blocks-zebra.png](https://doc-publik.entrouvert.com/media/uploads/2021/02/19/blocks-zebra.png)
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
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 aĝe 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 %}
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
{% 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 %}
Utiliser des filtres de requêtes
{{ form_objects|filter_by:"enfant_nom"|filter_value:"martin" }}