CBStats : finalité, syntaxe et sorties

CBStats affiche des statistiques dynamiques provenant de vues ContentBuilder NG directement dans les articles Joomla, tout en conservant les droits d’accès et la configuration des vues.

Exemple simple : {CBStats id=IdVue output=total}. Consultez les sections ci-dessous pour découvrir toutes les options de syntaxe.

Syntaxe : {CBStats id=IdVue ...}. La sortie par défaut est total.

Outputs disponibles :

• total : nombre d'enregistrements correspondants.
• form_name : titre ou nom de la vue.
• table : tableau HTML valeur/nombre.
• sum, min, max : agrégats numériques ; les dates ISO acceptent un min/max chronologique.
• avg : moyenne arithmétique des valeurs numériques (les valeurs vides ou non numériques sont ignorées).
• json : tableau brut [{label,value}].
• pie : graphique circulaire responsive avec couleurs dynamiques, pourcentages localisés, infobulle, légende détaillée et total.
• bar : histogramme horizontal responsive avec valeurs, pourcentages, infobulle, légende, total et tri.
• histogram : distribution numérique regroupée dans des ranges explicites, par exemple ranges='18-29;30-39;40-49;50+'.
• line : courbe de tendance ordonnée, souvent avec des dates ou catégories séquentielles, par exemple output=line limit=12.
• radar : comparaison multi-axes ; utilisez 3 à 8 catégories, par exemple field=Distance output=radar ranges='0-100;101-200;201+'.

Table, JSON, Pie, Bar, Histogram, Line et Radar utilisent le même moteur PHP normalisé ; avg utilise les mêmes valeurs numériques normalisées.

Exemples simples :
{CBStats id=25 output=total}
{CBStats id=25 field=Parcours output=table}
{CBStats id=25 field=Parcours output=json}
{CBStats id=25 field=Parcours output=pie}
{CBStats id=25 field=Parcours output=bar sort=value dir=desc}
{CBStats id=25 field=Distance output=avg}
{CBStats id=25 field=Distance output=histogram ranges='0-50;51-100;101+'}
{CBStats id=25 field=Date output=line limit=12}
{CBStats id=25 field=Score output=radar}

Fusionner des vues avec idsum : idsum=25+27 remplace id= et accepte de deux à cinq identifiants de vues uniques séparés par +. Chaque vue applique les droits et les filtres avant l’addition des valeurs portant exactement le même libellé. add=, la normalisation à zéro, titles=, le tri et l’output sont ensuite appliqués une seule fois au résultat fusionné. output=form_name n’est pas disponible avec idsum. Exemples : {CBStats idsum=25+27 field="Parcours" output="table" title="Monticyclo / Montigravel"} et {CBStats idsum=31+32+33+34+35 field="Distance" output="bar" title="BRM"}.

Filtrer sur un autre champ : field=Element-1 est le champ regroupé et affiché dans le graphique. filter[field]=Element-2 est le champ utilisé pour filtrer les enregistrements. filter[value]="Dét* | 3 | 4" conserve les valeurs commençant par Dét, ou la valeur exacte 3, ou la valeur exacte 4. Le caractère | sépare les alternatives, les espaces autour sont ignorés et, sans *, la correspondance est exacte.

{CBStats id=15 field=Element-1 filter[field]=Element-2 filter[value]="Dét* | 3 | 4" output=bar}

Raccourci sur le même champ : lorsque le filtre porte sur le champ affiché, {CBStats id=15 field=Element-2 value="Dét* | 3 | 4" output=bar} équivaut à {CBStats id=15 field=Element-2 filter[field]=Element-2 filter[value]="Dét* | 3 | 4" output=bar}. Lorsque les champs diffèrent, utilisez filter[field] et filter[value]. Ne confondez pas value= avec values=, réservé à source=manual.

Exemples :
{CBStats id=25 field=Parcours output=pie add='100 km=-3'}
{CBStats id=25 field=Parcours output=table titles='1=Groupe 1;2=Groupe 2'}
{CBStats id=25 field=Parcours output=bar add='1=-2;2=3' titles='1=Groupe 1;2=Groupe 2' sort=value dir=desc}
{CBStats id=15 field=Element-1 filter[field]=Element-2 filter[value]="Dét* | 3 | 4" output=bar}
{CBStats id=15 field=Element-2 value="Dét* | 3 | 4" output=bar}

