CBList : rôle, syntaxe et principales options

CBList affiche une vue liste ContentBuilder NG directement dans un article Joomla. La liste conserve les droits d’accès et la configuration de la vue.

Exemple simple :
{CBList id=15}
Cet exemple affiche la vue 15 telle qu’elle est configurée dans ContentBuilder NG, sans filtrer ses colonnes ni remplacer son titre, son tri, sa pagination, ses actions, sa mise en page ou son thème.

Les options numériques id, height, pagination et limit doivent être écrites sans guillemets.

Principales options :

• id=15 : vue ContentBuilder NG à afficher. Cette option est obligatoire.
• fields="Nom|Prenom|Email" : sélectionne les colonnes affichées et leur ordre.
• title="Liste des inscrits" : remplace le titre visible de la vue. Omettez title pour conserver le titre configuré. Utilisez title=hide, ou son équivalent title="", pour masquer le titre CB.
• sort="Nom|Prenom" dir="asc" : trie initialement tous les champs indiqués par ordre croissant. Une direction unique s’applique à tous les champs du tri.
• pagination=25 : affiche 25 enregistrements par page.
• limit=10 : conserve au maximum les 10 premiers enregistrements accessibles après les ACL, la recherche, les filtres et le tri. La pagination et les exports portent sur ce sous-ensemble limité.
• actions="detail|edit|export" : sélectionne les contrôles proposés à l’utilisateur, dans la limite des droits de la vue.
• layout=cards : affiche les enregistrements sous forme de cartes plutôt que dans le tableau standard. C’est l’alias lisible de listcard.
• height=700 : fixe la hauteur minimale initiale du cadre à 700 pixels. Le cadre peut s’agrandir automatiquement si nécessaire.
• loading=lazy : valeur par défaut ; charge la liste lorsqu’elle approche de la zone visible. Utilisez loading=eager pour la charger immédiatement.

Exemple réaliste :
{CBList id=15 fields="Nom|Prenom|Email" title="Liste des inscrits" sort="Nom|Prenom" dir="asc" pagination=25 limit=10 actions="detail|edit|export" layout=cards height=700 loading=lazy}

Thème : CBList utilise le thème configuré dans la vue ContentBuilder NG. Thoth est le thème par défaut et de secours. La balise CBList ne possède pas d’option theme=.

CBList et CBStats peuvent être associés dans le même article, par exemple un graphique de synthèse suivi de la liste détaillée des enregistrements.

fields= sélectionne les colonnes à afficher et leur ordre parmi les champs disponibles dans la vue ContentBuilder NG. Utilisez uniquement les noms source exacts des éléments, en respectant la casse, ou leurs identifiants de référence exacts. Les libellés affichés et les variantes d’accent ou de casse sont refusés. Séparez les valeurs avec |. Un élément existant indiqué dans fields reste valide s’il est dépublié ou désactivé pour la liste ; ContentBuilder omet simplement cette colonne sans signaler d’erreur de syntaxe.

Trois colonnes affichées :
{CBList id=15 fields="Nom|Prenom|Email"}

Colonnes affichées avec tri et pagination :
{CBList id=15 fields="Nom|Prenom|Email" sort="Nom|Prenom" dir="asc" pagination=25}

Une seule valeur dir="asc" ou dir="desc" s’applique à tous les champs de sort. Pour mélanger les directions, indiquez-en une par champ, par exemple dir="asc|desc". Ajoutez title="Liste des inscrits" pour remplacer le titre visible ou title=hide pour le masquer complètement. title="" est équivalent. layout, height et loading règlent la présentation comme expliqué ci-dessus.

pagination=20 découpe la liste en pages de 20 lignes. pagination=0 conserve le nombre de lignes prévu par la vue, mais masque le sélecteur et les liens de pagination.

limit=100 plafonne le résultat à 100 lignes après ACL, recherche, filtres et tri. Avec pagination=20, cela donne au maximum 5 pages. L’export utilise le même résultat plafonné. Les nombres s’écrivent sans guillemets.

Exemples :
{CBList id=15 pagination=20 limit=100}
{CBList id=15 actions=none pagination=0 limit=10}

layout= accepte default, cards, listone, listtwo, listthree, listcard, listcompact ou listtiles. cards est un alias de listcard. Cette option contrôle les lignes internes ; card=h1…v5 enveloppe toute la balise.

height=700 fixe la hauteur initiale minimale de l’iframe, entre 240 et 5 000 pixels. loading=lazy charge à l’approche de l’écran ; loading=eager charge immédiatement.

Exemples :
{CBList id=15 layout=cards height=700 loading=lazy}
{CBList id=15 layout=listcompact loading=eager}

{CBList id=15 fields="Nom" output=value} renvoie uniquement la dernière valeur du champ Nom, au format texte Unicode et sans iframe. Tous les ACL, restrictions, recherches et filtres de CB sont appliqués avant le tri.

Par défaut, ce mode utilise sort=ID dir=desc offset=0. Utilisez offset=1 pour l’avant-dernier résultat, ou choisissez explicitement un autre champ de tri et dir=asc ou dir=desc. fields doit contenir exactement un champ. offset est un entier compris entre 0 et 4 999, sans guillemets.

Les options pagination, actions, title, layout, height et loading sont refusées avec output=value. En l’absence de résultat, CBList ne renvoie rien. Dans une liste normale, pagination=0 masque le sélecteur et les contrôles de pagination sans modifier le nombre de lignes.

actions= sélectionne les contrôles disponibles dans les écrans intégrés de liste, de détail et d’édition. Sans cette option, tous les contrôles déjà autorisés par les droits de la vue restent disponibles. Cette option n’accorde jamais un droit refusé par la vue.

