# Guide d'Utilisation - Freya avec PrimeFaces

**Version** : Freya 5.0.0 + PrimeFaces 14.0.0
**Date** : 2025-12-25
**Sources** : Documentation officielle Freya et exemples

---

## 🎯 Introduction

Ce guide montre comment utiliser les composants **PrimeFaces standards** avec le thème **Freya** dans vos applications Quarkus, basé sur les exemples officiels de Freya 5.0.0.

**Important** : Freya est un **thème CSS** pour PrimeFaces, pas une bibliothèque de composants. Vous utilisez les composants PrimeFaces standards (`p:inputText`, `p:dataTable`, etc.) avec les classes CSS de Freya.

---

## 📦 Installation

### 1. Dépendances Maven

```xml
<dependency>
    <groupId>dev.lions</groupId>
    <artifactId>primefaces-freya-extension</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>
```

Cette extension fournit :
- ✅ Thème Freya
- ✅ Templates de layout
- ✅ Composant `FreyaMenu`
- ✅ Bean `GuestPreferences`

### 2. Configuration

**application.properties** :
```properties
primefaces.THEME=freya
primefaces.FONT_AWESOME=true
primefaces.CLIENT_SIDE_VALIDATION=true
primefaces.MOVE_SCRIPTS_TO_BOTTOM=true
```

---

## 🎨 Classes CSS Freya

### Layout Classes (PrimeFlex)

Freya utilise **PrimeFlex** pour le layout :

```xml
<div class="grid">                    <!-- Grille responsive -->
    <div class="col-12 md:col-6">    <!-- Colonne : 12 cols mobile, 6 desktop -->
        <div class="card">            <!-- Carte Freya -->
            <!-- Contenu -->
        </div>
    </div>
</div>
```

**Classes principales** :
- `grid` - Conteneur grille
- `col-{n}` - Colonnes (1-12)
- `md:col-{n}`, `lg:col-{n}` - Breakpoints responsive
- `card` - Carte Freya avec ombre et border-radius
- `ui-fluid` - Inputs 100% width

### Form Classes

**Pattern Field** (recommandé) :
```xml
<div class="field">
    <p:outputLabel for="name" value="Nom" />
    <p:inputText id="name" value="#{bean.nom}" />
    <p:message for="name" />
</div>
```

**Grid Formgrid** :
```xml
<div class="grid formgrid">
    <div class="col-12 md:col-6">
        <div class="field">
            <p:outputLabel for="firstname" value="Prénom" />
            <p:inputText id="firstname" value="#{bean.prenom}" />
        </div>
    </div>
    <div class="col-12 md:col-6">
        <div class="field">
            <p:outputLabel for="lastname" value="Nom" />
            <p:inputText id="lastname" value="#{bean.nom}" />
        </div>
    </div>
</div>
```

**Float Label** :
```xml
<span class="ui-float-label">
    <p:inputText id="float-input" value="#{bean.username}" />
    <p:outputLabel for="@previous" value="Username" />
</span>
```

### Icons in Inputs

```xml
<span class="ui-input-icon-left">
    <i class="pi pi-user"></i>
    <p:inputText placeholder="Username" />
</span>

<span class="ui-input-icon-right">
    <p:inputText placeholder="Search" />
    <i class="pi pi-search"></i>
</span>
```

---

## 📝 Composants de Formulaire

### InputText

**Basique** :
```xml
<p:inputText value="#{bean.nom}" placeholder="Nom" />
```

**Avec field pattern** :
```xml
<div class="field">
    <p:outputLabel for="nom" value="Nom" />
    <p:inputText id="nom" value="#{bean.nom}" required="true" />
    <p:message for="nom" />
</div>
```

**Disabled / Erreur** :
```xml
<p:inputText value="#{bean.nom}" disabled="true" />
<p:inputText value="#{bean.nom}" styleClass="ui-state-error" />
```

### InputTextarea

```xml
<div class="field">
    <p:outputLabel for="description" value="Description" />
    <p:inputTextarea id="description"
                     value="#{bean.description}"
                     rows="5"
                     autoResize="false" />
</div>
```

### SelectOneMenu (Dropdown)

```xml
<div class="field">
    <p:outputLabel for="category" value="Catégorie" />
    <p:selectOneMenu id="category" value="#{bean.category}">
        <f:selectItem itemLabel="Sélectionnez..." itemValue="" />
        <f:selectItem itemLabel="Option 1" itemValue="1" />
        <f:selectItem itemLabel="Option 2" itemValue="2" />
    </p:selectOneMenu>
</div>
```

