# Design des graphes de statistiques

Comment changer l'apparence des graphes du backoffice sans changer de librairie.

## La librairie

**Flot 0.7** (`js/flot/jquery.flot.js`), plugin jQuery qui dessine dans un `<canvas>`.
Version de 2011, plus maintenue, mais volontairement conservée.

Elle est chargée par les pages qui posent `$header_vars['flot'] = 1;` — aujourd'hui
`bo-index.php`, `bo-admin-statistique.php` et `bo-admin-chat-connectes-logs.php`.
`header_js_require.inc.php` n'injecte alors **que** `jquery.flot.js` : aucun des
9 plugins présents dans `js/flot/` n'est chargé.

## Les fichiers à connaître

| Fichier | Rôle |
|---|---|
| `js/js_include/bo_admin_statistique.js` | 17 des 18 fonctions qui tracent les graphes |
| `js/js_include/bo_admin_chat_connectes_logs.js` | la 18e (`statsGraphNbLivesView`) |
| `img/backoffice_default/css/style.css` | le CSS **réellement servi** au backoffice |
| `js/flot/API.txt` | la doc de référence de Flot 0.7, à lire en premier |

Les deux fichiers JS ne sont **jamais chargés ensemble** :
`bo-admin-chat-connectes-logs.php` ne charge que le second. Toute modification
transverse doit donc être appliquée aux deux.

Attention : `img/backoffice_default/css/style.min.css` existe mais **n'est pas chargé**.
Le backoffice reçoit la version non minifiée, via `$CONF_TEMPLATE['tpl_dirname']`
lu en base (`fo_header.vue.php:177`). Le mot `backoffice_default` n'apparaît nulle
part dans le code : inutile de le chercher.

## Les quatre leviers

**1. L'objet `options` de `$.plot()`** — couvre la grande majorité des besoins :
couleurs (`colors`), épaisseurs et remplissages (`series.lines`, `series.points`),
grille et cadre (`grid`), axes et graduations (`xaxis`, `yaxis`), légende (`legend`).
Tout est documenté dans `API.txt`.

**2. Le CSS** — Flot génère ses graduations en `<div>` HTML, pas en canvas. Elles
portent la classe `.tickLabel` et sont donc entièrement stylables (`API.txt:680`).
Idem pour la légende et pour le tooltip, qui est notre propre élément.

**3. Les dégradés** — `{ colors: [{ opacity: 0.2 }, { opacity: 0.01 }] }` sur
`series.lines.fillColor` ou `grid.backgroundColor`. Verticaux uniquement (`API.txt:819`).

**4. Les hooks** — `processOptions`, `draw`, `drawSeries`… pour ce que les options
ne couvrent pas (`API.txt:1024`). Dernier recours.

## Recette : restyler un graphe

Les 18 graphes partagent déjà le même bloc `options` : prendre n'importe quelle
fonction comme modèle. Les réglages qui font le plus de différence :

```js
var options = {
    series: {
        lines:  { show: true, lineWidth: 2, fill: true,
                  fillColor: { colors: [{ opacity: 0.20 }, { opacity: 0.01 }] } },
        points: { show: false, radius: 3, lineWidth: 2 },
        shadowSize: 0          // coupe l'ombre portée façon 2011
    },
    colors: ['#2a78d6'],       // la courbe
    grid: {
        hoverable: true,
        borderWidth: 0,        // pas de cadre autour du tracé
        color: '#e1e0d9',      // grille récessive, distincte de la courbe
        backgroundColor: '#ffffff',
        labelMargin: 10,
        mouseActiveRadius: 20  // cible de survol plus large que le point
    },
    legend: { show: false },   // une seule série : le titre la nomme
    xaxis: { ticks: xAxisLabel, tickLength: 0, color: '#e1e0d9' },
    yaxis: { min: 0, tickDecimals: 0, color: '#e1e0d9',
             tickColor: '#e1e0d9' }   // sans dilution, voir plus bas
};
```

Les points qui comptent vraiment :

