lionsdev/lions-user-manager-client-quarkus-primefaces-freya
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9cb5e82f654e3d37772e355081f5f9e94e08c319
lions-user-manager-client-q…/target/classes/META-INF/resources/templates/components/shared/README_KPI.md

7.4 KiB
Raw Blame History

📊 Composants KPI Réutilisables - Écosystème LionsDev

Version: 2.0.0
Date: 2025-01-29
Pattern: WOU/DRY (Write Once Use / Don't Repeat Yourself)

🎯 Vue d'Ensemble

Ces composants KPI (Indicateurs de Performance) sont conçus pour être 100% réutilisables dans tous les projets de l'écosystème lionsdev. Ils suivent les meilleures pratiques de PrimeFaces Freya et offrent une expérience utilisateur cohérente.

📦 Composants Disponibles

1. kpi-card.xhtml - Carte KPI Individuelle

Composant principal pour afficher un indicateur de performance unique.

Localisation: /templates/components/shared/cards/kpi-card.xhtml

Paramètres principaux:

  • title (requis) - Titre du KPI
  • value (requis) - Valeur à afficher
  • icon (requis) - Icône PrimeIcons
  • iconColor (requis) - Couleur de l'icône
  • growthValue (optionnel) - Valeur de croissance
  • growthLabel (optionnel) - Libellé de croissance
  • progressValue (optionnel) - Barre de progression 0-100
  • statusIcon, statusLabel, statusValue (optionnel) - Mode statut
  • clickable (défaut: false) - Rendre cliquable
  • clickOutcome (optionnel) - Redirection au clic

Exemple simple:

<ui:include src="/templates/components/shared/cards/kpi-card.xhtml">
    <ui:param name="title" value="Total Utilisateurs" />
    <ui:param name="value" value="#{bean.totalUsers}" />
    <ui:param name="icon" value="pi-users" />
    <ui:param name="iconColor" value="blue-600" />
</ui:include>

Exemple avec croissance:

<ui:include src="/templates/components/shared/cards/kpi-card.xhtml">
    <ui:param name="title" value="Utilisateurs Actifs" />
    <ui:param name="value" value="#{bean.activeUsers}" />
    <ui:param name="icon" value="pi-user-check" />
    <ui:param name="iconColor" value="green-600" />
    <ui:param name="growthValue" value="#{bean.growthPercent}" />
    <ui:param name="growthLabel" value="ce mois" />
    <ui:param name="progressValue" value="#{bean.progressPercent}" />
</ui:include>

Exemple avec statut:

<ui:include src="/templates/components/shared/cards/kpi-card.xhtml">
    <ui:param name="title" value="Sessions Actives" />
    <ui:param name="value" value="#{bean.activeSessions}" />
    <ui:param name="icon" value="pi-sign-in" />
    <ui:param name="iconColor" value="purple-600" />
    <ui:param name="statusIcon" value="pi-check-circle" />
    <ui:param name="statusLabel" value="En ligne" />
    <ui:param name="statusValue" value="#{bean.onlineUsers} actifs" />
</ui:include>

2. kpi-group.xhtml - Groupe de KPI

Composant composite pour organiser plusieurs KPI dans une grille.

Localisation: /templates/components/shared/dashboard/kpi-group.xhtml

Paramètres:

  • title (optionnel) - Titre de la section
  • columns (défaut: 4) - Nombre de colonnes (1-6)
  • colSize (optionnel) - Taille personnalisée

Exemple:

<ui:include src="/templates/components/shared/dashboard/kpi-group.xhtml">
    <ui:param name="title" value="Statistiques Utilisateurs" />
    <ui:param name="columns" value="4" />
    <ui:define name="kpi-content">
        <!-- KPI 1 -->
        <ui:include src="/templates/components/shared/cards/kpi-card.xhtml">
            <ui:param name="title" value="Total" />
            <ui:param name="value" value="#{bean.total}" />
            <ui:param name="icon" value="pi-users" />
            <ui:param name="iconColor" value="blue-600" />
        </ui:include>
        <!-- KPI 2, 3, 4... -->
    </ui:define>
</ui:include>

3. dashboard-section.xhtml - Section Dashboard

Composant composite pour créer des sections de dashboard réutilisables.

Localisation: /templates/components/shared/dashboard/dashboard-section.xhtml

Paramètres:

  • title (requis) - Titre de la section
  • description (optionnel) - Description
  • icon (optionnel) - Icône
  • colSize (défaut: "col-12") - Taille de colonne
  • showCard (défaut: true) - Envelopper dans une carte

Exemple:

<ui:include src="/templates/components/shared/dashboard/dashboard-section.xhtml">
    <ui:param name="title" value="Actions Rapides" />
    <ui:param name="icon" value="pi-bolt" />
    <ui:param name="colSize" value="col-12 lg:col-6" />
    <ui:define name="section-content">
        <!-- Contenu de la section -->
        <div class="grid">
            <div class="col-12 md:col-6">
                <p:commandButton value="Action 1" />
            </div>
        </div>
    </ui:define>
</ui:include>

4. user-stat-card.xhtml - Wrapper de Compatibilité

Wrapper de compatibilité ascendante qui délègue à kpi-card.xhtml.

Note: Pour de nouvelles implémentations, utilisez directement kpi-card.xhtml.

🎨 Couleurs Disponibles

Utilisez les couleurs PrimeFlex pour iconColor:

  • blue-600, blue-500, blue-400
  • green-600, green-500, green-400
  • purple-600, purple-500, purple-400
  • orange-600, orange-500, orange-400
  • red-600, red-500, red-400
  • cyan-600, cyan-500, cyan-400
  • pink-600, pink-500, pink-400

📐 Tailles de Colonnes

Utilisez les classes PrimeFlex pour colSize:

  • col-12 - Pleine largeur
  • col-12 md:col-6 - 2 colonnes sur tablette+
  • col-12 md:col-6 lg:col-3 - 4 colonnes sur desktop (défaut)
  • col-12 md:col-4 - 3 colonnes
  • col-12 md:col-6 lg:col-2 - 6 colonnes

🔄 Réutilisabilité dans l'Écosystème LionsDev

Ces composants peuvent être utilisés dans:

  • ✅ lions-user-manager (module actuel)
  • ✅ unionflow (via dépendance Maven)
  • ✅ btpxpress (via dépendance Maven)
  • ✅ Tout autre projet lionsdev (via dépendance Maven)

Avantages:

  • Code DRY (Don't Repeat Yourself)
  • Interface utilisateur cohérente
  • Maintenance centralisée
  • Évolutivité garantie

📝 Bonnes Pratiques

  1. Toujours utiliser kpi-card.xhtml pour de nouveaux KPI
  2. Utiliser kpi-group.xhtml pour organiser plusieurs KPI
  3. Utiliser dashboard-section.xhtml pour structurer les dashboards
  4. Respecter les conventions de couleurs PrimeFlex
  5. Documenter les paramètres personnalisés dans votre code

🚀 Exemple Complet de Dashboard

<div class="grid">
    <!-- En-tête -->
    <div class="col-12">
        <ui:include src="/templates/components/layout/page-header.xhtml">
            <ui:param name="title" value="Tableau de Bord" />
        </ui:include>
    </div>
    
    <!-- KPIs -->
    <div class="col-12">
        <div class="grid">
            <ui:include src="/templates/components/shared/cards/kpi-card.xhtml">
                <ui:param name="title" value="Total" />
                <ui:param name="value" value="#{bean.total}" />
                <ui:param name="icon" value="pi-users" />
                <ui:param name="iconColor" value="blue-600" />
            </ui:include>
            <!-- Autres KPI... -->
        </div>
    </div>
    
    <!-- Sections -->
    <ui:include src="/templates/components/shared/dashboard/dashboard-section.xhtml">
        <ui:param name="title" value="Actions Rapides" />
        <ui:define name="section-content">
            <!-- Contenu -->
        </ui:define>
    </ui:include>
</div>

📚 Documentation Complète

Pour plus de détails, consultez:

  • /templates/components/README.md - Documentation générale
  • Code source des composants avec commentaires JSDoc

Auteur: Lions User Manager Team
Licence: Écosystème LionsDev