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=15 output=total}. Consultez les sections ci-dessous pour découvrir toutes les options de syntaxe.

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

Outputs disponibles :

• total : nombre d’enregistrements correspondants.
• table : tableau HTML valeur/nombre.
• 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 regroupée dans des groupes de valeurs explicites avec groups, par exemple groups='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 groups='0-100;101-200;201+'.
• json : tableau brut [{label,value}].
• 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).
• remaining : nombre restant pour atteindre un target positif.
• percentage : part des enregistrements correspondant à field et value.
• progress : total filtré en pourcentage de target, plafonné à 100 %.
• distinct : nombre de valeurs de champ distinctes et non vides.
• view_name : nom de la vue ContentBuilder NG.

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=15 output=total}
{CBStats id=15 field=Parcours output=table}
{CBStats id=15 field=Parcours output=json}
{CBStats id=15 field=Parcours output=pie}
{CBStats id=15 field=Parcours output=bar sort=value dir=desc}
{CBStats id=15 field=Distance output=avg}
{CBStats id=15 field=Distance output=histogram groups='0-50;51-100;101+'}
{CBStats id=15 field=Date output=line limit=12}
{CBStats id=15 field=Score output=radar}

Fusionner des vues avec idsum : idsum=15+16 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=view_name n’est pas disponible avec idsum. Exemples : {CBStats idsum=15+16 field="Parcours" output="table" labels="title=Monticyclo / Montigravel"} et {CBStats idsum=15+16+17+18+19 field="Distance" output="bar" labels="title=BRM"}.

output=remaining target=200 soustrait du nombre cible positif le total CBStats normalement filtré et ne renvoie jamais une valeur inférieure à zéro.

Tous les filtres habituels de vue, source, droits et enregistrements sont appliqués en premier. Exemple : {CBStats id=15 output=remaining target=200}.

output=percentage renvoie la part des enregistrements correspondant à field= et value= dans la population limitée par l’éventuel filtre filter[field]/filter[value]. Une sélection vide est refusée et une population nulle renvoie 0 %.

Exemple : {CBStats id=15 field=Civilite value="H" output=percentage}.

output=progress target=200 renvoie le total normalement filtré en pourcentage d’un objectif positif, avec un maximum de 100 %.

Exemple : {CBStats id=15 output=progress target=200}.

output=distinct compte les valeurs distinctes non vides de field= après l’application de tous les filtres CBStats habituels, des restrictions de vue/source et des droits.

Il accepte filter[field], filter[value], le raccourci value= sur le même champ, les jokers * et les alternatives |. Exemples : {CBStats id=15 field=Departement output=distinct} et {CBStats id=15 field=Departement value="78|60" output=distinct}.

Une Card éditoriale regroupe du HTML libre ainsi que des balises CBStats et CBList sans imposer la structure HTML complète d’une Card. Utilisez la syntaxe complète recommandée : <div class="cb-card-editorial" data-card="v1" data-w="33">…</div>.

Un élément direct <h1> à <h6 data-cb-card-title> devient le bandeau coloré de la Card et reste visible dans l’éditeur visuel. Un titre Hx sans cet attribut reste dans le corps. L’ancienne syntaxe data-title reste compatible avec ses suffixes partagés |h1 à |h6 et |remX positif. Sans l’une de ces formes de titre, aucun bandeau n’est affiché. data-card accepte h1 à h6 et v1 à v6 ; sa valeur par défaut est v1. data-w accepte 33, 66 ou 100 ; sa valeur par défaut est 33. Une Card ou une largeur invalide utilise ces valeurs sûres par défaut.

Exemple :
<div class="cb-card-editorial" data-card="v1" data-w="33">
<h4 data-cb-card-title>Informations</h4>
<p>Total : {CBStats id=15 output=total}</p>
<p>Groupes distincts : {CBStats id=15 field=Groupe output=distinct}</p>
{CBList id=15 fields="Nom|Prenom" limit=5}
</div>

Le balisage HTML standard est conservé par TinyMCE et JCE. Le rendu réutilise le CSS partagé existant des Cards et supprime les nœuds texte vides ou constitués d’espaces insécables insérés entre les Cards d’une grille cb-cards.

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=15 field=Parcours output=pie add='100 km=-3'}
{CBStats id=15 field=Parcours output=table titles='1=Groupe 1;2=Groupe 2'}
{CBStats id=15 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}

Utilisez labels='title=Parcours;category=Distance;value=Inscrits;total=Total affiché' pour les textes de présentation et titles='Original=Titre affiché' pour les noms des catégories de données.

Exemple : {CBStats id=15 field=Distance output=bar labels='title=Parcours;category=Distance;value=Inscrits;total=Total affiché' background='#eef6f8'}.

Le total affiché est la somme des résultats après les groupes, les ajouts, le tri et limit. Des groupes qui se chevauchent peuvent compter un même enregistrement plusieurs fois. Utilisez output=total pour obtenir le nombre réel d’enregistrements filtrés.

CBStats ajoute au libellé du total le séparateur adapté à la langue si nécessaire. background= accepte les couleurs sûres documentées, par exemple background=lightblue.

labels='title=Parcours;category=Distance;value=Inscrits;total=Total affiché' centralise les libellés de présentation. category et value concernent Table ; total concerne Table et les graphiques ; title nomme le bloc ou la Card. Les clés omises conservent leur valeur par défaut ; les clés inconnues, dupliquées ou vides sont refusées. titles= reste réservé au renommage des catégories de données. export=manual conserve labels=.

