403 lines
12 KiB
Markdown
403 lines
12 KiB
Markdown
# 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 :**
|
|
```xhtml
|
|
<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 :**
|
|
```xml
|
|
<dependency>
|
|
<groupId>dev.lions</groupId>
|
|
<artifactId>primefaces-freya-extension</artifactId>
|
|
<version>1.0.0-SNAPSHOT</version>
|
|
</dependency>
|
|
```
|
|
|
|
2. **Utiliser le template :**
|
|
```xhtml
|
|
<ui:composition template="/WEB-INF/template.xhtml">
|
|
<ui:define name="content">
|
|
<!-- Votre contenu -->
|
|
</ui:define>
|
|
</ui:composition>
|
|
```
|
|
|
|
3. **Accéder aux préférences :**
|
|
```xhtml
|
|
#{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 :
|
|
```xml
|
|
<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
|
|
|