ac_datagrid v3.14.0

Architecture v3.12.0 — noyau commun avec ac_datagrid_pro

Depuis la v3.12.0, ac_datagrid partage son noyau JavaScript (rendu, tri, pagination, édition, export, sous-grilles…) avec ac_datagrid_pro, la version JS pure destinée aux projets sans backend PHP (Laravel, Symfony, API REST quelconque). Les deux classes sont compilées depuis les mêmes sources partagées via un script de build unique ; seul le transport réseau diffère (dispatcher PHP intégré ici, contrat REST configurable côté Pro).

Concrètement pour vous : toute nouvelle fonctionnalité du noyau (formatage conditionnel, presets, agrégats…) est disponible dans les deux classes simultanément, et documentée ici comme avant — cette page ne couvre que ac_datagrid. Pour l'usage JS pur sans backend PHP, voir la documentation dédiée ac_datagrid_pro (contrat REST, mode données en mémoire, presets par défaut différents).

Introduction

ac_datagrid est un composant PHP/JavaScript qui génère des grilles de données interactives à partir d'une simple configuration PHP. Un seul fichier à déposer dans votre projet — aucune dépendance npm, composer, jQuery ou CDN.

Il couvre l'intégralité du cycle CRUD : lecture paginée, ajout, édition (inline, modale ou cellule par cellule), suppression, export XLSX et import CSV. Deux modes de rendu sont disponibles : clientside (toutes les données chargées en une fois, tri/recherche/filtres instantanés côté navigateur, recommandé jusqu'à ~5 000 lignes) et serverside (pagination et filtrage côté serveur, testé à 200 000 lignes en grille principale et 2 000 000 en sous-grilles, gère facilement 2 000 000 de lignes).

La classe gère elle-même la connexion PDO, la sécurité CSRF, la session PHP et la génération complète du HTML/CSS/JS — la page appelante n'a qu'à instancier et afficher. Elle est conçue pour être déployée par simple copie FTP, sans aucune étape de build.

Fonctionnalités principales