**Avec filtre** :
```xml
<p:selectOneMenu value="#{bean.category}" filter="true" filterMatchMode="contains">
    <f:selectItems value="#{bean.categories}" />
</p:selectOneMenu>
```

### Calendar (DatePicker)

```xml
<div class="field">
    <p:outputLabel for="date" value="Date" />
    <p:datePicker id="date" value="#{bean.date}" showIcon="true" />
</div>
```

### SelectManyCheckbox

```xml
<div class="field">
    <p:outputLabel value="Options" />
    <p:selectManyCheckbox value="#{bean.selectedOptions}" layout="responsive" columns="3">
        <f:selectItem itemLabel="Option 1" itemValue="1" />
        <f:selectItem itemLabel="Option 2" itemValue="2" />
        <f:selectItem itemLabel="Option 3" itemValue="3" />
    </p:selectManyCheckbox>
</div>
```

### SelectOneRadio

```xml
<div class="field">
    <p:outputLabel value="Catégorie" />
    <p:selectOneRadio value="#{bean.category}" layout="responsive" columns="2">
        <f:selectItem itemLabel="Accessories" itemValue="Accessories" />
        <f:selectItem itemLabel="Clothing" itemValue="Clothing" />
    </p:selectOneRadio>
</div>
```

---

## 📊 Composants de Données

### DataTable

**Basique** :
```xml
<p:dataTable value="#{bean.users}" var="user" paginator="true" rows="10">
    <p:column headerText="Nom">
        <h:outputText value="#{user.nom}" />
    </p:column>
    <p:column headerText="Email">
        <h:outputText value="#{user.email}" />
    </p:column>
</p:dataTable>
```

**Complet (Pattern Freya CRUD)** :
```xml
<h:form id="form">
    <p:growl id="messages" showDetail="true" />

    <!-- Toolbar -->
    <p:toolbar styleClass="mb-4">
        <p:toolbarGroup>
            <p:commandButton value="Nouveau"
                           icon="pi pi-plus"
                           actionListener="#{bean.openNew}"
                           update="dialog-content"
                           oncomplete="PF('dialog').show()"
                           styleClass="ui-button-success" />
            <p:commandButton value="Supprimer"
                           icon="pi pi-trash"
                           actionListener="#{bean.deleteSelected}"
                           styleClass="ui-button-danger"
                           disabled="#{!bean.hasSelected()}"
                           update="@this">
                <p:confirm header="Confirmation"
                          message="Supprimer les éléments sélectionnés ?"
                          icon="pi pi-exclamation-triangle" />
            </p:commandButton>
        </p:toolbarGroup>
        <p:toolbarGroup align="right">
            <p:fileUpload mode="simple" skinSimple="true" label="Import" />
            <p:commandButton value="Export" icon="pi pi-upload" ajax="false">
                <p:dataExporter type="pdf" target="dt" fileName="data"/>
            </p:commandButton>
        </p:toolbarGroup>
    </p:toolbar>

    <!-- DataTable -->
    <p:dataTable id="dt"
                 widgetVar="dtTable"
                 var="item"
                 value="#{bean.items}"
                 selection="#{bean.selectedItems}"
                 rowKey="#{item.id}"
                 paginator="true"
                 rows="10"
                 reflow="true">

        <f:facet name="header">
            <div class="products-table-header">
                <span style="font-weight: bold">Gestion des Données</span>
                <span class="filter-container ui-input-icon-left">
                    <i class="pi pi-search"></i>
                    <p:inputText id="globalFilter"
                               onkeyup="PF('dtTable').filter()"
                               placeholder="Rechercher" />
                </span>
            </div>
        </f:facet>

        <p:ajax event="rowSelect" update=":form:toolbar" />
        <p:ajax event="rowUnselect" update=":form:toolbar" />

        <p:column selectionMode="multiple" exportable="false" />

        <p:column headerText="Nom" sortBy="#{item.nom}" filterBy="#{item.nom}">
            <h:outputText value="#{item.nom}" />
        </p:column>

        <p:column exportable="false">
            <p:commandButton icon="pi pi-pencil"
                           update=":form:dialog-content"
                           oncomplete="PF('dialog').show()"
                           styleClass="edit-button rounded-button ui-button-success">
                <f:setPropertyActionListener value="#{item}" target="#{bean.selectedItem}" />
            </p:commandButton>
            <p:commandButton icon="pi pi-trash"
                           styleClass="ui-button-warning rounded-button"
                           oncomplete="PF('deleteDialog').show()">
                <f:setPropertyActionListener value="#{item}" target="#{bean.selectedItem}" />
            </p:commandButton>
        </p:column>
    </p:dataTable>
</h:form>
```

---

