337 lines
11 KiB
Markdown
337 lines
11 KiB
Markdown
# 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
|