Actions disponibles :

• search : affiche la barre de recherche et les filtres.
• state : affiche le filtre et le contrôle du statut de workflow.
• publish : affiche le filtre et le contrôle de publication ou dépublication.
• language : affiche le filtre de langue.
• new : permet de créer un nouvel enregistrement.
• edit : permet d’ouvrir l’écran d’édition d’un enregistrement existant.
• delete : permet de supprimer des enregistrements.
• export : affiche le bouton d’export.
• rating : affiche et permet d’utiliser la notation.
• detail : permet d’ouvrir l’écran de détail d’un enregistrement.
• print : affiche le bouton d’impression sur l’écran de détail.

Séparez les actions avec |.

{CBList id=15 actions="detail|edit|export"}
{CBList id=15 fields="Nom|Prenom|Email" actions="search|detail|edit|export"}

actions=none masque et interdit toutes les actions CBList : recherche et filtres, création, détail, édition, suppression, export, notation et impression. L’absence de actions ou actions="" conserve les réglages de la vue.

Les contrôles de pagination sont indépendants. Pour afficher les données sans aucune commande en haut ou en bas, utilisez :
{CBList id=15 actions=none pagination=0}

none ne peut pas être associé à une autre action.

card=h1 à card=h6 ou card=v1 à card=v6 ajoute une Card colorée. Pour toutes les variantes, le titre reste horizontal et placé au-dessus du contenu. Le bandeau est créé uniquement si title= contient un texte.

Les titres des Cards utilisent h4 par défaut. Ajoutez |h1 à |h6 après le titre pour sélectionner un niveau de titre, ou |remX / |remX.X pour définir une taille visuelle positive tout en conservant le niveau sémantique h4. Les espaces autour du dernier | sont facultatifs et la casse du suffixe est ignorée. Un suffixe non reconnu reste dans le titre complet, affiché avec le rendu h4 par défaut.

{CBList id=15 title="Inscriptions | h4" card=h1}
{CBList id=15 title="Inscriptions | rem1.25" card=h1}

Les couleurs peuvent être surchargées dans le fichier user.css de Joomla : .cb-card-h1 { --cb-card-header-bg: #005a9c; --cb-card-header-color: #fff; }

Placez toutes les Cards V à juxtaposer dans un seul conteneur <div class="cb-cards">, sans <br> entre les balises. Sur PC, le conteneur affiche trois colonnes ; sur petit écran, une seule. Une Card H placée dans ce conteneur occupe toute la ligne.

Exemple :
<div class="cb-cards">
{CBList id=15 title="Liste 1" card=v1}
{CBList id=15 title="Liste 2" card=v2}
{CBList id=15 title="Liste 3" card=v3}
</div>

Dans un conteneur cb-cards, ajoutez w=33 pour une colonne, w=66 pour deux colonnes ou w=100 pour toute la ligne. Écrivez la valeur sans guillemets et uniquement avec card=. Sans w=, une Card V vaut 33 et une Card H vaut 100. Sur petit écran, toutes passent à 100 %.

Exemple :
<div class="cb-cards">
{CBList id=15 title="Liste courte" card=v1 w=33}
{CBList id=15 title="Liste large" card=v2 w=66}
</div>

Un seul conteneur cb-cards peut contenir six Cards V : les trois premières occupent la première ligne et les trois suivantes passent automatiquement sur la deuxième. N’ajoutez ni <br> ni second conteneur entre elles. Une Card H utilisée seule n’a pas besoin de conteneur.

Exemple à coller en mode HTML de l’éditeur Joomla, sans marqueurs Markdown ``` :

<h2>Tableau de bord</h2>
<div class="cb-cards">
{CBStats id=15 field=Groupe output=pie title="Groupes" card=v1}
{CBStats id=15 field=Prenom output=bar title="Prénoms" card=v2}
{CBStats id=15 field=Groupe output=table title="Détail" card=v3}
{CBStats id=15 field=Ville output=pie title="Villes" card=v4}
{CBStats id=15 field=Age output=histogram ranges="18-29;30-39;40-49;50+" title="Âges" card=v5}
{CBStats id=15 output=total title="Total" card=v1}
</div>
{CBList id=15 fields="Nom|Prenom|Email" title="Derniers enregistrements" sort=ID dir=desc limit=10 card=h1}

Pour tout le site : ajoutez .cb-card-h1 { --cb-card-accent: #005a9c; --cb-card-header-color: #fff; } dans le fichier user.css du template Joomla. Toutes les Cards H1 sont alors modifiées. Remplacez h1 par la variante H/V souhaitée.

Pour un seul article : entourez les balises avec <div class="mes-cards">…</div>, puis ajoutez <style>.mes-cards .cb-card-h1 { --cb-card-accent: #005a9c; }</style> dans l’article si son éditeur et la politique du site autorisent les éléments style. Le conteneur évite de modifier les autres pages.

--cb-card-accent contrôle la couleur du bandeau. Les personnalisations avancées peuvent utiliser --cb-card-header-bg, --cb-card-header-color, --cb-card-bg, --cb-card-color et --cb-card-border-color.

Source : id. Colonnes et tri : fields, sort, dir. Volume : pagination, limit. Commandes : actions. Présentation : title, layout, height, loading, card. Valeur unique : output, offset.

Une erreur indique l’option, sa valeur et la règle attendue. Les ACL restent toujours prioritaires.

Exemple complet :
{CBList id=15 fields="Nom|Prenom|Email" sort="Nom|Prenom" dir="asc|desc" pagination=20 limit=100 actions="search|detail|export" title="Inscriptions" layout=cards height=700 loading=lazy card=h1}