## 🗂️ Composants Panel

### Dialog

**Basique** :
```xml
<p:dialog header="Détails"
          widgetVar="dialog"
          modal="true"
          showEffect="fade"
          responsive="true">
    <p:outputPanel id="dialog-content">
        <!-- Contenu -->
    </p:outputPanel>
</p:dialog>
```

**Avec formulaire et footer** :
```xml
<p:dialog header="Éditer"
          widgetVar="editDialog"
          modal="true"
          responsive="true">
    <p:outputPanel id="edit-content" class="ui-fluid">
        <p:outputPanel rendered="#{not empty bean.selectedItem}">
            <div class="field">
                <p:outputLabel for="name" value="Nom" />
                <p:inputText id="name" value="#{bean.selectedItem.nom}" required="true" />
            </div>
            <div class="field">
                <p:outputLabel for="description" value="Description" />
                <p:inputTextarea id="description" value="#{bean.selectedItem.description}" />
            </div>
        </p:outputPanel>
    </p:outputPanel>

    <f:facet name="footer">
        <p:commandButton value="Annuler"
                       icon="pi pi-times"
                       onclick="PF('editDialog').hide()"
                       styleClass="ui-button-secondary" />
        <p:commandButton value="Sauvegarder"
                       icon="pi pi-check"
                       actionListener="#{bean.save}"
                       update="edit-content"
                       oncomplete="if(!args.validationFailed) PF('editDialog').hide()"
                       styleClass="ui-button-success" />
    </f:facet>
</p:dialog>
```

### Panel

```xml
<p:panel header="Titre du Panel" toggleable="true" collapsed="false">
    <p>Contenu du panel...</p>
</p:panel>
```

### AccordionPanel

```xml
<p:accordionPanel multiple="false">
    <p:tab title="Section 1">
        <p>Contenu de la section 1...</p>
    </p:tab>
    <p:tab title="Section 2">
        <p>Contenu de la section 2...</p>
    </p:tab>
</p:accordionPanel>
```

---

## 🔘 Composants Button

### CommandButton

**Basique** :
```xml
<p:commandButton value="Sauvegarder"
                action="#{bean.save}"
                update="form" />
```

**Avec icône** :
```xml
<p:commandButton value="Nouveau"
                icon="pi pi-plus"
                actionListener="#{bean.create}" />
```

**Avec styles Freya** :
```xml
<!-- Success -->
<p:commandButton value="Créer"
                icon="pi pi-check"
                styleClass="ui-button-success" />

<!-- Warning -->
<p:commandButton value="Attention"
                icon="pi pi-exclamation-triangle"
                styleClass="ui-button-warning" />

<!-- Danger -->
<p:commandButton value="Supprimer"
                icon="pi pi-trash"
                styleClass="ui-button-danger" />

<!-- Secondary -->
<p:commandButton value="Annuler"
                icon="pi pi-times"
                styleClass="ui-button-secondary" />

<!-- Rounded -->
<p:commandButton icon="pi pi-pencil"
                styleClass="rounded-button ui-button-success" />
```

**Groupe de boutons** :
```xml
<f:facet name="footer">
    <p:commandButton value="Annuler"
                   icon="pi pi-times"
                   styleClass="ui-button-secondary" />
    <p:commandButton value="Sauvegarder"
                   icon="pi pi-check"
                   styleClass="ui-button-success" />
</f:facet>
```

---

## 💬 Composants Message

### Message (pour un champ)

```xml
<div class="field">
    <p:outputLabel for="email" value="Email" />
    <p:inputText id="email" value="#{bean.email}" required="true" />
    <p:message for="email" />
</div>
```

### Messages (tous les messages)

```xml
<h:form>
    <p:messages id="messages" showDetail="true" closable="true" />
    <!-- Formulaire -->
</h:form>
```

### Growl (notifications toast)

```xml
<h:form>
    <p:growl id="growl" showDetail="true" />
    <p:commandButton value="Save"
                   action="#{bean.save}"
                   update="growl" />
</h:form>
```

**Dans le bean** :
```java
public void save() {
    // Logic...
    FacesContext.getCurrentInstance().addMessage(null,
        new FacesMessage(FacesMessage.SEVERITY_INFO,
                        "Succès",
                        "Données sauvegardées avec succès"));
}
```

---

## 📐 Patterns de Layout

### Page Complète avec Card

```xml
<ui:composition template="/WEB-INF/template.xhtml">
    <ui:define name="title">Ma Page</ui:define>

    <ui:define name="content">
        <div class="grid">
            <div class="col-12">
                <div class="card">
                    <h5>Titre</h5>
                    <p>Contenu...</p>
                </div>
            </div>
        </div>
    </ui:define>
</ui:composition>
```

