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

13 KiB
Raw Blame History

Architecture

Ce document décrit l'architecture de PrimeFaces Freya Extension.

🏗️ Vue d'ensemble

PrimeFaces Freya Extension est une bibliothèque de composants composites Jakarta Faces qui simplifie l'utilisation de PrimeFaces avec le thème Freya.

Principe de base

XHTML Page → Freya Extension → PrimeFaces → Jakarta Faces → HTML/CSS/JS

📊 Diagramme d'architecture

┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                         │
│  ┌──────────────┐      ┌──────────────┐      ┌────────────┐ │
│  │ XHTML Pages  │ ───> │ Managed Beans│ ───> │  Business  │ │
│  └──────────────┘      └──────────────┘      │   Logic    │ │
│         │                                     └────────────┘ │
└─────────┼───────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│           PrimeFaces Freya Extension (46 composants)         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ fr:fieldInput│  │ fr:fieldSelect│ │fr:actionDialog│      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│         │                 │                  │               │
│         └─────────────────┴──────────────────┘               │
│                           │                                  │
│                  ┌────────▼────────┐                         │
│                  │    Composite    │                         │
│                  │   Components    │                         │
│                  └────────┬────────┘                         │
│                           │                                  │
│                  ┌────────▼────────┐                         │
│                  │ freya.taglib.xml│                         │
│                  └─────────────────┘                         │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    PrimeFaces Core                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  p:inputText │  │p:selectOneMenu│ │   p:dialog   │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│         └─────────────────┴──────────────────┘               │
│                           │                                  │
│                  ┌────────▼────────┐                         │
│                  │   PrimeFaces    │                         │
│                  │   Components    │                         │
│                  └────────┬────────┘                         │
└─────────────────────────┬─┴─────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    Jakarta Faces                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Facelets   │─>│ JSF Lifecycle│─>│  Rendering   │      │
│  └──────────────┘  └──────────────┘  └──────┬───────┘      │
└─────────────────────────────────────────────┼───────────────┘
                                              │
                          ┌───────────────────┘
                          │
          ┌───────────────┴───────────────┐
          │                               │
          ▼                               ▼
┌──────────────────┐            ┌──────────────────┐
│   Freya Theme    │            │   HTML/CSS/JS    │
│ ┌──────────────┐ │            │                  │
│ │layout-*.css  │ │            │  Final Output    │
│ │primeicons.css│ │────────────>│  to Browser      │
│ │primeflex.css │ │            │                  │
│ └──────────────┘ │            └──────────────────┘
└──────────────────┘

🔧 Composants

Structure d'un composant composite

Chaque composant Freya Extension suit cette structure :

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns:composite="http://xmlns.jcp.org/jsf/composite"
      xmlns:p="http://primefaces.org/ui">

    <!-- 1. Interface : Définition des attributs -->
    <composite:interface>
        <composite:attribute name="label" required="true" />
        <composite:attribute name="value" required="true" />
        <composite:attribute name="required" default="false" />
    </composite:interface>

    <!-- 2. Implémentation : Structure HTML + Composant PrimeFaces -->
    <composite:implementation>
        <div class="field">
            <p:outputLabel value="#{cc.attrs.label}">
                <span class="p-error" rendered="#{cc.attrs.required}"> *</span>
            </p:outputLabel>
            
            <p:inputText value="#{cc.attrs.value}" 
                         required="#{cc.attrs.required}" />
            
            <p:message for="..." />
        </div>
    </composite:implementation>
</html>

Catégories de composants

Catégorie Nombre Exemples
Formulaires 18 fieldInput, fieldSelect, fieldCalendar
Données 4 dataTable, dataView, tree, treeTable
Navigation 3 breadcrumb, steps, tabView
Actions 4 button, commandButton, linkButton
Feedback 3 message, growl, inplace
Utilitaires 6 avatar, badge, tag, progressBar
Layout 2 card, panel
Dialogs 2 actionDialog, formDialog
Avancés 3 tree, fieldEditor, chart
Thème 1 themeSelector

📁 Structure du projet

