400 lines
12 KiB
Markdown
400 lines
12 KiB
Markdown
# 📦 Composants Réutilisables - Lions User Manager
|
|
|
|
**Version**: 1.0.0
|
|
**Date**: 2025-01-29
|
|
**Pattern**: WOU/DRY (Write Once Use / Don't Repeat Yourself)
|
|
|
|
---
|
|
|
|
## 🎯 Vue d'Ensemble
|
|
|
|
Ce répertoire contient tous les composants UI réutilisables pour le module **lions-user-manager**. Ces composants suivent les patterns établis dans **unionflow** et peuvent être utilisés dans n'importe quel projet de l'écosystème **lionsdev**.
|
|
|
|
---
|
|
|
|
## 📂 Structure des Composants
|
|
|
|
```
|
|
templates/components/
|
|
├── user-management/ # Composants spécifiques utilisateurs
|
|
│ ├── user-card.xhtml
|
|
│ ├── user-form.xhtml
|
|
│ ├── user-search-bar.xhtml
|
|
│ ├── user-actions.xhtml
|
|
│ └── user-role-badge.xhtml
|
|
├── role-management/ # Composants spécifiques rôles
|
|
│ ├── role-card.xhtml
|
|
│ ├── role-form.xhtml
|
|
│ └── role-assignment.xhtml
|
|
├── audit/ # Composants audit
|
|
│ ├── audit-log-row.xhtml
|
|
│ └── audit-stats-card.xhtml
|
|
└── shared/ # Composants génériques réutilisables
|
|
├── buttons/
|
|
│ └── button-user-action.xhtml
|
|
├── cards/
|
|
│ └── user-stat-card.xhtml
|
|
├── forms/
|
|
│ └── user-form-field.xhtml
|
|
└── tables/
|
|
└── user-data-table.xhtml
|
|
```
|
|
|
|
---
|
|
|
|
## 📋 Liste Complète des Composants
|
|
|
|
### 👤 User Management (5 composants)
|
|
|
|
#### 1. `user-card.xhtml`
|
|
**Description**: Carte utilisateur avec informations principales et actions
|
|
|
|
**Paramètres principaux**:
|
|
- `user`: UserDTO (requis)
|
|
- `showActions`: Boolean (défaut: true)
|
|
- `showRoles`: Boolean (défaut: true)
|
|
- `clickable`: Boolean (défaut: true)
|
|
- `outcome`: String (optionnel)
|
|
|
|
**Exemple**:
|
|
```xhtml
|
|
<ui:include src="/templates/components/user-management/user-card.xhtml">
|
|
<ui:param name="user" value="#{userBean.selectedUser}" />
|
|
<ui:param name="showActions" value="true" />
|
|
</ui:include>
|
|
```
|
|
|
|
#### 2. `user-form.xhtml`
|
|
**Description**: Formulaire complet pour créer/modifier un utilisateur
|
|
|
|
**Paramètres principaux**:
|
|
- `user`: UserDTO (requis)
|
|
- `mode`: String (défaut: "create") - "create" ou "edit"
|
|
- `showRealmSelector`: Boolean (défaut: false)
|
|
- `showPasswordFields`: Boolean (défaut: true)
|
|
- `readonly`: Boolean (défaut: false)
|
|
|
|
**Exemple**:
|
|
```xhtml
|
|
<ui:include src="/templates/components/user-management/user-form.xhtml">
|
|
<ui:param name="user" value="#{userBean.newUser}" />
|
|
<ui:param name="mode" value="create" />
|
|
<ui:param name="submitAction" value="#{userBean.createUser}" />
|
|
</ui:include>
|
|
```
|
|
|
|
#### 3. `user-search-bar.xhtml`
|
|
**Description**: Barre de recherche avancée pour utilisateurs
|
|
|
|
**Paramètres principaux**:
|
|
- `searchCriteria`: UserSearchCriteriaDTO (requis)
|
|
- `searchAction`: String (requis)
|
|
- `showAdvanced`: Boolean (défaut: false)
|
|
- `showRealmFilter`: Boolean (défaut: true)
|
|
- `showStatusFilter`: Boolean (défaut: true)
|
|
|
|
**Exemple**:
|
|
```xhtml
|
|
<ui:include src="/templates/components/user-management/user-search-bar.xhtml">
|
|
<ui:param name="searchCriteria" value="#{userBean.searchCriteria}" />
|
|
<ui:param name="searchAction" value="#{userBean.search}" />
|
|
<ui:param name="update" value="userTable" />
|
|
</ui:include>
|
|
```
|
|
|
|
#### 4. `user-actions.xhtml`
|
|
**Description**: Boutons d'action pour un utilisateur
|
|
|
|
**Paramètres principaux**:
|
|
- `user`: UserDTO (requis)
|
|
- `showView`: Boolean (défaut: true)
|
|
- `showEdit`: Boolean (défaut: true)
|
|
- `showDelete`: Boolean (défaut: true)
|
|
- `showActivate`: Boolean (défaut: true)
|
|
- `layout`: String (défaut: "horizontal") - "horizontal", "vertical" ou "dropdown"
|
|
|
|
**Exemple**:
|
|
```xhtml
|
|
<ui:include src="/templates/components/user-management/user-actions.xhtml">
|
|
<ui:param name="user" value="#{user}" />
|
|
<ui:param name="layout" value="dropdown" />
|
|
<ui:param name="update" value="userTable" />
|
|
</ui:include>
|
|
```
|
|
|
|
#### 5. `user-role-badge.xhtml`
|
|
**Description**: Badge pour un rôle utilisateur
|
|
|
|
**Paramètres principaux**:
|
|
- `roleName`: String (requis)
|
|
- `roleType`: String (optionnel) - "REALM_ROLE", "CLIENT_ROLE", "COMPOSITE_ROLE"
|
|
- `severity`: String (optionnel) - "success", "info", "warning", "danger"
|
|
- `clickable`: Boolean (défaut: false)
|
|
|
|
**Exemple**:
|
|
```xhtml
|
|
<ui:include src="/templates/components/user-management/user-role-badge.xhtml">
|
|
<ui:param name="roleName" value="ADMIN" />
|
|
<ui:param name="roleType" value="REALM_ROLE" />
|
|
</ui:include>
|
|
```
|
|
|
|
---
|
|
|
|
### 🛡️ Role Management (3 composants)
|
|
|
|
#### 6. `role-card.xhtml`
|
|
**Description**: Carte rôle avec informations principales
|
|
|
|
**Paramètres principaux**:
|
|
- `role`: RoleDTO (requis)
|
|
- `showActions`: Boolean (défaut: true)
|
|
- `showDescription`: Boolean (défaut: true)
|
|
- `showCompositeInfo`: Boolean (défaut: true)
|
|
|
|
**Exemple**:
|
|
```xhtml
|
|
<ui:include src="/templates/components/role-management/role-card.xhtml">
|
|
<ui:param name="role" value="#{roleBean.selectedRole}" />
|
|
</ui:include>
|
|
```
|
|
|
|
#### 7. `role-form.xhtml`
|
|
**Description**: Formulaire pour créer/modifier un rôle
|
|
|
|
**Paramètres principaux**:
|
|
- `role`: RoleDTO (requis)
|
|
- `mode`: String (défaut: "create")
|
|
- `showRealmSelector`: Boolean (défaut: true)
|
|
- `showClientSelector`: Boolean (défaut: false)
|
|
- `showCompositeOptions`: Boolean (défaut: true)
|
|
|
|
**Exemple**:
|
|
```xhtml
|
|
<ui:include src="/templates/components/role-management/role-form.xhtml">
|
|
<ui:param name="role" value="#{roleBean.newRole}" />
|
|
<ui:param name="mode" value="create" />
|
|
<ui:param name="submitAction" value="#{roleBean.createRole}" />
|
|
</ui:include>
|
|
```
|
|
|
|
#### 8. `role-assignment.xhtml`
|
|
**Description**: Interface pour attribuer/révoquer des rôles
|
|
|
|
**Paramètres principaux**:
|
|
- `user`: UserDTO (requis)
|
|
- `availableRoles`: List<RoleDTO> (requis)
|
|
- `userRoles`: List<RoleDTO> (requis)
|
|
- `assignAction`: String (requis)
|
|
- `revokeAction`: String (requis)
|
|
|
|
**Exemple**:
|
|
```xhtml
|
|
<ui:include src="/templates/components/role-management/role-assignment.xhtml">
|
|
<ui:param name="user" value="#{userBean.selectedUser}" />
|
|
<ui:param name="availableRoles" value="#{roleBean.availableRoles}" />
|
|
<ui:param name="userRoles" value="#{userBean.userRoles}" />
|
|
<ui:param name="assignAction" value="#{roleBean.assignRole}" />
|
|
<ui:param name="revokeAction" value="#{roleBean.revokeRole}" />
|
|
</ui:include>
|
|
```
|
|
|
|
---
|
|
|
|
### 📊 Audit (2 composants)
|
|
|
|
#### 9. `audit-log-row.xhtml`
|
|
**Description**: Ligne de log d'audit avec informations détaillées
|
|
|
|
**Paramètres principaux**:
|
|
- `auditLog`: AuditLogDTO (requis)
|
|
- `showDetails`: Boolean (défaut: false)
|
|
- `showActions`: Boolean (défaut: false)
|
|
- `compact`: Boolean (défaut: false)
|
|
|
|
**Exemple**:
|
|
```xhtml
|
|
<ui:include src="/templates/components/audit/audit-log-row.xhtml">
|
|
<ui:param name="auditLog" value="#{log}" />
|
|
<ui:param name="showDetails" value="true" />
|
|
</ui:include>
|
|
```
|
|
|
|
#### 10. `audit-stats-card.xhtml`
|
|
**Description**: Carte statistiques d'audit
|
|
|
|
**Paramètres principaux**:
|
|
- `title`: String (requis)
|
|
- `value`: Number (requis)
|
|
- `icon`: String (requis)
|
|
- `iconColor`: String (requis)
|
|
- `trend`: Number (optionnel)
|
|
- `trendLabel`: String (optionnel)
|
|
|
|
**Exemple**:
|
|
```xhtml
|
|
<ui:include src="/templates/components/audit/audit-stats-card.xhtml">
|
|
<ui:param name="title" value="Total Actions" />
|
|
<ui:param name="value" value="#{auditBean.totalActions}" />
|
|
<ui:param name="icon" value="pi-history" />
|
|
<ui:param name="iconColor" value="blue-600" />
|
|
</ui:include>
|
|
```
|
|
|
|
---
|
|
|
|
### 🔧 Shared Components (4 composants)
|
|
|
|
#### 11. `button-user-action.xhtml`
|
|
**Description**: Bouton générique pour actions utilisateur
|
|
|
|
**Paramètres principaux**:
|
|
- `value`: String (requis)
|
|
- `icon`: String (optionnel)
|
|
- `action`: String (optionnel)
|
|
- `outcome`: String (optionnel)
|
|
- `severity`: String (défaut: "primary")
|
|
- `size`: String (défaut: "normal")
|
|
|
|
**Exemple**:
|
|
```xhtml
|
|
<ui:include src="/templates/components/shared/buttons/button-user-action.xhtml">
|
|
<ui:param name="value" value="Créer Utilisateur" />
|
|
<ui:param name="icon" value="pi-user-plus" />
|
|
<ui:param name="action" value="#{userBean.createUser}" />
|
|
</ui:include>
|
|
```
|
|
|
|
#### 12. `user-stat-card.xhtml`
|
|
**Description**: Carte statistique utilisateur
|
|
|
|
**Paramètres principaux**:
|
|
- `title`: String (requis)
|
|
- `value`: String/Number (requis)
|
|
- `icon`: String (requis)
|
|
- `iconColor`: String (requis)
|
|
- `trend`: Number (optionnel)
|
|
- `clickable`: Boolean (défaut: false)
|
|
|
|
**Exemple**:
|
|
```xhtml
|
|
<ui:include src="/templates/components/shared/cards/user-stat-card.xhtml">
|
|
<ui:param name="title" value="Total Utilisateurs" />
|
|
<ui:param name="value" value="#{userBean.totalUsers}" />
|
|
<ui:param name="icon" value="pi-users" />
|
|
<ui:param name="iconColor" value="blue-600" />
|
|
</ui:include>
|
|
```
|
|
|
|
#### 13. `user-form-field.xhtml`
|
|
**Description**: Champ de formulaire générique
|
|
|
|
**Paramètres principaux**:
|
|
- `id`: String (requis)
|
|
- `label`: String (requis)
|
|
- `value`: Object (requis)
|
|
- `type`: String (défaut: "text") - "text", "email", "password", "number", "textarea", "select", "checkbox", "calendar"
|
|
- `required`: Boolean (défaut: false)
|
|
- `readonly`: Boolean (défaut: false)
|
|
|
|
**Exemple**:
|
|
```xhtml
|
|
<ui:include src="/templates/components/shared/forms/user-form-field.xhtml">
|
|
<ui:param name="id" value="username" />
|
|
<ui:param name="label" value="Nom d'utilisateur" />
|
|
<ui:param name="value" value="#{user.username}" />
|
|
<ui:param name="required" value="true" />
|
|
</ui:include>
|
|
```
|
|
|
|
#### 14. `user-data-table.xhtml`
|
|
**Description**: Tableau de données pour utilisateurs
|
|
|
|
**Paramètres principaux**:
|
|
- `users`: List<UserDTO> (requis)
|
|
- `var`: String (défaut: "user")
|
|
- `paginator`: Boolean (défaut: true)
|
|
- `rows`: Number (défaut: 20)
|
|
- `showActions`: Boolean (défaut: true)
|
|
- `showRoles`: Boolean (défaut: true)
|
|
- `showSelection`: Boolean (défaut: false)
|
|
|
|
**Exemple**:
|
|
```xhtml
|
|
<ui:include src="/templates/components/shared/tables/user-data-table.xhtml">
|
|
<ui:param name="users" value="#{userBean.users}" />
|
|
<ui:param name="update" value="userTable" />
|
|
</ui:include>
|
|
```
|
|
|
|
---
|
|
|
|
## 🎨 Patterns et Conventions
|
|
|
|
### Documentation Inline
|
|
Chaque composant contient une documentation complète en commentaire avec:
|
|
- Description du composant
|
|
- Liste des paramètres avec types et valeurs par défaut
|
|
- Exemples d'utilisation
|
|
|
|
### Paramètres Optionnels
|
|
Tous les paramètres optionnels ont des valeurs par défaut définies avec `<c:set>`.
|
|
|
|
### Pattern WOU/DRY
|
|
- **Write Once Use**: Chaque composant est écrit une fois et réutilisé partout
|
|
- **Don't Repeat Yourself**: Pas de duplication de code
|
|
|
|
### Naming Convention
|
|
- Noms de fichiers en `kebab-case`
|
|
- Paramètres en `camelCase`
|
|
- IDs de composants avec préfixe cohérent
|
|
|
|
---
|
|
|
|
## 🚀 Utilisation dans d'Autres Projets
|
|
|
|
Ces composants peuvent être utilisés dans n'importe quel projet de l'écosystème **lionsdev** en ajoutant la dépendance Maven:
|
|
|
|
```xml
|
|
<dependency>
|
|
<groupId>dev.lions.user.manager</groupId>
|
|
<artifactId>lions-user-manager-client-quarkus-primefaces-freya</artifactId>
|
|
<version>1.0.0</version>
|
|
</dependency>
|
|
```
|
|
|
|
Puis inclure les composants dans vos pages XHTML:
|
|
|
|
```xhtml
|
|
<ui:include src="/templates/components/user-management/user-card.xhtml">
|
|
<ui:param name="user" value="#{userBean.selectedUser}" />
|
|
</ui:include>
|
|
```
|
|
|
|
---
|
|
|
|
## 📝 Notes Importantes
|
|
|
|
1. **Dépendances**: Tous les composants nécessitent PrimeFaces 14.0.5+ et Quarkus PrimeFaces 3.13.3+
|
|
2. **Thème**: Les composants utilisent le thème Freya (compatible avec unionflow)
|
|
3. **Validation**: Les composants de formulaire incluent la validation JSF
|
|
4. **Accessibilité**: Les composants suivent les bonnes pratiques d'accessibilité
|
|
|
|
---
|
|
|
|
## 🔄 Maintenance
|
|
|
|
Pour ajouter un nouveau composant:
|
|
|
|
1. Créer le fichier dans le répertoire approprié
|
|
2. Suivre le pattern de documentation inline
|
|
3. Ajouter des exemples d'utilisation
|
|
4. Mettre à jour ce README
|
|
|
|
---
|
|
|
|
**Dernière mise à jour**: 2025-01-29
|
|
**Version**: 1.0.0
|
|
**Auteur**: Lions User Manager Team
|
|
|