title='👥 Total des inscrits' personnalise le libellé global du total pour Table, Pie et Bar.

titles='Original=Titre affiché' personnalise les libellés individuels des catégories.

CBStats ajoute le séparateur adapté à la langue active lorsqu’il est absent et ne double pas un caractère « : » déjà présent.

background= accepte transparent, les couleurs hexadécimales, rgb(), rgba() et les couleurs nommées sûres documentées.

{CBStats id=25 field=Parcours output=pie title='👥 Total des inscrits'}

headers='Dpt=Département;Total=Qté' personnalise uniquement les deux en-têtes de colonnes de output=table. Les en-têtes non mappés restent inchangés ; les clés inconnues et les libellés vides sont ignorés. Les légendes Pie et Bar restent inchangées. title=, titles= et headers= sont indépendants. export=manual conserve le mappage.

limit=10 conserve les 10 premières valeurs statistiques après sort= et dir=. Sans limit, toutes les valeurs sont rendues. Les options numériques doivent être des entiers strictement positifs écrits sans guillemets.

Après la limitation, le total affiché et les pourcentages des graphiques sont recalculés uniquement sur les valeurs conservées. Aucune catégorie Autres n’est ajoutée.

{CBStats id=15 field=Ville output=table sort=value dir=desc limit=10}
{CBStats idsum=15+16 field=Club output=bar sort=value dir=desc limit=15}

Utilisez card=h1 à card=h6 ou card=v1 à card=v6. Pour toutes les variantes, le titre reste horizontal et placé au-dessus du contenu. Le bandeau s’affiche uniquement avec un title= explicite et non vide.

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.

{CBStats id=15 field=Groupe output=pie title="Répartition | h4" card=h1}
{CBStats id=15 field=Groupe output=pie title="Répartition | rem1.25" card=h1}

Surchargez les couleurs dans le fichier Joomla user.css avec les propriétés personnalisées --cb-card-*.

Placez les trois balises dans un unique <div class="cb-cards">, sans <br> et sans fermer le conteneur entre deux balises. Sur PC, les V occupent trois colonnes ; sur petit écran, une seule. Une Card H occupe toute la ligne.

Exemple :
<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}
</div>

Dans cb-cards, w=33 occupe une colonne, w=66 deux colonnes et w=100 toute la ligne. La valeur s’écrit sans guillemets et exige card=. Sans w=, V vaut 33 et H vaut 100. Sur petit écran, toutes les Cards occupent 100 %. Si une ligne n’a plus assez de place, la Card passe à la suivante.

w= règle la Card ; width= règle le graphique à l’intérieur.

Exemple :
<div class="cb-cards">
{CBStats id=15 field=Groupe output=pie title="Groupes" card=v1 w=33}
{CBStats id=15 field=Prenom output=bar title="Prénoms" card=v2 w=66 width=100%}
</div>

Placez jusqu’à six Cards V dans un seul conteneur cb-cards. Les trois premières forment la première ligne et les suivantes la deuxième. N’insérez aucun <br> et ne fermez pas le conteneur entre deux lignes. Une Card H seule peut être écrite directement après le conteneur.