primefaces-freya-extension/
├── runtime/                              # Module principal
│   ├── pom.xml                          # Dépendances runtime
│   └── src/main/resources/
│       └── META-INF/
│           ├── freya.taglib.xml         # Déclaration des 46 composants
│           └── resources/
│               └── freya/               # Composants composites (.xhtml)
│                   ├── fieldInput.xhtml
│                   ├── fieldSelect.xhtml
│                   ├── actionDialog.xhtml
│                   └── ... (43 autres)
│
├── integration-tests/                    # Tests et démonstration
│   ├── pom.xml                          # Dépendances de test
│   └── src/main/
│       ├── java/
│       │   └── dev/lions/freya/demo/
│       │       └── DemoBean.java        # Bean de démonstration
│       └── resources/
│           ├── application.properties   # Configuration Quarkus
│           └── META-INF/resources/
│               ├── index.xhtml          # Page d'accueil
│               └── components-demo.xhtml # Démo complète
│
├── README.md                            # Documentation principale
├── QUICKSTART.md                        # Guide de démarrage rapide
├── CONTRIBUTING.md                      # Guide de contribution
├── ACCESSIBILITY.md                     # Guide d'accessibilité
├── DEPLOYMENT.md                        # Guide de déploiement
├── CHANGELOG.md                         # Historique des versions
├── LICENSE                              # Licence Apache 2.0
└── pom.xml                             # Configuration Maven parent

🔄 Flux de données

1. Rendu d'un composant

User Request
    │
    ▼
XHTML Page (fr:fieldInput)
    │
    ▼
freya.taglib.xml (résolution du composant)
    │
    ▼
fieldInput.xhtml (composite component)
    │
    ▼
PrimeFaces p:inputText
    │
    ▼
Jakarta Faces Lifecycle
    │
    ▼
HTML Output + Freya CSS
    │
    ▼
Browser

2. Soumission d'un formulaire

User Submit
    │
    ▼
AJAX Request (PrimeFaces)
    │
    ▼
Jakarta Faces Lifecycle
    │
    ├─> Apply Request Values
    ├─> Process Validations
    ├─> Update Model Values
    ├─> Invoke Application (Bean method)
    └─> Render Response
    │
    ▼
AJAX Response (partial update)
    │
    ▼
Browser (DOM update)

🎨 Intégration avec Freya Theme

Ressources Freya

<h:outputStylesheet name="freya-layout/css/primeicons.css" />
<h:outputStylesheet name="freya-layout/css/primeflex.min.css" />
<h:outputStylesheet name="freya-layout/css/layout-light.css" />

Pattern Freya

Tous les composants fr:field* appliquent automatiquement :

<div class="field">
    <label>...</label>
    <input>...</input>
    <span class="p-message">...</span>
</div>

🚀 Technologies utilisées

Technologie Version Rôle
Java 17+ Langage de programmation
Quarkus 3.15+ Framework d'application
Jakarta Faces 4.0 Framework web MVC
PrimeFaces 14.0.0 Bibliothèque de composants UI
Freya Theme 5.0.0 Thème CSS moderne
PrimeFlex 3.3.1 Système de grille CSS
Maven 3.8+ Gestion de build

📝 Principes de conception

  1. Simplicité - Réduire le boilerplate de 80%
  2. Cohérence - Pattern uniforme pour tous les composants
  3. Compatibilité - 100% compatible avec PrimeFaces standard
  4. Maintenabilité - Un seul endroit pour modifier le pattern
  5. Accessibilité - Support WCAG 2.1 niveau AA
  6. Performance - Pas de surcharge, juste du wrapping

🔗 Dépendances

Runtime

  • io.quarkus:quarkus-myfaces - Jakarta Faces pour Quarkus
  • org.primefaces:primefaces:14.0.0:jakarta - PrimeFaces
  • org.primefaces:freya:5.0.0 - Thème Freya

Build

  • maven-compiler-plugin - Compilation Java
  • maven-resources-plugin - Copie des ressources
  • quarkus-maven-plugin - Build Quarkus

📚 Ressources