• 2 modes de rendu — clientside (réactif, jusqu'à ~5 000 lignes) et serverside (volumes importants)
• 3 modes d'édition — inline, modale, cellule par cellule (double-clic)
• Sous-grilles — intégrées dans le tableau parent ou séparées sur la page
• Filtres — automatiques par colonne (filtre_auto) et/ou externes avec sql_options
• Export XLSX / CSV / Import CSV — sans dépendance serveur
• i18n — ~65 clés traduisibles, 4 langues démontrées
• Accessibilité WCAG 2.1 AA — ARIA, navigation clavier, focus visible
• 4 thèmes CSS — sobre, techno, nature, pastel — via variables CSS
• Formatage conditionnel — numérique et date
• Événements JS custom — architecture découplée, notifications déléguées
• Registre global — window.acGrilleInstances pour piloter les grilles depuis JS externe
• Cookies — mémorisation des préférences utilisateur (tri multi-colonnes, colonnes masquées, ordre, filtres)

Clientside ou serverside ?

Règles importantes d'intégration

Ces règles ont été établies lors d'une intégration en production sur un produit en prod (janvier–mars 2026).

• ob_start() avant tout include en contexte AJAX — toute page gérant à la fois l'affichage HTML et les requêtes AJAX de la classe doit placer ob_start() en toute première instruction (avant les require_once) quand $_POST['acgr_id'] est présent. Sinon, des warnings PHP ou des whitespaces générés par les includes polluent la réponse JSON.

  if (isset($_POST['acgr_id'])) {
      ini_set('display_errors', 0);
      ob_start();
  }
  // require_once ... viennent ensuite

• champ_sql des filtres = alias du SELECT — la classe enveloppe le SQL dans SELECT * FROM (...) AS _acgr WHERE .... Dans cette sous-requête, les alias de table (g.id_genre, b.date_inscription) n'existent plus. Utiliser uniquement les alias de colonnes du SELECT (id_genre, date_inscription).
• Colonnes de filtre cachées — si un filtre externe porte sur un champ qui n'est pas affiché (ex: id_genre pour filtrer mais afficher nom_genre), ajouter ce champ dans le SELECT et le déclarer 'visible' => false dans la config colonnes.
• read_only ne bloque pas l'AJAX lire — read_only: true bloque uniquement sauvegarder et supprimer (protégés par CSRF). Le rechargement AJAX des sous-grilles fonctionne normalement en read_only.
• Sous-grilles séparées — pour des grilles enfant affichées séparément sur la page (pas dans le tableau parent), utiliser subgrid: true + subgrid_param: 'champ_liaison' et piloter depuis JS via window.acGrilleInstances[id].setFiltreParent(champ, valeur) + .charger().

Historique des versions

Getting Started — grille fonctionnelle en 5 minutes

1. Copier ac_datagrid.php dans votre projet

Un seul fichier à déposer. Aucune dépendance npm, composer ou CDN.

2. Créer une table MySQL exemple

CREATE TABLE produits (
    id      INT AUTO_INCREMENT PRIMARY KEY,
    nom     VARCHAR(100) NOT NULL,
    prix    DECIMAL(10,2),
    actif   TINYINT(1) DEFAULT 1
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

3. Page PHP minimale

<?php
require_once 'ac_datagrid.php';

$cfg = [
    // Connexion
    'db_host'     => 'localhost',
    'db_port'     => '3306',
    'db_name'     => 'ma_base',
    'db_user'     => 'user',
    'db_password' => 'secret',

    // Identification
    'id'    => 'grille_produits',
    'table' => 'produits',
    'sql'   => 'SELECT id, nom, prix, actif FROM produits',

    // Colonnes
    'colonnes' => [
        ['champ'=>'id',    'titre'=>'ID',    'editable'=>false],
        ['champ'=>'nom',   'titre'=>'Nom',   'type'=>'text',     'requis'=>true],
        ['champ'=>'prix',  'titre'=>'Prix',  'type'=>'number',   'monetaire'=>true],
        ['champ'=>'actif', 'titre'=>'Actif', 'type'=>'checkbox'],
    ],
];

$g = new ac_datagrid($cfg);

// Intercepter les requêtes AJAX
if ($g->estRequeteAjax()) {
    $g->traiterAjax();
    exit;
}
?>
<!DOCTYPE html>
<html><head><meta charset="UTF-8"></head><body>
<?= $g->genereCSS() ?>
<?= $g->genereHTML() ?>
<?= $g->genereJS() ?>
</body></html>

Gestion AJAX — pattern recommandé

Toutes les opérations (lire, sauvegarder, supprimer, exporter…) passent par des requêtes POST vers la même page PHP. Le pattern recommandé :

if ($g->estRequeteAjax()) {
    $g->traiterAjax();
    exit;
}

// Variante multi-grilles sur la même page :
if (isset($_POST['acgr_id'])) {
    if (strpos($_POST['acgr_id'], 'praticiens_') === 0) {
        $g = new ac_datagrid(array_merge($dbCfg, getConfigPraticiens()));
        $g->traiterAjax(); exit;
    }
    if (strpos($_POST['acgr_id'], 'patients_') === 0) {
        $g = new ac_datagrid(array_merge($dbCfg, getConfigPatients()));
        $g->traiterAjax(); exit;
    }
}

Actions AJAX disponibles

Format de réponse unifié

// Succès
{ "ok": true, "message": "Enregistrement ajouté.", "code": "INSERT_OK", "id": 42 }

// Échec
{ "ok": false, "message": "Le champ «Nom» est obligatoire.", "code": "CHAMP_REQUIS" }

Options générales

Presets disponibles

Un preset pré-remplit un jeu cohérent d'options ; toute option explicitement fournie dans la config l'emporte toujours sur le preset, même si le preset la définit aussi. 'complet' est un tableau vide dans le code source — c'est ce qui garantit qu'il ne peut jamais diverger des défauts de la classe : ne pas préciser preset du tout revient exactement au même.

Configuration des colonnes

Chaque élément du tableau colonnes est un tableau associatif :

Identifier la clé primaire

Si une colonne porte pk => true, c'est elle. Sinon, la clé primaire est la première colonne avec editable => false et visible !== false (heuristique inchangée). Si aucune colonne ne correspond, le fallback est 'id'.

['champ' => 'id', 'titre' => 'ID', 'editable' => false]  // <- clé primaire (heuristique)
['champ' => 'uuid', 'titre' => 'ID', 'pk' => true, 'editable' => false]  // <- clé primaire (explicite, prioritaire)

Types de colonnes

text

Champ texte simple. Rendu : <input type="text"> en édition.

number

Valeur numérique. Rendu : <input type="number">. Participe aux totaux automatiques. Utiliser total => false pour exclure un champ non sommable (ex : une année). Compatible monetaire et format_conditionnel.

date

Date au format ISO YYYY-MM-DD. Rendu : <input type="date">. Compatible format_conditionnel.

datetime v3.9.2

Date et heure, colonne DATETIME en base. Rendu : <input type="datetime-local"> (sans les secondes — un input datetime-local ne les gère pas nativement). Compatible format_conditionnel (même logique de comparaison que date).

checkbox

Booléen stocké en TINYINT(1). Rendu : case à cocher. Le filtre automatique propose Oui/Non/Tous.

select

Liste déroulante. Nécessite options (tableau PHP) ou sql_options (requête SQL) :

// Options statiques
['champ' => 'statut', 'type' => 'select', 'options' => [
    ['id' => 1, 'libelle' => 'Actif'],
    ['id' => 2, 'libelle' => 'Inactif'],
]]

// Options dynamiques depuis la BDD
['champ' => 'id_ville', 'type' => 'select',
 'sql_options'         => 'SELECT id_ville AS id, libelle FROM villes ORDER BY libelle',
 'sql_options_display' => 'SELECT id_ville AS id, libelle FROM villes ORDER BY libelle']

// Select en cascade (dépend d'un autre select)
['champ' => 'id_sous_cat', 'type' => 'select',
 'parent'       => 'id_categorie',     // champ parent
 'parent_label' => 'la catégorie',
 'sql_options'  => 'SELECT id, libelle FROM sous_categories WHERE id_cat = :parent']

textarea

Zone de texte multi-lignes. Rendu tronqué à 100 caractères en affichage. Occupe toute la largeur de la modal (class acgr-modal-full).

email, url, tel, color v3.11.0

Quatre types dédiés, chacun avec un <input type="..."> HTML natif (clavier mobile adapté, sélecteur natif pour color) et, pour email/url/tel, un pattern de validation appliqué à la sauvegarde (inline, modal et mode cellule).

['champ' => 'email',     'titre' => 'Email',     'type' => 'email'],
['champ' => 'site_web',  'titre' => 'Site web',  'type' => 'url'],
['champ' => 'telephone', 'titre' => 'Téléphone', 'type' => 'tel'],
['champ' => 'couleur',   'titre' => 'Couleur',   'type' => 'color'],

// Pattern personnalisé — remplace le pattern par défaut du type
['champ' => 'telephone_fr', 'titre' => 'Tél. FR', 'type' => 'tel',
 'pattern' => '^0[1-9][0-9]{8}$']

Modes d'édition

inline (défaut)

L'édition se fait directement dans la ligne du tableau. Les cellules se transforment en champs de formulaire. Boutons Valider / Annuler en colonne Actions.

modal

Une fenêtre modale s'ouvre avec tous les champs. Supporte les widgets Classothèque. Fermeture par Echap ou clic sur le fond.

'edit_mode'   => 'modal',
'modal_titre' => 'Mon enregistrement',

cell

Double-clic sur une cellule pour l'éditer individuellement. L'ajout de nouvelles lignes utilise ajout_mode (inline ou modal). Navigation clavier : Enter / F2 pour éditer, Échap pour annuler, ↑↓←→ pour se déplacer.

'edit_mode'  => 'cell',
'ajout_mode' => 'modal',  // modal recommandé en mode cell

Filtres externes

Des selects de filtrage peuvent être placés au-dessus de la grille. Ils déclenchent un rechargement AJAX.

'defaut_actif' => true,   // v3.13.0 — nécessaire pour que 'defaut' ci-dessous s'applique réellement
'filtres' => [
    [
        'id'          => 'filtre_ville',
        'label'       => 'Ville',
        'champ_sql'   => 'id_ville',   // champ utilisé dans le WHERE
        'sql_options' => 'SELECT id_ville AS id, libelle FROM villes ORDER BY libelle',
        'defaut'      => null,          // valeur sélectionnée par défaut
    ],
],

Serverside

En mode serverside, seule la page courante est chargée depuis le serveur. La pagination, le tri, la recherche et les filtres sont exécutés en SQL.

'serverside'      => true,
'longueur_defaut' => 25,    // lignes par page
'ordre_defaut'    => [0, 'asc'],

Quand l'utiliser ?

• > 5 000 lignes : recommandé
• > 50 000 lignes : indispensable
• Testé à 200 000 lignes avec temps de réponse < 1s

Totaux généraux serverside

En mode serverside avec totaux => true, deux lignes de totaux sont affichées : Σ (page courante) et ∑ (total général sur toutes les données filtrées, calculé côté serveur).

Sous-grilles

Une grille peut contenir des sous-grilles qui se chargent au clic sur ▶. Chaque ligne de la grille maître peut avoir sa propre sous-grille.

// 1. Créer la sous-grille avec subgrid=true et subgrid_param
$grPat = new ac_datagrid(array_merge($dbCfg, [
    'id'            => 'patients',
    'table'         => 'patients',
    'sql'           => 'SELECT id, nom, id_praticien FROM patients',
    'subgrid'       => true,
    'subgrid_param' => 'id_praticien',  // colonne de liaison
    'colonnes'      => [
        ['champ'=>'id',           'editable'=>false],
        ['champ'=>'nom',          'type'=>'text'],
        ['champ'=>'id_praticien', 'visible'=>false, 'editable'=>false],
    ],
]));

// 2. Attacher à la grille maître
$grPrat = new ac_datagrid(array_merge($dbCfg, [
    'id'            => 'praticiens',
    'subgrid'       => true,
    'subgrid_param' => 'id_praticien',
    'sous_grilles'  => [$grPat],
    // ...
]));

Performance

Les sous-grilles sont chargées à la demande (lazy loading). Testé à 2 000 000 de lignes réparties dans les sous-grilles de 200 000 lignes parentes.

Export XLSX / CSV

L'export génère un fichier directement dans le navigateur, sans dépendance serveur. Il respecte les filtres actifs au moment de l'export.

// Comportement historique — inchangé, bouton unique, clic direct
'export'          => true,
'export_filename' => 'mon_export',  // nom sans extension → fichier mon_export_YYYY-MM-DD.xlsx

// v3.11.0 — CSV en plus, bouton devient un menu déroulant
'export'          => true,
'export_formats'  => ['xlsx', 'csv'],
'export_filename' => 'mon_export',

XLSX

Le fichier généré comporte une ligne d'en-têtes en gras et les données. Les valeurs numériques sont typées comme nombres. Compatible Excel 2010+ et LibreOffice Calc.

CSV v3.11.0

Séparateur : csv_separateur (même clé que pour l'import CSV, cohérence garantie). Échappement RFC4180 (guillemets si virgule/guillemet/retour-ligne dans une valeur). BOM UTF-8 en tête du fichier — indispensable pour qu'Excel FR affiche correctement les caractères accentués.

'csv_separateur' => ';',  // ou ','

Import CSV

L'import se fait en 3 étapes via une modale : sélection du fichier → mapping des colonnes → prévisualisation + import.

'import_csv'    => true,
'csv_separateur' => ';',  // ou ','

Étapes

1. Fichier — glisser-déposer ou sélection. Lecture via FileReader API (côté client).
2. Mapping — association automatique par nom de colonne (insensible à la casse), ajustable manuellement.
3. Prévisualisation — aperçu des 5 premières lignes. Import ligne par ligne avec barre de progression et rapport d'erreurs.

Formatage conditionnel

Colorise le texte d'une cellule selon la valeur. Fonctionne sur les colonnes number et date.

Colonne numérique

['champ' => 'tarif', 'type' => 'number',
 'format_conditionnel' => [
    'seuil'     => 60,          // valeur de référence (float)
    'superieur' => '#dc2626',  // rouge si tarif > 60
    'egal'      => '#f59e0b',  // orange si tarif = 60
    'inferieur' => '#16a34a',  // vert si tarif < 60
]]

Colonne date

['champ' => 'date_installation', 'type' => 'date',
 'format_conditionnel' => [
    'seuil'     => '2020-01-01',  // date de référence ISO
    'superieur' => '#16a34a',    // vert si date > 2020
    'egal'      => '#f59e0b',    // orange si date = 2020
    'inferieur' => '#dc2626',    // rouge si date < 2020
]]

Plusieurs paliers v3.12.0

Pour plus de deux couleurs (ex. vert / orange / rouge), format_conditionnel accepte aussi un tableau de règles, évaluées dans l'ordre — la première règle qui correspond gagne. Les deux formes sont détectées automatiquement (is_array avec clés numériques vs seuil/superieur/egal/inferieur) ; l'ancienne forme reste strictement inchangée, aucune migration nécessaire.

['champ' => 'note', 'type' => 'number',
 'format_conditionnel' => [
    ['operateur' => '>=', 'valeur' => 8.5, 'couleur' => '#16a34a', 'gras' => true],
    ['operateur' => '>=', 'valeur' => 7.6, 'couleur' => '#f59e0b'],
    ['operateur' => '<',  'valeur' => 7.6, 'couleur' => '#dc2626'],
]]

Vignettes images

Une colonne peut afficher une URL comme vignette cliquable (lightbox au clic).

['champ'       => 'photo',
 'titre'       => 'Photo',
 'type'        => 'text',
 'url_image'   => true,
 'image_taille'=> '40px',      // taille du carré affiché
 'image_round' => 'round',     // round | rounded | square | none
]

Si l'URL est invalide ou l'image inaccessible, un placeholder ? est affiché. Le clic ouvre un lightbox plein écran avec fermeture par Échap ou clic.

Widgets Classothèque

Chaque widget déclare sa propre static MODES_SUPPORTES (ex : ['modal', 'inline']). Un widget qui ne la déclare pas garde le comportement historique — modal uniquement, input texte simple en inline ou cell — repli qui protège tous les widgets existants sans modification v3.9.0.

// ac_carte — saisie d'adresse avec carte interactive
['champ'          => 'adresse',
 'type'           => 'text',
 'widget'         => 'ac_carte',
 'widget_ancre'   => 'div',          // ancre de type div
 'widget_options' => [
    'mode'            => 'saisie',
    'hauteur'         => '280px',
    'lien_itineraire' => false,
]]

// ac_telephone_multipays — saisie de numéro avec indicatif
['champ'          => 'telephone',
 'type'           => 'text',
 'widget'         => 'ac_telephone_multipays',
 'widget_ancre'   => 'input',          // ancre de type input
 'widget_options' => ['pays_defaut' => 'FR']]

// ac_big_select — sélection à fort volume, recherche AJAX (v3.9.0)
['champ'            => 'id_beneficiaire',
 'type'             => 'select',
 'widget'           => 'ac_big_select',
 'champ_libelle'    => 'lib_beneficiaire',   // fourni par une jointure du SQL principal
 'sql_options_ajax' => 'SELECT id_beneficiaire AS id, CONCAT(nom, " ", prenom) AS libelle
                         FROM dat_beneficiaires
                         WHERE id_asso = :id_asso AND actif = 1
                           AND CONCAT(nom, " ", prenom) LIKE :terme
                         ORDER BY nom, prenom',
 'sql_options'      => 'SELECT id_beneficiaire AS id, CONCAT(nom, " ", prenom) AS libelle
                         FROM dat_beneficiaires WHERE id_asso = :id_asso']

widget_ancre

• input — le widget s'attache à un <input hidden> (ac_telephone_multipays)
• div — le widget s'attache à un <div> conteneur (ac_carte, ac_note_etoiles…)

Les widgets doivent exposer les méthodes getValeur() et setValeur(id, libelle) de la Classothèque (getLibelle() également, pour les widgets à liste comme ac_big_select).

Scrollbar horizontale miroir v3.6.8

Lorsque la grille déborde horizontalement, une scrollbar miroir apparaît au-dessus du tableau, synchronisée bidirectionnellement avec la scrollbar native du bas. Elle permet de faire défiler la grille sans avoir à atteindre le bas de la page.

Comportement automatique

• Affichée uniquement si table.scrollWidth > tableWrap.clientWidth — invisible si tout le tableau est visible.
• Recalculée après chaque render() (changement de page, filtre, tri…) via requestAnimationFrame.
• Recalculée lors du redimensionnement de la fenêtre (window.resize).
• Aucune option de configuration requise — la fonctionnalité est toujours active.

Cas des onglets cachés

Quand une grille est dans un onglet avec display:none au chargement, son tableWrap.clientWidth est 0 à ce moment-là et le calcul reste à zéro. Il faut déclencher un recalcul une fois l'onglet visible. Voir la section Hooks publics JS ci-dessous.

i18n — Internationalisation

Toutes les chaînes d'interface sont externalisées et remplaçables via l'option labels.

Usage

$g = new ac_datagrid([
    // ...
    'labels' => [
        'enregistrer'    => 'Save',
        'annuler'        => 'Cancel',
        'aucun_resultat' => 'No results',
        // Les clés non fournies gardent la valeur FR par défaut
    ],
]);

Labels disponibles (sélection)

La liste complète des ~65 clés est disponible dans $LABELS_DEFAUT en haut du fichier ac_datagrid.php.

Méthode statique

// Utiliser un label en PHP (pour les messages serveur)
$msg = ac_datagrid::lblStatic($labels, 'insert_ok');
$msg = ac_datagrid::lblStatic($labels, 'champ_requis', 'Nom');  // avec sprintf

Événements JavaScript

La grille émet des événements DOM sur son élément acgr-wrap-{id}. Ils remontent (bubbles).

wrap.addEventListener('acgr:row-click', function(e) {
    // e.detail.id        : id de la ligne cliquée
    // e.detail.grille_id : id de la grille émettrice
    // e.detail.selected  : true = sélectionnée, false = désélectionnée
    // e.detail.row       : objet complet de la ligne (v3.12.0)
    if (!e.detail.selected) return;
    chargerSousGrilles(e.detail.id);
});

// Cas typique en prod — une grille pilote 4 sous-grilles
wrap.addEventListener('acgr:row-click', function(e) {
    if (!e.detail.selected) return;
    var id = e.detail.id;
    chargerParcoursPro(id);
    chargerAteliers(id);
    chargerFamille(id);
    chargerAdministratif(id);
});

wrap.addEventListener('acgr:apres-chargement', function(e) {
    // e.detail.total     : nombre total de lignes (filtrées)
    // e.detail.page      : page courante
    // e.detail.grille_id : id de la grille émettrice
    console.log(e.detail.total + ' lignes, page ' + e.detail.page);
});

// e.detail.donnees   : objet avec les valeurs insérées
// e.detail.grille_id : id de la grille

// e.detail.donnees   : objet avec les valeurs mises à jour
// e.detail.grille_id : id de la grille

// e.detail.id        : id supprimé
// e.detail.grille_id : id de la grille

// e.detail.ids       : tous les ids tentés
// e.detail.nb_ok     : nombre de suppressions réussies
// e.detail.erreurs   : [{id, message}] pour les échecs
// e.detail.grille_id : id de la grille

// e.detail.message : message lisible
// e.detail.code    : code machine (CHAMP_REQUIS, RUNTIME_ERROR…)
wrap.addEventListener('acgr:erreur', e => afficherErreur(e.detail.message));

wrap.addEventListener('acgr:action-custom', function(e) {
    // e.detail.id        : clé primaire de la ligne
    // e.detail.ligne      : objet complet de la ligne (tous les champs)
    // e.detail.table      : nom de la table (cfg.table)
    // e.detail.grille_id  : id de la grille émettrice
    ouvrirDetail(e.detail.id, e.detail.ligne);
});

// Dispatché sur document, pas sur le wrap de la grille
// e.detail.action   : 'CREATE' | 'UPDATE' | 'DELETE'
// e.detail.table    : nom de la table (clé 'table' dans la config JS)
// e.detail.id       : id de la ligne concernée
// e.detail.grille_id : id de la grille émettrice
// e.detail.donnees  : champs de la ligne concernée — v3.13.0

document.addEventListener('acgr:log', function(e) {
    fetch('/assets/php/ac_datagrid_log_ajax.php', {
        method: 'POST',
        body: new URLSearchParams({
            action    : e.detail.action,
            table     : e.detail.table,
            id        : e.detail.id,
            grille_id : e.detail.grille_id,
            csrf_token: insert.csrfToken()
        })
    });
});

wrap.addEventListener('acgr:before_delete', function(e) {
    // e.detail.id        : clé primaire de la ligne
    // e.detail.ligne     : objet complet de la ligne (ou null si introuvable localement)
    // e.detail.table     : nom de la table (cfg.table)
    // e.detail.grille_id : id de la grille émettrice
    if (e.detail.ligne && e.detail.ligne.statut === 'facture') {
        e.preventDefault();
        AcNotifModale.notif('error', 'Suppression refusée', 'Ligne déjà facturée.', 4);
    }
});

Hooks serveur PHP v3.11.0

Trois clés de config acceptent un callable PHP exécuté côté serveur, dans ajaxSauvegarder()/ajaxSupprimer(). Toutes trois sont opt-in : absentes de la config (défaut null), aucun changement de comportement.

on_log

Appelé après chaque écriture BDD confirmée (CREATE, UPDATE, DELETE) — équivalent serveur de l'événement JS acgr:log, utile pour un journal d'audit qui doit survivre même si le JavaScript du navigateur est désactivé ou la page fermée avant que l'événement JS ne soit traité côté client.

'on_log' => function(string $action, int $id, string $table, array $donnees = []) {
    // $action  : 'CREATE' | 'UPDATE' | 'DELETE'
    // $donnees : champs de la ligne concernée — 4e paramètre, v3.13.0
    journaliser($action, $id, $table, $donnees);
},

on_avant_sauvegarde

Appelé juste avant l'INSERT/UPDATE, reçoit tous les champs — y compris les colonnes invisibles/FK (visible => false) que la page hôte injecte aujourd'hui souvent manuellement dans $_POST avant traiterAjax(). Le hook sécurise ce cas : la valeur devient injectable côté serveur, non falsifiable côté client.

'on_avant_sauvegarde' => function(array $donnees, bool $estNouveau, ?int $rowId): array {
    // Forçage serveur d'un champ invisible — non falsifiable côté client
    $donnees['id_asso'] = id_asso_courant();

    // Blocage conditionnel — remonte au client via le même mécanisme d'erreur
    // que le token CSRF (rep.message, event acgr:erreur)
    if (!$estNouveau && $donnees['montant'] > 10000) {
        throw new RuntimeException('Montant trop élevé pour une modification.');
    }

    return $donnees;  // toujours retourner le tableau, modifié ou non
},

on_avant_suppression v3.13.0

Symétrique de on_avant_sauvegarde, côté suppression. Appelé juste avant le DELETE, reçoit l'id de la ligne et son contenu complet (chargé depuis la vue SQL déclarée). Retourner une chaîne non vide bloque la suppression et remonte le message au client. Ne rien retourner (ou null) autorise la suppression, comportement identique à l'absence du hook.

'on_avant_suppression' => function(int $rowId, array $ligne): void|string {
    if ($ligne['statut'] === 'facture') {
        return 'Impossible de supprimer une ligne déjà facturée.';
    }
    // Rien ou null : suppression autorisée
},

Hooks publics JS v3.6.8

Chaque grille expose trois mécanismes pour déclencher un recalcul de sa scrollbar miroir depuis l'extérieur. Cas d'usage typique : une grille dans un onglet caché (display:none) au chargement. Une fois l'onglet rendu visible, le code appelant notifie la grille pour qu'elle mesure ses vraies dimensions.

1. Méthode directe sur le container

Recalcule la scrollbar miroir de cette seule grille.

document.getElementById('acgr-wrap-mon_id').acgrRefreshScroll();

2. Événement DOM ciblé

Même résultat que la méthode directe, mais sous forme d'événement.

const wrap = document.getElementById('acgr-wrap-mon_id');
wrap.dispatchEvent(new CustomEvent('acgr:refresh-scroll'));

3. Événement global — toutes les grilles

Dispatché sur document — toutes les grilles de la page recalculent leur scrollbar. Pratique pour les systèmes d'onglets : un seul appel suffit, quelle que soit la grille concernée. Les grilles encore cachées recalculent aussi mais obtiennent clientWidth = 0 et restent masquées sans effet visible.

// Dans le gestionnaire d'activation d'onglet :
document.getElementById('tab-' + btn.dataset.tab).classList.add('active');

// Attendre que le layout CSS soit appliqué (rAF garantit que display:block est effectif)
requestAnimationFrame(function() {
    document.dispatchEvent(new CustomEvent('acgr:refresh-scroll-all'));
});

Cookies et personnalisation

La grille mémorise automatiquement les préférences de l'utilisateur :

• Ordre des colonnes (drag via menu ⋮)
• Colonnes masquées
• Colonnes fixées (gauche / droite)
• Tri multi-colonnes
• Filtres colonnes actifs
• Recherche globale
• Nombre de lignes par page

Le cookie est clé par URL + id de grille. Durée : 1 an.

'cookies' => false,  // désactiver complètement

Le bouton ↺ Réinitialiser apparaît dans la toolbar dès qu'une préférence est active. Il supprime le cookie et restaure la configuration initiale.

Mode debug

Activer pour diagnostiquer les réponses serveur non-JSON (erreurs PHP fatales, warnings, pages 500…).

'debug' => true

Lorsqu'une réponse AJAX n'est pas du JSON valide, un panneau s'affiche sous la grille avec :

• Le Content-Type reçu
• Les 2000 premiers caractères du contenu brut
• Un log console.error complet

Accessibilité WCAG

ac_datagrid implémente les recommandations WCAG 2.1 niveau AA :

Sémantique ARIA

• role="grid" sur la table avec aria-label
• role="row" sur tous les <tr>
• role="gridcell" sur tous les <td>
• role="columnheader" sur tous les <th>
• aria-sort="ascending|descending|none" sur les colonnes triables
• aria-live="polite" sur la zone d'info pagination
• aria-label sur tous les boutons icônes (traduit via i18n)
• aria-expanded sur les boutons de sous-grille

Navigation clavier (mode cell uniquement)

Focus visible

Tous les éléments interactifs ont un :focus-visible avec outline: 2px solid var(--acgr-accent).

Méthodes publiques

Exemple rebuild dynamique

// PHP — endpoint ?rebuild=1
if (isset($_GET['rebuild'])) {
    $g = new ac_datagrid(array_merge($dbCfg, $maCfg, [
        'edit_mode'  => $_GET['edit_mode']  ?? 'cell',
        'ajout_mode' => $_GET['ajout_mode'] ?? 'modal',
    ]));
    header('Content-Type: application/json');
    echo json_encode([
        'css'  => $g->genereCSS('sobre'),
        'html' => $g->genereHTML(),
        'js'   => $g->genereJS(),
    ]);
    exit;
}

ac_datagrid v3.14.0  ·  artisan-code.fr  ·  18 août 2026