ac_datagrid_pro.js

1. Quick start

Une seule balise <script>, quelques lignes de configuration — et votre grille est en ligne. Pas de npm, pas de bundler, pas de framework.

<script src="ac_datagrid_pro.js"></script>

Choisissez votre mode selon votre situation :

Mode data — zéro backend

Le moyen le plus rapide de démarrer. Vous n'avez besoin d'aucun serveur, d'aucune API, d'aucune base de données. Passez votre tableau et la grille fait le reste — tri, filtres, pagination, tout est géré côté client.

<div id="ma-grille"></div>
<script src="ac_datagrid_pro.js"></script>
<script>
new AcDatagridPro({
    target: '#ma-grille',
    data: [
        { id: 1, nom: 'Dupont',  prenom: 'Marie',  ville: 'Bordeaux' },
        { id: 2, nom: 'Martin',  prenom: 'Thomas', ville: 'Lyon'     },
        { id: 3, nom: 'Petit',   prenom: 'Claire', ville: 'Paris'    },
    ],
    colonnes: [
        { champ: 'id',     titre: 'ID',     editable: false },
        { champ: 'nom',    titre: 'Nom'    },
        { champ: 'prenom', titre: 'Prénom' },
        { champ: 'ville',  titre: 'Ville'  },
    ]
});
</script>

Sans preset déclaré, le preset mini s'applique : affichage simple, lecture seule, pagination. Ajoutez preset: 'recherche' pour obtenir tri, recherche et filtres automatiques sur vos données.

Mode url — avec API

