lionsdev/primefaces-freya-extension
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
primefaces-freya-extension/ANALYSE_INTEGRALE.md

12 KiB
Raw Permalink Blame History

Analyse Intégrale - PrimeFaces Freya Extension

📋 Vue d'ensemble

PrimeFaces Freya Extension est une extension Quarkus qui intègre le thème premium Freya de PrimeFaces dans l'écosystème Quarkus, permettant aux développeurs d'utiliser facilement ce thème moderne et personnalisable dans leurs applications Quarkus basées sur JSF/PrimeFaces.

🎯 Intention du Projet

Objectif Principal

L'intention principale de ce projet est de créer une extension Quarkus réutilisable qui :

  1. Intègre le thème Freya de PrimeFaces dans Quarkus de manière native
  2. Fournit un template de layout complet avec tous les composants nécessaires (menu, topbar, footer, panneau de configuration)
  3. Simplifie l'adoption du thème Freya pour les développeurs Quarkus en évitant la configuration manuelle complexe
  4. Offre une personnalisation dynamique via un bean de session (GuestPreferences) pour gérer les préférences utilisateur (thème clair/sombre, couleurs, styles de menu, etc.)

Contexte d'Utilisation

Cette extension est conçue pour être utilisée dans des projets comme :

  • lions-user-manager (gestion d'utilisateurs Keycloak avec interface PrimeFaces Freya)
  • gbcm-llc (plateforme de conseil en management)
  • btpxpress (plateforme de gestion BTP)
  • Tout autre projet Quarkus nécessitant une interface moderne avec PrimeFaces

🏗️ Architecture du Projet

Structure Multi-Modules Maven

Le projet suit l'architecture standard des extensions Quarkus avec 3 modules :

primefaces-freya-extension/
├── pom.xml                          # Module parent
├── runtime/                         # Module runtime (dépendances et ressources)
│   ├── pom.xml
│   └── src/main/
│       ├── java/                    # Bean de gestion des préférences
│       └── resources/
│           └── META-INF/
│               ├── quarkus-extension.properties
│               └── resources/       # Templates XHTML, CSS, JS, images
├── deployment/                      # Module de déploiement (build-time)
│   └── pom.xml
└── integration-tests/               # Tests d'intégration
    ├── pom.xml
    └── src/main/resources/
        └── META-INF/resources/
            └── index.xhtml          # Page de vérification

Module Runtime (runtime/)

Responsabilités :

  • Définit les dépendances nécessaires (PrimeFaces, Freya Theme, Quarkus PrimeFaces)
  • Contient toutes les ressources statiques (templates, CSS, JS, images)
  • Fournit le bean GuestPreferences pour la gestion des préférences utilisateur

Dépendances clés :

  • quarkus-primefaces (3.14.0) - Support PrimeFaces pour Quarkus
  • primefaces (14.0.0) - Framework JSF PrimeFaces
  • freya-theme (5.0.0-jakarta) - Thème premium Freya
  • quarkus-awt - Support AWT pour le rendu

Ressources fournies :

  • Templates XHTML : template.xhtml, menu.xhtml, topbar.xhtml, footer.xhtml, config.xhtml
  • Pages d'exemple : landing.xhtml, login.xhtml, error.xhtml, notfound.xhtml, etc.
  • Assets : CSS compilés, JavaScript, images, icônes PrimeIcons
  • SCSS sources : Fichiers SCSS pour personnalisation avancée

Module Deployment (deployment/)

Responsabilités :

  • Configure le build-time processing de Quarkus
  • Définit les dépendances de déploiement nécessaires
  • Utilise le processeur d'extension Quarkus pour générer les métadonnées

Dépendances de déploiement :

  • quarkus-arc-deployment - Injection de dépendances
  • quarkus-undertow-deployment - Serveur web
  • myfaces-quarkus-deployment - Support JSF/MyFaces
  • quarkus-poi-deployment - Support Excel
  • quarkus-itext-deployment - Support PDF

Module Integration Tests (integration-tests/)

Responsabilités :

  • Contient une application de test minimale
  • Vérifie que l'extension fonctionne correctement
  • Page de vérification (index.xhtml) pour tester le rendu

🔧 Composants Techniques

1. Bean de Préférences (GuestPreferences.java)

Localisation : runtime/src/main/java/org/primefaces/freya/view/GuestPreferences.java

Fonctionnalités :

  • Gestion du mode sombre/clair : darkMode (light/dark)
  • Thèmes de composants : 8 couleurs disponibles (Blue, Green, Orange, Turquoise, Avocado, Purple, Red, Yellow)
  • Modes de menu : Sidebar, Horizontal, Slim
  • Thèmes de sections : Topbar et Menu peuvent avoir des thèmes indépendants
  • Style d'input : Outlined ou Filled
  • Gestion du logo : Logo clair ou sombre selon le thème

Portée : @SessionScoped - Les préférences sont persistées par session utilisateur

2. Template Principal (template.xhtml)

Localisation : runtime/src/main/resources/META-INF/resources/WEB-INF/template.xhtml

Structure :

  • En-tête avec métadonnées et scripts
  • Layout wrapper avec classes dynamiques basées sur les préférences
  • Inclusion des composants : topbar, menu, rightpanel, config
  • Zone de contenu principale (<ui:insert name="content"/>)
  • Footer
  • Indicateur de chargement AJAX
  • Styles dynamiques selon les préférences

Utilisation :

<ui:composition template="/WEB-INF/template.xhtml">
    <ui:define name="content">
        <!-- Contenu de la page -->
    </ui:define>
</ui:composition>

3. Panneau de Configuration (config.xhtml)

Localisation : runtime/src/main/resources/META-INF/resources/WEB-INF/config.xhtml

Fonctionnalités :

  • Bouton de configuration (icône engrenage)
  • Panneau latéral avec options :
    • Type de menu (Horizontal/Sidebar/Slim)
    • Schéma de couleurs (Light/Dark)
    • Thèmes de topbar et menu (indépendants)
    • Style d'input (Outlined/Filled)
    • Sélection de couleur de thème (8 options)

Interaction : Utilise JavaScript PrimeFaces.FreyaConfigurator pour les changements dynamiques

4. Menu (menu.xhtml)

Structure :

  • Logo Freya
  • Bouton de pin/unpin du menu
  • Menu PrimeFaces avec composant personnalisé <fr:menu>
  • Exemple de structure avec sous-menus

5. Topbar (topbar.xhtml)

Composants :

  • Bouton menu hamburger
  • Logo (adaptatif selon le thème)
  • Barre de recherche
  • Profil utilisateur avec menu déroulant
  • Bouton panneau latéral

6. Ressources Statiques

CSS :

  • layout-light.css / layout-dark.css - Styles compilés
  • primeflex.min.css - Framework CSS utilitaire
  • primeicons.css - Bibliothèque d'icônes

JavaScript :

  • layout.js - Logique de configuration et interaction du layout
  • prism.js - Coloration syntaxique (pour documentation)

Images :

  • Logos (Freya standard, blanc, single)
  • Avatar par défaut
  • Images de pages d'erreur/404
  • Favicon

SCSS Sources :

  • Structure modulaire avec variables, mixins, layouts, thèmes
  • Permet la personnalisation avancée avant compilation

🔌 Intégration Quarkus

Extension Metadata

Fichier : quarkus-extension.properties

deployment-artifact=dev.lions:primefaces-freya-extension-deployment:1.0.0-SNAPSHOT
requires-quarkus-version=[3.15,)

Fichier : quarkus-extension.yaml

  • Liste toutes les dépendances d'extension requises
  • Définit les métadonnées de l'extension
  • Spécifie la version minimale de Quarkus (3.15+)

Dépendances Requises

L'extension nécessite automatiquement :

  • quarkus-primefaces - Support PrimeFaces
  • quarkus-arc - Injection de dépendances
  • myfaces-quarkus - Support JSF
  • quarkus-undertow - Serveur web
  • quarkus-awt - Support graphique
  • Et autres dépendances transitives

Utilisation dans un Projet

Pour utiliser cette extension dans un projet Quarkus :

  1. Ajouter la dépendance :
<dependency>
    <groupId>dev.lions</groupId>
    <artifactId>primefaces-freya-extension</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>
  1. Utiliser le template :
<ui:composition template="/WEB-INF/template.xhtml">
    <ui:define name="content">
        <!-- Votre contenu -->
    </ui:define>
</ui:composition>
  1. Accéder aux préférences :
#{guestPreferences.darkMode}
#{guestPreferences.componentTheme}

🎨 Fonctionnalités du Thème Freya

Personnalisation Dynamique

  1. 8 Thèmes de Couleur :

    • Blue (#2c84d8)
    • Green (#34B56F)
    • Orange (#FF810E)
    • Turquoise (#58AED3)
    • Avocado (#AEC523)
    • Purple (#464DF2) - Par défaut
    • Red (#FF9B7B)
    • Yellow (#FFB340)

  2. Modes d'Affichage :

    • Light Mode
    • Dark Mode

  3. Layouts de Menu :

    • Sidebar (par défaut)
    • Horizontal
    • Slim

  4. Styles d'Input :

    • Outlined (par défaut)
    • Filled

Pages Prédéfinies

L'extension fournit des templates pour :

  • Landing page (landing.xhtml) - Page d'accueil marketing
  • Login (login.xhtml) - Page de connexion
  • Error (error.xhtml) - Page d'erreur
  • 404 (notfound.xhtml) - Page non trouvée
  • Access Denied (access.xhtml) - Accès refusé
  • Help (help.xhtml) - Aide
  • Invoice (invoice.xhtml) - Facture
  • Empty (empty.xhtml) - Page vide

📊 Versions et Compatibilité

Versions Utilisées

  • Quarkus : 3.15.1
  • Java : 17
  • PrimeFaces : 14.0.0
  • Freya Theme : 5.0.0-jakarta
  • Quarkus PrimeFaces : 3.14.0

Compatibilité

  • Quarkus : ≥ 3.15
  • Jakarta EE : Compatible Jakarta (pas Java EE)
  • Java : 17+

🔍 Points d'Attention

1. Repository Local

Le projet référence un repository Maven local :

<repository>
    <id>local-maven-repo</id>
    <url>file://${project.basedir}/../../maven-repo</url>
</repository>

Cela suggère que certaines dépendances peuvent être dans un repository local.

2. License Commerciale

Le thème Freya est sous PrimeFaces Commercial License, ce qui signifie :

  • ⚠️ Nécessite une licence commerciale pour usage en production
  • ⚠️ Le code source de GuestPreferences.java mentionne cette licence

3. Module Deployment Vide

Le module deployment/ ne contient pas de code Java, seulement des dépendances. Cela peut indiquer :

  • Une extension simple qui ne nécessite pas de processing build-time complexe
  • Ou une structure en cours de développement

4. Tests d'Intégration Minimaux

Le module integration-tests/ contient seulement une page de vérification basique, pas de tests automatisés complets.

💡 Cas d'Usage

Utilisation dans l'Écosystème Lions

Cette extension est conçue pour être utilisée dans :

  1. lions-user-manager

    • Interface de gestion d'utilisateurs Keycloak
    • Utilise PrimeFaces Freya pour l'UI

  2. gbcm-llc

    • Plateforme de conseil en management
    • Interface client avec thème moderne

  3. btpxpress

    • Gestion d'entreprise BTP
    • Interface web pour gestion de chantiers

Avantages

✅ Réutilisabilité : Une seule extension pour tous les projets
✅ Cohérence : Même look & feel across projects
✅ Maintenance : Mise à jour centralisée
✅ Rapidité : Démarrage rapide avec template complet
✅ Personnalisation : Facile à personnaliser via SCSS et préférences

🚀 État du Projet

Statut Actuel

  • ✅ Structure multi-modules complète
  • ✅ Templates XHTML fonctionnels
  • ✅ Bean de préférences implémenté
  • ✅ Ressources statiques intégrées
  • ✅ Métadonnées d'extension Quarkus configurées
  • ⚠️ Tests d'intégration minimaux
  • ⚠️ Documentation manquante (pas de README)

Recommandations

  1. Ajouter un README.md avec instructions d'utilisation
  2. Compléter les tests d'intégration avec des tests automatisés
  3. Documenter les variables SCSS pour personnalisation
  4. Ajouter des exemples de pages utilisant le template
  5. Créer une documentation sur la personnalisation avancée

📝 Conclusion

PrimeFaces Freya Extension est une extension Quarkus bien structurée qui intègre le thème premium Freya de PrimeFaces dans l'écosystème Quarkus. Son intention principale est de simplifier l'adoption et l'utilisation du thème Freya dans les projets Quarkus en fournissant :

  • Un template de layout complet et prêt à l'emploi
  • Un système de préférences utilisateur pour la personnalisation dynamique
  • Toutes les ressources nécessaires (CSS, JS, images)
  • Une intégration native avec Quarkus via le système d'extensions

Cette extension permet aux développeurs de démarrer rapidement avec une interface moderne et professionnelle sans avoir à configurer manuellement tous les composants du thème Freya.

Date d'analyse : 2025-01-27
Version analysée : 1.0.0-SNAPSHOT