- `lineWidth: 2` au lieu de `0.5`. Le demi-pixel est ce qui donne l'aspect délavé.
- `grid.color` **différent** de `colors`. Quand les deux valent la même couleur, la
  grille pèse autant que les données.
- `yaxis: { min: 0, tickDecimals: 0 }` sur tout compteur, sinon l'axe affiche des
  valeurs négatives et des décimales (« 0.5 vue ») quand la série est plate.
- `tickLength: 0` sur `xaxis` supprime les verticales et garde les horizontales.
- `points: { show: false }` conserve quand même le halo de survol : `radius` et
  `lineWidth` sont lus indépendamment de `show` (`jquery.flot.js:2475`).

## Deux comportements absents d'API.txt

Ils s'expliquent seulement en lisant la source, et ils surprennent.

**La grille est diluée à 22 % d'alpha.** Flot trace les lignes de niveau avec
`$.color.parse(axis.options.color).scale('a', 0.22)` (`jquery.flot.js:1561`).
Régler `yaxis.color` sur un gris franc donne donc des lignes quasi invisibles.
La sortie est `tickColor`, lu en priorité et non dilué :

```js
yaxis: { color: '#e1e0d9', tickColor: '#e1e0d9' }   // 1px pleinement opaque
```

**La largeur des lignes de grille n'est pas paramétrable.** `ctx.lineWidth = 1`
est câblé juste après (`jquery.flot.js:1562`). Pour épaissir une ligne de niveau,
il faut passer par `grid.markings`, qui accepte un `lineWidth`.

Pour le tooltip, utiliser la classe CSS `.k4-chart-tooltip` déjà en place plutôt
que de reposer un style inline.

## Ce que la lib ne permet pas

- **Netteté sur écran HiDPI.** Flot 0.7 fait `c.width = canvasWidth` sans tenir
  compte de `devicePixelRatio` (`jquery.flot.js:689`). Sur un écran retina ou en
  mise à l'échelle Windows, le canvas est rastérisé en 1x puis étiré. Aucune option
  ne corrige ça.
- **Redimensionnement.** `jquery.flot.resize.js` est sur le disque mais n'est pas
  chargé : un graphe ne se réajuste pas quand la fenêtre change de taille.

## Pièges

- **Encodage.** `bo_admin_statistique.js` contient des commentaires accentués en
  ISO-8859-1. Ne pas le réécrire avec un outil qui le relit en UTF-8 : éditer
  seulement la zone concernée, ou passer par un découpage `head`/`tail`.
- **Fins de ligne.** `img/backoffice_default/css/style.css` est intégralement en
  CRLF. Ajouter des lignes en LF produit un fichier mixte.
- **18 fonctions dupliquées.** Les fonctions ne diffèrent que par l'URL et le
  libellé de série, et le bloc `options` est recopié dans chacune. Toute retouche
  transverse se paie 18 fois — un script vaut mieux que 18 éditions manuelles.
- **Cache.** CSS et JS sont servis avec `?v=<licence_asset_version>`. Si cette
  valeur ne bouge pas, le navigateur ressort son cache : recharger de force.
- **Un id, deux pages.** `#stats_graph_nbviews_medias` existe dans
  `bo_hp_menu.vue.php` (dashboard) et `bo_admin_statistique.vue.php` (stats
  détaillées). Les deux sont tracés par la même fonction et changent ensemble.

## État actuel

Les **18** graphes sont modernisés et partagent les mêmes réglages. Il ne reste
plus trace de l'ancien style (`lineWidth: 0.5`, grille `#024066` de la même
couleur que la courbe, tooltip rose de la démo Flot).

Le fonctionnel n'a pas été touché : URLs, paramètres, champs de série,
`markings`, `$.ajax` et les handlers `plothover` sont restés identiques. Seuls le
corps de `showTooltip` et l'objet `options` ont changé.

Deux limites connues subsistent, décrites plus haut : le rendu HiDPI et l'absence
de redimensionnement.