Pointez vers votre endpoint REST. La grille envoie des requêtes HTTP (GET par défaut pour la lecture, voir contrat d'API) et attend une réponse normalisée.

new AcDatagridPro({
    target:     '#ma-grille',
    url:        '/api/clients',   // votre endpoint REST
    preset:     'edition',        // CRUD activé
    serverside: true,             // recommandé dès que le volume dépasse quelques milliers de lignes
    colonnes: [
        { champ: 'id',    titre: 'ID',    editable: false },
        { champ: 'nom',   titre: 'Nom',   requis: true    },
        { champ: 'email', titre: 'Email', type: 'email'   },
    ]
});

Le contrat d'API attendu est décrit dans la section API référence.

2. Cas concrets

Vous avez des données JSON (un export, une réponse d'API tierce, un fichier statique) et vous voulez les afficher avec tri, recherche et filtres. Aucun serveur nécessaire.

const produits = [
    { id: 1, ref: 'REF-001', nom: 'Câble HDMI 2m',    categorie: 'Câbles',  prix: 12.90, stock: 48 },
    { id: 2, ref: 'REF-002', nom: 'Souris sans fil',   categorie: 'Périph.', prix: 29.90, stock: 12 },
    { id: 3, ref: 'REF-003', nom: 'Clavier mécanique', categorie: 'Périph.', prix: 89.00, stock: 5  },
    { id: 4, ref: 'REF-004', nom: 'Hub USB-C 7 ports', categorie: 'Câbles',  prix: 45.00, stock: 0  },
];

new AcDatagridPro({
    target:  '#grille-produits',
    data:    produits,
    preset:  'recherche',   // tri + recherche globale + filtres automatiques
    colonnes: [
        { champ: 'ref',       titre: 'Réf.',      editable: false, largeur: '100px' },
        { champ: 'nom',       titre: 'Produit'                                     },
        { champ: 'categorie', titre: 'Catégorie', type: 'select',
          options: [{ id: 'Câbles', libelle: 'Câbles' }, { id: 'Périph.', libelle: 'Périphériques' }] },
        { champ: 'prix',      titre: 'Prix',      type: 'number', monetaire: true   },
        { champ: 'stock',     titre: 'Stock',     type: 'number',
          format_conditionnel: [{ operateur: '=', valeur: 0, couleur: '#dc2626', gras: true }] },
    ]
});

Le preset recherche gère tri, recherche et filtres entièrement en mémoire, sans aucune requête serveur. La colonne stock passe en rouge gras quand elle vaut 0.

Votre backend expose un endpoint REST. La grille gère l'interface complète : ajout, modification, suppression avec confirmation — sans une ligne de JS supplémentaire.

new AcDatagridPro({
    target:     '#grille-contacts',
    url:        '/api/contacts',
    preset:     'edition',
    serverside: true,
    colonnes: [
        { champ: 'id',        titre: 'ID',       editable: false },
        { champ: 'nom',       titre: 'Nom',      requis: true  },
        { champ: 'prenom',    titre: 'Prénom',   requis: true  },
        { champ: 'email',     titre: 'Email',    type: 'email'   },
        { champ: 'telephone', titre: 'Tél.',     type: 'tel'     },
        { champ: 'id_statut', titre: 'Statut',   type: 'select',
          options: [
              { id: 1, libelle: 'Actif'   },
              { id: 2, libelle: 'Inactif' },
              { id: 3, libelle: 'Prospect'},
          ]
        },
    ]
});

Le preset edition inclut : tri, recherche, filtres, CRUD en modale (création / modification / suppression), et persistance de l'état en localStorage.

Pour les cas métier avancés : le preset complet active toutes les fonctionnalités.

new AcDatagridPro({
    target:          '#grille-commandes',
    url:             '/api/commandes',
    preset:          'complet',
    serverside:      true,
    export:          true,
    export_formats:  ['csv', 'xlsx'],
    export_filename: 'commandes',
    theme:           'techno',
    colonnes: [
        { champ: 'id',          titre: 'N°',    editable: false, largeur: '70px'  },
        { champ: 'client',      titre: 'Client', requis: true                 },
        { champ: 'date',        titre: 'Date',   type: 'date'                   },
        { champ: 'montant_ht',  titre: 'HT',     type: 'number', monetaire: true,
          agregat: 'somme',
          format_conditionnel: [{ operateur: '>=', valeur: 10000, couleur: '#16a34a', gras: true }] },
        { champ: 'montant_ttc', titre: 'TTC',    type: 'number', monetaire: true, agregat: 'somme' },
        { champ: 'statut',      titre: 'Statut', type: 'select',
          options: [
              { id: 'brouillon', libelle: 'Brouillon' },
              { id: 'envoyee',   libelle: 'Envoyée'   },
              { id: 'payee',     libelle: 'Payée'     },
              { id: 'annulee',   libelle: 'Annulée'   },
          ]
        },
    ]
});

Le preset complet inclut tout : CRUD modale + cellule (double-clic), ajout inline, épingles ★, duplication de ligne, export CSV/XLSX, import CSV, totaux et formatage conditionnel. Les totaux ne sont plus déclarés dans une liste globale totals : chaque colonne porte son propre agregat (somme par défaut ; voir Colonnes).

3. Options avancées

Presets

Les presets sont des configurations pré-packagées. Choisissez le plus proche de votre besoin et surchargez uniquement ce qui diffère.

Chaîne de fusion : Défauts → Preset → Config du développeur. La config explicite l'emporte toujours.

Options générales

Colonnes

Chaque colonne est un objet dans le tableau colonnes :

Formatage conditionnel

{ champ: 'salaire', titre: 'Salaire', type: 'number',
  format_conditionnel: [
    { operateur: '<', valeur: 30000, couleur: '#dc2626'               },  // rouge
    { operateur: '>', valeur: 50000, couleur: '#16a34a', gras: true  },  // vert gras
  ]
}

Opérateurs : = == < > <= >= — Propriétés de règle : couleur · gras (bool, optionnel). Les règles sont évaluées dans l'ordre, la première qui correspond gagne.

Forme alternative pour un seuil unique (deux/trois couleurs autour d'une valeur de référence) : { seuil, superieur, egal, inferieur } — voir la documentation ac_datagrid pour le détail, le mécanisme est strictement identique des deux côtés.

Filtres externes v3.13.0

Des selects (ou champs date) de filtrage peuvent être placés au-dessus de la grille, en plus du filtre_auto par colonne. Contrairement à ac_datagrid (PHP), il n'y a pas de sql_options — chaque filtre fournit directement son tableau d'options en JS, le transport REST n'ayant pas de notion de requête SQL à exécuter côté classe.

new AcDatagridPro('#ma-grille', {
    url: '/api/commandes',
    filtres: [
        {
            id:        'filtre_statut',
            label:     'Statut',
            champ_sql: 'statut',            // clé transmise au backend
            options:   [
                { id: 0, libelle: 'En cours' },
                { id: 1, libelle: 'Terminée' },
            ],
            defaut: 0,                       // v3.13.0 — nécessite defaut_actif ci-dessous
        },
    ],
    defaut_actif: true,   // v3.13.0 — sans ça, 'defaut' reste cosmétique
    colonnes: [ /* ... */ ],
});

Thèmes

4 thèmes CSS embarqués dans la classe — aucun fichier externe, activables via theme :

CRUD — Modes d'édition

edit_mode: 'inline' (défaut)

La ligne entière se transforme en formulaire. Boutons ✔ Valider et ✕ Annuler à droite.

edit_mode: 'modal'

Un formulaire s'ouvre dans une modale. Tous les champs sur une seule vue. Idéal pour les formulaires complexes.

edit_mode: 'cell'

Double-clic sur une cellule pour l'éditer directement. Entrée = valider, Échap = annuler. Idéal pour les corrections rapides.

Granularité CRUD

// Désactiver uniquement la suppression
ajout: true, delete: false

// Lecture seule (raccourci)
read_only: true

Widgets externes v1.1.0

Une colonne peut remplacer son champ de saisie par défaut par un composant JavaScript riche que vous avez écrit vous-même — un sélecteur de carte, un champ téléphone international, un éditeur enrichi... Le composant n'a besoin d'aucune dépendance particulière ; il respecte simplement un contrat minimal, comme une prise électrique.

Le contrat côté widget

Votre classe JavaScript doit exposer :

• un constructeur new MonWidget(ancreId, options)
• une méthode setValeur(valeur, libelleInitial) — appelée pour préremplir la valeur existante à l'ouverture (libelleInitial vient de col.champ_libelle si déclaré, sinon null)
• une méthode getValeur() — appelée pour récupérer la valeur saisie à la sauvegarde
• optionnellement, une propriété statique MODES_SUPPORTES (ex. ['modal','inline']) — sans elle, le widget n'est utilisé qu'en edit_mode:'modal'

Déclaration dans la colonne

{
  champ: 'adresse',
  titre: 'Adresse',
  widget: 'MonWidgetCarte',       // nom de la classe, exposée sur window
  widget_ancre: 'div',            // 'div' (widget visuel) ou 'input' (widget qui gère une valeur simple)
  widget_options: { zoom: 14 }    // transmis tel quel au constructeur, complété automatiquement
}

Lignes épinglées ★

Activez la colonne étoile avec epingle: true (activé par défaut). L'utilisateur épingle des lignes en cliquant sur l'étoile — elles remontent en tête et restent visibles sur toutes les pages.

new AcDatagridPro({
    target:  '#grille',
    url:     '/api/clients',
    preset:  'edition_avancee',  // épingles activées par edition_avancee et complet
    colonnes: [ ... ]
});

Export CSV / XLSX

Activez l'export avec export: true et choisissez le(s) format(s) avec export_formats.

new AcDatagridPro({
    url:             '/api/data',
    export:          true,
    export_formats:  ['csv', 'xlsx'],
    export_filename: 'mes_clients',
    colonnes: [ ... ]
});

Sous-grilles (maître/détail)

new AcDatagridPro({
    target:  '#praticiens',
    url:     '/api/praticiens',
    colonnes: [ ... ],

    sous_grilles: [{
        subgrid_param: 'id_praticien',   // champ transmis au backend de la sous-grille
        url:           '/api/patients',
        colonnes: [
            { champ: 'id',   titre: 'ID',  editable: false },
            { champ: 'nom',  titre: 'Nom' },
            { champ: 'tel',  titre: 'Tél.' },
        ],
    }],
});

Chaque objet de sous_grilles accepte les mêmes options qu'une grille normale (routes, theme, serverside, preset...). Plusieurs sous-grilles sont possibles (tableau, pas de limite à une seule).

Événements DOM

La grille émet des événements DOM personnalisés, qui remontent (bubbles) sur l'élément cible :

document.querySelector('#ma-grille')
  .addEventListener('acgr:apres-insert', function(e) {
      console.log('Champs insérés :', e.detail.donnees);
  });

Accessibilité v1.1.0

La grille pose automatiquement les attributs ARIA nécessaires pour qu'un lecteur d'écran ou une navigation 100% clavier comprenne sa structure et ses états — aucune configuration requise.

• Structure : role="grid" sur la table, row sur les lignes, columnheader sur les en-têtes, gridcell sur les cellules
• Tri : aria-sort reflète l'état réel (ascending / descending / none) sur chaque colonne triable
• Épingles : aria-label explicite ("Épingler" / "Désépingler") sur la cellule étoile — pas d'aria-pressed (contrairement à une version antérieure de cette doc)
• Sous-grilles : aria-expanded sur le bouton d'expansion, synchronisé à chaque ouverture/fermeture
• Boutons d'action : aria-label explicite sur éditer/dupliquer/supprimer (une icône seule n'est pas lisible par un lecteur d'écran)
• Résultats : aria-live="polite" sur la zone d'info — le nombre de résultats est annoncé automatiquement après un filtre ou un changement de page
• Pagination : aria-label="Pagination" sur le conteneur — pas de role="navigation" ni d'aria-current par page actuellement (contrairement à une version antérieure de cette doc)

Les libellés sont personnalisables via cfg.labels, comme tous les autres textes de la grille.

Méthodes publiques

Scrollbar horizontale miroir v1.0.5

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 tient à l'écran.
• 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 — toujours active.

Cas des onglets cachés

Quand la grille est dans un onglet display:none au chargement, son clientWidth est 0 et le calcul reste à zéro. Utiliser les hooks publics pour déclencher un recalcul une fois l'onglet visible.

Hooks publics JS v1.0.5

Chaque instance expose trois mécanismes pour forcer le recalcul de la scrollbar miroir depuis l'extérieur. Tous sont opt-in — les grilles existantes fonctionnent sans modification.

1. Méthode directe sur le conteneur

document.getElementById('mon_id').acgrRefreshScroll();

2. Événement DOM ciblé

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

3. Événement global — toutes les grilles

Dispatché sur document — toutes les grilles de la page recalculent simultanément. Idéal pour les systèmes d'onglets : un seul appel suffit.

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

// requestAnimationFrame garantit que display:block est effectif avant le calcul
requestAnimationFrame(function() {
    document.dispatchEvent(new CustomEvent('acgr:refresh-scroll-all'));
});

4. API référence

La grille délègue tout au réseau via cfg.routes, avec ces valeurs par défaut :

Query params de lire — précisions importantes

GET {url}?acgr_id=...&start=0&length=25&search=...&order_tris=...&filtres_colonnes=...

Trois paramètres sont des chaînes JSON, pas des tableaux natifs :

Réponse attendue

{
  "data":             [ { "id": 1, "nom": "Dupont", "prenom": "Marie" }, ... ],
  "recordsFiltered":  1234,
  "epinglees":        [ { "id": 5, "nom": "Martin", ... }, ... ],
  "totaux_generaux":  { "montant": 128450 }
}

Contrat d'API — sauvegarder

// Création — POST {url}
// Corps : { "nom": "Martin", "prenom": "Jean" }
// Réponse : { "id": 157 }

// Modification — PUT {url}/157
// Corps : { "nom": "Martin", "prenom": "Jean-Noël" }
// Réponse : {} (corps vide accepté, le code HTTP fait foi)

L'id retourné à la création est indispensable : c'est lui qui remplace le row_id négatif temporaire de la ligne fraîchement créée côté client.

Contrat d'API — supprimer

// DELETE {url}/157
// Réponse : {} (ou 204 No Content)

Le corps n'est pas inspecté, seul le code HTTP compte.

Contrat d'API — options_cascade

// GET {url}/cascade/id_statut?valeur_parent=3
// Réponse : { "options": [ { "id": 1, "libelle": "Actif" }, { "id": 2, "libelle": "Inactif" } ] }

Gestion des erreurs

Le code HTTP fait foi : tout code < 400 est un succès, tout code ≥ 400 un échec.

{ "message": "Explication lisible", "code": "VALIDATION_ERREUR" }

message est affiché à l'utilisateur ; code est transmis dans l'événement acgr:erreur (e.detail.code, absent si non fourni).

Adapter à un backend existant

Chaque entrée de cfg.routes accepte construire et/ou mapper, indépendamment — utile pour brancher la grille sur un backend qui suit d'autres conventions, y compris l'ancien schéma à endpoint unique décrit plus haut :

new AcDatagridPro({
    url: '/api/donnees.php',
    routes: {
        lire: {
            construire(params) {
                return { method: 'POST', url: '/api/donnees.php',
                         body: { action: 'load', page: Math.floor(params.start / params.length) + 1,
                                 per_page: params.length, search: params.search } };
            },
            mapper(json) {
                return { ok: json.status === 'ok', data: json.data,
                         recordsFiltered: json.total, totaux_generaux: json.totals };
            },
        },
        // ... sauvegarder / supprimer / options_cascade / exporter, même principe
    },
    colonnes: [ ... ]
});

Pas d'authentification/CSRF intégrée pour ce protocole (stateless) : branchez la vôtre via cfg.enTetes(action, params), appelé à chaque requête, qui retourne les en-têtes HTTP à fusionner (typiquement Authorization: Bearer ...).

Feuille de route