### Deux Colonnes

```xml
<div class="grid">
    <div class="col-12 lg:col-6">
        <div class="card">
            <h5>Colonne Gauche</h5>
            <!-- Contenu -->
        </div>
    </div>
    <div class="col-12 lg:col-6">
        <div class="card">
            <h5>Colonne Droite</h5>
            <!-- Contenu -->
        </div>
    </div>
</div>
```

### Formulaire Complet

```xml
<div class="grid">
    <div class="col-12">
        <div class="card">
            <h:form id="userForm" class="ui-fluid">
                <h5>Nouvel Utilisateur</h5>

                <div class="grid formgrid">
                    <div class="col-12 md:col-6">
                        <div class="field">
                            <p:outputLabel for="firstname" value="Prénom" />
                            <p:inputText id="firstname" value="#{bean.user.firstname}" required="true" />
                            <p:message for="firstname" />
                        </div>
                    </div>
                    <div class="col-12 md:col-6">
                        <div class="field">
                            <p:outputLabel for="lastname" value="Nom" />
                            <p:inputText id="lastname" value="#{bean.user.lastname}" required="true" />
                            <p:message for="lastname" />
                        </div>
                    </div>
                </div>

                <div class="field">
                    <p:outputLabel for="email" value="Email" />
                    <p:inputText id="email" value="#{bean.user.email}" required="true" />
                    <p:message for="email" />
                </div>

                <div class="field">
                    <p:outputLabel for="role" value="Rôle" />
                    <p:selectOneMenu id="role" value="#{bean.user.role}">
                        <f:selectItem itemLabel="Sélectionnez..." itemValue="" />
                        <f:selectItems value="#{bean.roles}" />
                    </p:selectOneMenu>
                </div>

                <div class="field">
                    <p:commandButton value="Annuler"
                                   icon="pi pi-times"
                                   styleClass="ui-button-secondary"
                                   style="margin-right: .5rem" />
                    <p:commandButton value="Sauvegarder"
                                   icon="pi pi-check"
                                   action="#{bean.save}"
                                   update="userForm"
                                   styleClass="ui-button-success" />
                </div>
            </h:form>
        </div>
    </div>
</div>
```

---

## 🎨 Composant FreyaMenu

**Usage** :
```xml
<html xmlns:fr="http://primefaces.org/freya">

<fr:menu model="#{menuBean.model}" />
```

**Bean** :
```java
@Named
@SessionScoped
public class MenuBean implements Serializable {
    private MenuModel model;

    @PostConstruct
    public void init() {
        model = new DefaultMenuModel();

        DefaultMenuItem item1 = DefaultMenuItem.builder()
            .value("Dashboard")
            .icon("pi pi-home")
            .outcome("/dashboard.xhtml")
            .build();
        model.getElements().add(item1);

        DefaultSubMenu subMenu = DefaultSubMenu.builder()
            .label("Gestion")
            .icon("pi pi-cog")
            .build();

        DefaultMenuItem subItem = DefaultMenuItem.builder()
            .value("Utilisateurs")
            .outcome("/users/list.xhtml")
            .build();
        subMenu.getElements().add(subItem);

        model.getElements().add(subMenu);
    }

    public MenuModel getModel() {
        return model;
    }
}
```

---

## 📚 Ressources

### Documentation Officielle
- **PrimeFaces** : https://primefaces.github.io/primefaces/14_0_0/
- **PrimeFlex** : https://www.primefaces.org/primeflex/
- **PrimeIcons** : https://www.primefaces.org/primeicons/

### Exemples Sources Freya
- **Localisation** : `C:/Users/dadyo/PersonalProjects/lions-workspace/freya/tag/src/main/webapp/`
- Fichiers : `input.xhtml`, `crud.xhtml`, `formlayout.xhtml`, `button.xhtml`, etc.

---

## ✅ Bonnes Pratiques

1. **Utiliser les classes Freya** : `grid`, `card`, `field`, `formgrid`
2. **Pattern field cohérent** : Label + Input + Message
3. **ui-fluid pour formulaires** : Inputs 100% width
4. **Responsive design** : Utiliser `col-12 lg:col-6` etc.
5. **Icônes PrimeIcons** : `pi pi-*`
6. **Styles de boutons** : `ui-button-success`, `ui-button-danger`, etc.
7. **Messages appropriés** : `p:message` pour champs, `p:growl` pour notifications
8. **Dialog modal** : Toujours avec `modal="true"` et `responsive="true"`

---

**Version** : 1.0.0
**Dernière mise à jour** : 2025-12-25