Initial commit: PrimeFaces Freya Extension - Composants Freya pour PrimeFaces avec support Quarkus
This commit is contained in:
dahoud
336
ANALYSE_OFFICIELLE.md
Normal file
336
ANALYSE_OFFICIELLE.md
Normal file
@@ -0,0 +1,336 @@
|
||||
# Analyse Basée sur les Sources Officielles - PrimeFaces Freya Extension
|
||||
|
||||
**Date** : 2025-12-25
|
||||
**Sources** : Freya 5.0.0, Jakarta EE, PrimeFaces 14.0.0
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Découvertes Importantes
|
||||
|
||||
### ❌ ERREUR D'INTERPRÉTATION INITIALE
|
||||
|
||||
L'analyse précédente (README.md et TODO.md) affirmait que l'extension devait fournir **25 composants composites**. Cette affirmation est **INCORRECTE** basée sur les sources officielles de Freya.
|
||||
|
||||
### ✅ RÉALITÉ SELON LES SOURCES OFFICIELLES
|
||||
|
||||
Après avoir analysé les sources Freya 5.0.0 locales (`C:/Users/dadyo/PersonalProjects/lions-workspace/freya/`), voici la réalité :
|
||||
|
||||
**Freya fournit** :
|
||||
1. ✅ **UN SEUL composant custom** : `FreyaMenu` (composant Java avec renderer)
|
||||
- Localisation : `tag/src/main/java/org/primefaces/freya/component/FreyaMenu.java`
|
||||
- Taglib : `META-INF/primefaces-freya.taglib.xml`
|
||||
- Namespace : `http://primefaces.org/freya`
|
||||
- Usage : `<fr:menu model="#{menuBean.model}" />`
|
||||
|
||||
2. ✅ **Templates de layout** :
|
||||
- `template.xhtml`, `menu.xhtml`, `topbar.xhtml`, `footer.xhtml`, `config.xhtml`
|
||||
- 8 pages prédéfinies (landing, login, error, etc.)
|
||||
|
||||
3. ✅ **Exemples d'utilisation** de composants PrimeFaces standards :
|
||||
- `input.xhtml` - Démo des composants input de PrimeFaces
|
||||
- `crud.xhtml` - Démo CRUD avec p:dataTable, p:dialog
|
||||
- Autres démos : button, calendar, charts, formlayout, etc.
|
||||
|
||||
**Freya NE fournit PAS** :
|
||||
- ❌ Bibliothèque de composants composites
|
||||
- ❌ Wrappers autour des composants PrimeFaces
|
||||
- ❌ Composants `fr:inputText`, `fr:card`, `fr:dataTable`, etc.
|
||||
|
||||
---
|
||||
|
||||
## 📚 Ce que Disent les Documentations Officielles
|
||||
|
||||
### Jakarta EE - Composite Components
|
||||
|
||||
**Source** : https://jakarta.ee/learn/docs/jakartaee-tutorial/current/web/faces-advanced-cc/faces-advanced-cc.html
|
||||
|
||||
Les composite components sont créés avec :
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<ui:composition xmlns:composite="http://xmlns.jcp.org/jsf/composite"
|
||||
xmlns:p="http://primefaces.org/ui">
|
||||
|
||||
<composite:interface>
|
||||
<composite:attribute name="label" required="false" />
|
||||
<composite:attribute name="value" required="false" />
|
||||
<composite:editableValueHolder name="input" targets="inputComponent" />
|
||||
</composite:interface>
|
||||
|
||||
<composite:implementation>
|
||||
<div class="field">
|
||||
<p:outputLabel value="#{cc.attrs.label}" />
|
||||
<p:inputText id="inputComponent" value="#{cc.attrs.value}" />
|
||||
<p:message for="inputComponent" />
|
||||
</div>
|
||||
</composite:implementation>
|
||||
|
||||
</ui:composition>
|
||||
```
|
||||
|
||||
**Éléments clés** :
|
||||
- `composite:attribute` - Définit les attributs du composant
|
||||
- `composite:editableValueHolder` - Permet le binding bidirectionnel
|
||||
- `composite:actionSource` - Pour les actions (boutons)
|
||||
- `#{cc.attrs.*}` - Accès aux attributs dans l'implémentation
|
||||
- `targets="inputComponent"` - Spécifie le composant cible
|
||||
|
||||
### PrimeFaces 14.0.0
|
||||
|
||||
**Source** : https://primefaces.github.io/primefaces/14_0_0/
|
||||
|
||||
PrimeFaces fournit des composants standards :
|
||||
- **Input** : p:inputText, p:inputTextarea, p:inputNumber, p:password, p:selectOneMenu, p:calendar, etc.
|
||||
- **Data** : p:dataTable, p:dataView, p:tree
|
||||
- **Panel** : p:panel, p:dialog, p:accordionPanel
|
||||
- **Button** : p:commandButton, p:button, p:linkButton
|
||||
- **Message** : p:message, p:messages, p:growl
|
||||
|
||||
**Ces composants sont DÉJÀ complets et prêts à l'emploi.**
|
||||
|
||||
### Freya Theme - Pattern d'Utilisation
|
||||
|
||||
**Source** : `C:/Users/dadyo/PersonalProjects/lions-workspace/freya/tag/src/main/webapp/`
|
||||
|
||||
Freya utilise les composants PrimeFaces **directement**, avec les classes CSS de Freya :
|
||||
|
||||
```xhtml
|
||||
<!-- Exemple tiré de input.xhtml -->
|
||||
<div class="grid ui-fluid">
|
||||
<div class="col-12 md:col-6">
|
||||
<div class="card">
|
||||
<h5>InputText</h5>
|
||||
<div class="grid formgrid">
|
||||
<div class="col-12 mb-2 lg:col-4 mb-lg-0">
|
||||
<p:inputText placeholder="Default" />
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h5>Float Label</h5>
|
||||
<span class="ui-float-label">
|
||||
<p:inputText id="float-input" />
|
||||
<p:outputLabel for="@previous" value="Username" />
|
||||
</span>
|
||||
|
||||
<h5>Textarea</h5>
|
||||
<p:inputTextarea placeholder="Your message" />
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Pattern Freya** :
|
||||
- Classes CSS : `grid`, `card`, `field`, `formgrid`, `ui-fluid`, `ui-float-label`
|
||||
- Composants PrimeFaces standards : `p:inputText`, `p:inputTextarea`, etc.
|
||||
- Pas de wrappers ou composants composites
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Recommandation Stratégique
|
||||
|
||||
### ❌ Approche REJETÉE (Ancienne Vision)
|
||||
|
||||
Créer 25 composants composites custom (`fr:inputText`, `fr:card`, etc.) est :
|
||||
1. **Inutile** - PrimeFaces fournit déjà tout
|
||||
2. **Non conforme** à Freya officiel
|
||||
3. **Maintenance complexe** - Duplication de code
|
||||
4. **Contre-productif** - Rajoute une couche inutile
|
||||
|
||||
### ✅ Approche RECOMMANDÉE (Conforme aux Sources Officielles)
|
||||
|
||||
**Option 1 : Extension Minimaliste (RECOMMANDÉ)**
|
||||
|
||||
Fournir uniquement :
|
||||
1. ✅ Composant `FreyaMenu` (déjà fait dans `primefaces-freya.taglib.xml`)
|
||||
2. ✅ Templates de layout (déjà fait)
|
||||
3. ✅ Bean `GuestPreferences` (déjà fait)
|
||||
4. ✅ Documentation sur l'utilisation des composants PrimeFaces avec Freya
|
||||
|
||||
**Avantages** :
|
||||
- Conforme à Freya officiel
|
||||
- Maintenance minimale
|
||||
- Réutilise PrimeFaces directement
|
||||
- Simple et efficace
|
||||
|
||||
**Option 2 : Composants Composites Ciblés (Si vraiment nécessaire)**
|
||||
|
||||
Si vous voulez vraiment des composants composites, créez **uniquement** ceux qui ajoutent de la valeur :
|
||||
|
||||
**Candidats potentiels** (maximum 5 composants) :
|
||||
1. `fr:fieldInput` - Field + Label + Input + Message (pattern répété partout)
|
||||
2. `fr:fieldSelect` - Field + Label + SelectOneMenu + Message
|
||||
3. `fr:actionDialog` - Dialog avec footer buttons standardisés
|
||||
4. `fr:dataTableCrud` - DataTable avec toolbar CRUD standard
|
||||
5. `fr:formCard` - Card avec formulaire et actions
|
||||
|
||||
**Avantages** :
|
||||
- Réduit la duplication de code
|
||||
- Patterns cohérents
|
||||
- Toujours basé sur PrimeFaces
|
||||
|
||||
**À NE PAS FAIRE** :
|
||||
- ❌ Ne pas wrapper TOUS les composants PrimeFaces
|
||||
- ❌ Ne pas créer des composants qui n'ajoutent aucune valeur
|
||||
- ❌ Ne pas créer de composants juste pour "avoir 25 composants"
|
||||
|
||||
---
|
||||
|
||||
## 📋 Structure Recommandée pour les Composants Composites (Si Option 2)
|
||||
|
||||
### Exemple : fr:fieldInput
|
||||
|
||||
**Fichier** : `runtime/src/main/resources/META-INF/resources/freya/fieldInput.xhtml`
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<ui:composition xmlns="http://www.w3.org/1999/xhtml"
|
||||
xmlns:ui="http://xmlns.jcp.org/jsf/facelets"
|
||||
xmlns:composite="http://xmlns.jcp.org/jsf/composite"
|
||||
xmlns:p="http://primefaces.org/ui">
|
||||
|
||||
<composite:interface>
|
||||
<!-- Attributs du composant -->
|
||||
<composite:attribute name="label" type="java.lang.String" required="false" />
|
||||
<composite:attribute name="value" required="false" />
|
||||
<composite:attribute name="required" type="java.lang.Boolean" default="false" />
|
||||
<composite:attribute name="placeholder" type="java.lang.String" required="false" />
|
||||
<composite:attribute name="disabled" type="java.lang.Boolean" default="false" />
|
||||
<composite:attribute name="styleClass" type="java.lang.String" required="false" />
|
||||
|
||||
<!-- Binding pour l'input -->
|
||||
<composite:editableValueHolder name="input" targets="inputComponent" />
|
||||
</composite:interface>
|
||||
|
||||
<composite:implementation>
|
||||
<!-- Pattern Freya field -->
|
||||
<div class="field #{cc.attrs.styleClass}">
|
||||
<p:outputLabel for="#{cc.clientId}:inputComponent"
|
||||
value="#{cc.attrs.label}"
|
||||
rendered="#{not empty cc.attrs.label}" />
|
||||
|
||||
<p:inputText id="inputComponent"
|
||||
value="#{cc.attrs.value}"
|
||||
required="#{cc.attrs.required}"
|
||||
placeholder="#{cc.attrs.placeholder}"
|
||||
disabled="#{cc.attrs.disabled}" />
|
||||
|
||||
<p:message for="inputComponent" />
|
||||
</div>
|
||||
</composite:implementation>
|
||||
|
||||
</ui:composition>
|
||||
```
|
||||
|
||||
**Utilisation** :
|
||||
```xhtml
|
||||
<fr:fieldInput label="Nom"
|
||||
value="#{bean.nom}"
|
||||
required="true"
|
||||
placeholder="Entrez votre nom" />
|
||||
```
|
||||
|
||||
**Avantages** :
|
||||
- Réduit le code répétitif
|
||||
- Pattern Freya cohérent (field + label + input + message)
|
||||
- Basé sur p:inputText standard
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Plan d'Action Révisé
|
||||
|
||||
### Phase 1 : Nettoyage (1 jour)
|
||||
|
||||
1. ✅ Supprimer `freya.taglib.xml` (25 composants fictifs)
|
||||
2. ✅ Garder `primefaces-freya.taglib.xml` (FreyaMenu uniquement)
|
||||
3. ✅ Mettre à jour README avec la vraie vision
|
||||
4. ✅ Créer guide d'utilisation des composants PrimeFaces avec Freya
|
||||
|
||||
### Phase 2 : Composants Ciblés (2-3 jours) - OPTIONNEL
|
||||
|
||||
Si vraiment nécessaire, créer 3-5 composants composites qui ajoutent de la valeur :
|
||||
|
||||
1. `fr:fieldInput` - Field pattern Freya
|
||||
2. `fr:fieldSelect` - SelectOneMenu avec field pattern
|
||||
3. `fr:actionDialog` - Dialog standardisé
|
||||
|
||||
### Phase 3 : Documentation (1 jour)
|
||||
|
||||
1. ✅ Guide d'utilisation Freya + PrimeFaces
|
||||
2. ✅ Exemples de pages (inspirés de Freya officiel)
|
||||
3. ✅ Bonnes pratiques CSS Freya (grid, card, field, etc.)
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation à Créer
|
||||
|
||||
### 1. FREYA_USAGE_GUIDE.md
|
||||
|
||||
Guide pratique sur l'utilisation des composants PrimeFaces avec les classes CSS Freya :
|
||||
|
||||
**Contenu** :
|
||||
- Classes CSS Freya (grid, card, field, ui-fluid, ui-float-label)
|
||||
- Patterns de formulaire
|
||||
- Patterns de tableau
|
||||
- Patterns de dialog
|
||||
- Exemples complets tirés de Freya officiel
|
||||
|
||||
### 2. COMPOSITE_COMPONENTS_GUIDE.md (Si Option 2)
|
||||
|
||||
Guide sur les composants composites créés :
|
||||
|
||||
**Contenu** :
|
||||
- Liste des composants (3-5 maximum)
|
||||
- Attributs de chaque composant
|
||||
- Exemples d'utilisation
|
||||
- Quand les utiliser vs composants PrimeFaces directs
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Checklist de Conformité
|
||||
|
||||
Pour être conforme aux sources officielles, l'extension DOIT :
|
||||
|
||||
- ✅ Fournir le composant `FreyaMenu` (déjà fait)
|
||||
- ✅ Fournir les templates de layout (déjà fait)
|
||||
- ✅ Fournir le bean `GuestPreferences` (déjà fait)
|
||||
- ✅ Documenter l'utilisation de PrimeFaces avec Freya
|
||||
- ❌ NE PAS wrapper tous les composants PrimeFaces
|
||||
- ❌ NE PAS créer 25 composants composites inutiles
|
||||
|
||||
---
|
||||
|
||||
## 💡 Conclusion
|
||||
|
||||
**Décision stratégique requise** :
|
||||
|
||||
### Option A : Extension Minimaliste (RECOMMANDÉ)
|
||||
**Temps** : 1 jour (nettoyage + documentation)
|
||||
**Résultat** : Extension conforme, simple, maintenable
|
||||
|
||||
### Option B : Composants Composites Ciblés
|
||||
**Temps** : 3-4 jours (nettoyage + 3-5 composants + documentation)
|
||||
**Résultat** : Extension avec valeur ajoutée légère
|
||||
|
||||
---
|
||||
|
||||
**Recommandation finale** : **Option A**
|
||||
|
||||
Freya + PrimeFaces fournissent déjà TOUT ce dont vous avez besoin. Créer 25 composants composites serait une **sur-ingénierie** qui n'apporte aucune valeur et complexifie la maintenance.
|
||||
|
||||
**La vraie valeur de l'extension** réside dans :
|
||||
1. Le composant `FreyaMenu` custom
|
||||
2. Les templates de layout professionnels
|
||||
3. Le bean de gestion des préférences
|
||||
4. La documentation d'utilisation de Freya + PrimeFaces
|
||||
|
||||
C'est exactement ce que l'extension fournit déjà ! ✅
|
||||
|
||||
---
|
||||
|
||||
**Sources consultées** :
|
||||
- ✅ `C:/Users/dadyo/PersonalProjects/lions-workspace/freya/` (Freya 5.0.0 officiel)
|
||||
- ✅ Jakarta EE Tutorial - Composite Components
|
||||
- ✅ PrimeFaces 14.0.0 (site officiel)
|
||||
|
||||
**Date d'analyse** : 2025-12-25
|
||||
**Validité** : Basée sur Freya 5.0.0, Jakarta EE, PrimeFaces 14.0.0
|
||||
Reference in New Issue
Block a user