geo/app/lib/presentation/widgets/docs/amicale_widgets_documentation.md

Documentation des Widgets Amicale

Cette documentation explique comment utiliser les widgets AmicaleRowWidget et AmicaleTableWidget pour afficher et gérer les données des amicales dans l'application.

AmicaleRowWidget

Le widget AmicaleRowWidget représente une ligne dans un tableau d'amicales. Il affiche les informations d'une amicale avec les colonnes suivantes :

• ID
• Nom
• Code Postal
• Région
• Actions (boutons selon les droits de l'utilisateur)

Propriétés

Propriété	Type	Description
amicale	AmicaleModel	Obligatoire. L'objet amicale à afficher.
onEdit	VoidCallback?	Fonction appelée lorsque l'utilisateur clique sur le bouton d'édition.
onDelete	VoidCallback?	Fonction appelée lorsque l'utilisateur clique sur le bouton de suppression.
isAlternate	bool	Indique si la ligne doit avoir une couleur de fond alternée. Par défaut à false.

Gestion des droits d'accès

Le widget gère automatiquement l'affichage des boutons d'action en fonction du rôle de l'utilisateur :

• Le bouton d'édition (crayon) est visible pour tous les utilisateurs avec un rôle > 1
• Le bouton de suppression (corbeille) est visible uniquement pour les utilisateurs avec un rôle > 2

Exemple d'utilisation

AmicaleRowWidget(
  amicale: amicale,
  isAlternate: index % 2 == 1, // Alterner les couleurs
  onEdit: () {
    // Code pour gérer l'édition
  },
  onDelete: () {
    // Code pour gérer la suppression
  },
)

AmicaleTableWidget

Le widget AmicaleTableWidget affiche un tableau complet d'amicales avec un en-tête et des lignes. Il utilise le widget AmicaleRowWidget pour afficher chaque ligne.

Propriétés

Propriété	Type	Description
amicales	List<AmicaleModel>	Obligatoire. La liste des amicales à afficher.
onEdit	Function(AmicaleModel)?	Fonction appelée lorsque l'utilisateur clique sur le bouton d'édition d'une amicale.
onDelete	Function(AmicaleModel)?	Fonction appelée lorsque l'utilisateur clique sur le bouton de suppression d'une amicale.
isLoading	bool	Indique si les données sont en cours de chargement. Affiche un indicateur de chargement si true. Par défaut à false.
emptyMessage	String?	Message à afficher lorsque la liste des amicales est vide.

États du tableau

Le widget gère automatiquement différents états :

1. Chargement : Affiche un indicateur de chargement circulaire lorsque isLoading est true.
2. Liste vide : Affiche un message lorsque la liste des amicales est vide.
3. Affichage normal : Affiche la liste des amicales avec des lignes alternées.

Exemple d'utilisation

AmicaleTableWidget(
  amicales: _amicales,
  isLoading: _isLoading,
  onEdit: (amicale) {
    // Code pour gérer l'édition de l'amicale
  },
  onDelete: (amicale) {
    // Code pour gérer la suppression de l'amicale
  },
  emptyMessage: 'Aucune amicale trouvée. Veuillez en créer une nouvelle.',
)

Intégration avec AmicaleRepository

Pour utiliser ces widgets avec le repository des amicales, vous devez :

1. Récupérer les amicales depuis le repository :

final amicaleRepository = Provider.of<AmicaleRepository>(context, listen: false);
final amicales = amicaleRepository.getAllAmicales();

2. Gérer les actions d'édition et de suppression :

void _handleEdit(AmicaleModel amicale) {
  // Naviguer vers la page d'édition ou afficher une boîte de dialogue
}

Future<void> _handleDelete(AmicaleModel amicale) async {
  // Afficher une confirmation puis supprimer
  final amicaleRepository = Provider.of<AmicaleRepository>(context, listen: false);
  await amicaleRepository.deleteAmicale(amicale.id);

  // Recharger la liste
  setState(() {
    _amicales = amicaleRepository.getAllAmicales();
  });
}

Exemple complet

Un exemple complet d'utilisation est disponible dans le fichier app/lib/presentation/widgets/examples/amicale_table_example.dart.

Personnalisation

Styles

Les widgets utilisent les styles du thème de l'application pour la cohérence visuelle. Vous pouvez personnaliser l'apparence en modifiant le thème ou en surchargeant les styles dans votre implémentation.

Colonnes et flexibilité

Les colonnes du tableau ont des valeurs de flex prédéfinies pour une mise en page optimale :

• ID : flex 1
• Nom : flex 4
• Code Postal : flex 2
• Région : flex 3
• Actions : flex 2

Vous pouvez ajuster ces valeurs en modifiant le code source si nécessaire.

Bonnes pratiques

1. Gestion des erreurs : Ajoutez toujours une gestion des erreurs lors de l'interaction avec le repository.
2. Confirmation des actions : Demandez toujours une confirmation avant de supprimer une amicale.
3. Actualisation des données : Prévoyez un moyen de rafraîchir les données (bouton ou pull-to-refresh).
4. Pagination : Pour les grandes listes, envisagez d'implémenter une pagination.