Exemple : {CBStats id=15 field=Distance output=table labels='title=Parcours;category=Distance;value=Inscrits;total=Total affiché'}

titleset="departements-fr-FR.ini" charge des libellés de catégories réutilisables depuis un fichier INI administré. Les fichiers du site placés dans media/contentbuilderng/cbstats/titlesets remplacent les fichiers fournis de même nom placés dans media/com_contentbuilderng/cbstats/titlesets. Les correspondances écrites dans titles= restent prioritaires.

Exemple : {CBStats id=15 field=Departement output=table titleset="departements-fr-FR.ini"}.

Un fichier absent ou invalide ne bloque jamais le rendu : les valeurs originales restent visibles. Lorsque le Debug Joomla est activé, CBStats enregistre un Warning. Gérez les fichiers depuis ContentBuilder NG → À propos → Jeux de titres CBStats.

groups= définit directement des groupes de valeurs. Utilisez des intervalles numériques inclusifs comme 18-24, 18- et 70+, ou des valeurs explicites non contiguës avec un libellé d’affichage, comme 1,2,7,9=Groupe 1. Les valeurs qui ne correspondent à aucun groupe restent des catégories individuelles. Les groupes qui se chevauchent sont comptés indépendamment ; le total affiché est donc la somme de tous les résultats affichés et peut compter un même enregistrement plusieurs fois.

groupset="ages-fr-FR.ini" charge des groupes de valeurs réutilisables depuis un fichier INI administré contenant une section [groups]. Chaque clé est un intervalle ou une liste de valeurs séparées par des virgules ; sa valeur INI est le libellé d’affichage.

Exemples complets :
{CBStats id=15 field=Categorie output=bar groups="1,2,7,9=Groupe 1;3,4,8=Groupe 2"}
{CBStats id=15 field=Age output=histogram groupset="ages-fr-FR.ini"}

Gérez ces fichiers dans ContentBuilder NG → À propos → Jeux de données CBStats, avec le type Groupes. La syntaxe inline groups= est prioritaire sur groupset= ; la syntaxe inline titles= remplace les libellés des groupes.

config="vcmb-config.ini" charge des libellés et des options de présentation et d’affichage réutilisables. Dans [presentation], w accepte 33, 66 ou 100 pour la largeur de la Card, tandis que width règle le graphique. Les options écrites dans la balise surchargent le fichier clé par clé.

Exemple : {CBStats id=15 field=Distance output=bar config="vcmb-config.ini" w=100 width=800 labels="title=Parcours spécial"}

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. La clé title de labels= fournit le titre de la Card ; hide="title" le masque.

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 labels="title=Répartition | h4" card=h1}
{CBStats id=15 field=Groupe output=pie labels="title=Répartition | rem1.25" card=h1}
{CBStats id=15 field=Groupe output=pie labels="title=Répartition" hide="title" 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 labels="title=Groupes" card=v1}
{CBStats id=15 field=Prenom output=bar labels="title=Prénoms" card=v2}
{CBStats id=15 field=Groupe output=table labels="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 labels="title=Groupes" card=v1 w=33}
{CBStats id=15 field=Prenom output=bar labels="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 labels="title=Groupes" card=v1}
{CBStats id=15 field=Prenom output=bar labels="title=Prénoms" card=v2}
{CBStats id=15 field=Groupe output=table labels="title=Détail" card=v3}
{CBStats id=15 field=Ville output=pie labels="title=Villes" card=v4}
{CBStats id=15 field=Age output=histogram groups="18-29;30-39;40-49;50+" labels="title=Âges" card=v5}
{CBStats id=15 output=total labels="title=Total" card=v1}
</div>
{CBList id=15 fields="Nom|Prenom|Email" labels="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 title, total, values et graph, combinés avec | dans n’importe quel ordre. title masque le titre défini par labels="title=...", y compris le titre d’une Card. 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 du résultat produit un message plutôt qu’un bloc vide. L’ancienne syntaxe total=hide est refusée ; utilisez hide="total".

hide="title" : contenu sans titre de bloc ni de Card. hide="total|values" : graphique complet uniquement. hide="graph|total" : liste textuelle uniquement. hide="graph|values" : Total uniquement.

{CBStats id=15 field=Groupe output=bar labels="title=Répartition" hide="title|values" card=v1}
{CBStats id=15 field=Age output=histogram groups="18-29;30-39;40-49;50-59;60+" hide="total|values"}
{CBStats id=15 field=Age output=radar groups="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' labels='title=👥 Total des inscrits'}

Outputs : pie, bar, table, total. add=, titles=, labels=, 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=15 field=Parcours output=pie labels='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 view_name. Les noms d’outputs de liste et de graphique retournent les données normalisées sans HTML. groups, 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 : target, add, titles, titleset, groups, groupset, sort, dir, limit. Sortie : output, labels, background, hide, card, w, width, height, export. Diagnostic : debug. L’ancienne option total=hide est refusée ; utilisez hide="total".

Ordre normal : ACL → filtres → regroupement des valeurs sources → groups si demandé → add → normalisation à zéro → titles → 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 labels="title=Répartition" hide="values" card=h1 width=100% height=320 export=manual}