Exemple HTML Joomla, sans marqueurs Markdown ``` :

<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. 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.

Personnalisations avancées : --cb-card-header-bg, --cb-card-header-color, --cb-card-bg, --cb-card-color et --cb-card-border-color.

width= règle la largeur du conteneur du graphique et height= sa hauteur. Les valeurs acceptées sont un entier positif, px ou %. Un nombre seul est converti en pixels : width=350 équivaut à width=350px. Les expressions CSS, unités différentes et valeurs supérieures à 100 % ou 5 000px sont refusées.

Sans option : Pie occupe 80 % du conteneur, reste centré et ne dépasse pas 350px. Bar, Histogram, Line et Radar occupent 100 % de la largeur disponible. Aucun graphique ne doit provoquer de défilement horizontal par défaut.

Largeur explicite : width=100% permet à Pie d’utiliser toute la Card et supprime son maximum de 350px. width=300 fixe 300px. Sur un petit conteneur, préférez un pourcentage pour conserver le responsive.

Hauteur explicite : elle désactive la conservation automatique du ratio du graphique. height=280 donne 280px. height=80% ne fonctionne utilement que si le parent possède déjà une hauteur CSS définie ; sinon utilisez des pixels.

Exemples :
{CBStats id=15 field=Groupe output=pie}
{CBStats id=15 field=Groupe output=pie width=100%}
{CBStats id=15 field=Groupe output=bar width=100% height=280}
{CBStats id=15 field=Groupe output=radar width=80% height=320px}

hide= accepte uniquement total, values et graph, combinés avec | dans n’importe quel ordre. total masque uniquement le Total affiché, values masque la liste textuelle des libellés et valeurs sous le graphique sans modifier le graphique lui-même, et graph masque le dessin en conservant cette liste textuelle légère. Sans hide=, tout est affiché. Masquer les trois éléments produit un message plutôt qu’un bloc vide. L’ancienne syntaxe total=hide est refusée ; utilisez hide="total".

hide="total|values" : graphique complet uniquement. hide="graph|total" : liste textuelle uniquement. hide="graph" : liste textuelle et Total. hide="values" : graphique complet et Total. hide="graph|values" : Total uniquement.

{CBStats id=15 field=GroupeVcmb output=bar hide="values"}
{CBStats id=25 field=age output=histogram ranges="18-29;30-39;40-49;50-59;60+" hide="total|values"}
{CBStats id=25 field=age output=radar ranges="18-29;30-39;40-49;50-59;60+" hide="graph|total"}

source=manual utilise exclusivement values=, sans vue, champ ni requête ContentBuilder. Il conserve les résultats même si une vue est réutilisée.

{CBStats source=manual output=pie values='100 km=45;150 km=47;200 km=38;200 km (Formule)=30' title='👥 Total des inscrits'}

Outputs : pie, bar, table, total. add=, titles=, title=, sort=none|title|label|value et dir=asc|desc restent disponibles. Les doublons sont additionnés. Dans un libellé, utilisez \;, \= et \. N’ajoutez ni id= ni field=.

Seul export=manual affiche les résultats finaux et la syntaxe source=manual visible sous les outputs Pie, Bar et Table. Les libellés finaux après titles=, les ajouts et le tri sont directement intégrés dans values= ; titles= n’est pas recopié.

{CBStats id=25 field=Parcours output=pie title='👥 Total des inscrits' export=manual}

Le bouton centré Copier la syntaxe copie exactement la syntaxe affichée au-dessus. Avec une source déjà manuelle, la syntaxe finale normalisée est affichée une seule fois, sans imbrication.

URL/API : tous les outputs de données sont testables avec action=cbstats : json, table, pie, bar, histogram, line, radar, total, sum, min, max, avg et form_name. Les noms d’outputs de liste et de graphique retournent les données normalisées sans HTML. ranges, add, titles, sort, dir et limit utilisent la validation des balises d’article.

API + Droits : vérifiez les ACL, les champs publiés et autorisés pour API/Stats, la permission STATS et l’onglet API de la vue. Aucune requête ne contourne les droits de la vue ou du champ.

DEBUG : les diagnostics sûrs suivent le réglage DEBUG de la vue. DEBUG ne donne aucun droit supplémentaire et ne contourne jamais les ACL.

Source : source, id, idsum, values. Données : field, filter[field], filter[value], value. Calcul : add, titles, ranges, sort, dir, limit. Sortie : output, headers, title, background, hide, card, width, height, export. Diagnostic : debug. L’ancienne option total=hide est refusée ; utilisez hide="total".

Ordre normal : ACL → filtres → regroupement → add → normalisation à zéro → titles → ranges si nécessaire → tri → limit → output et présentation.

Exemple complet :
{CBStats id=15 field=Groupe filter[field]=Statut filter[value]="Publié*" add="Externe=2" titles="Externe=Invités" sort=value dir=desc limit=10 output=bar title="Répartition" hide="values" card=h1 width=100% height=320 export=manual}