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

Documentation du Widget EntiteForm

Cette documentation décrit le widget EntiteForm créé pour la création et la modification des entités (amicales) dans l'application GeoSector.

Description

Le widget EntiteForm est un formulaire complet permettant de créer ou modifier une entité (amicale). Il gère l'affichage de tous les champs nécessaires, la validation des données et les restrictions d'accès basées sur le rôle de l'utilisateur.

Propriétés

• amicale (AmicaleModel?, optionnel) : Le modèle d'amicale à modifier. Si null, le formulaire sera en mode création.
• onSubmit (Function(AmicaleModel)?, optionnel) : Callback appelé lorsque le formulaire est soumis avec succès.
• readOnly (bool, défaut: false) : Si true, tous les champs du formulaire seront en lecture seule.

Champs du formulaire

Le formulaire inclut les champs suivants :

Informations générales

• Nom : Nom de l'amicale (obligatoire)

Adresse

• Adresse ligne 1 : Première ligne d'adresse
• Adresse ligne 2 : Seconde ligne d'adresse (optionnelle)
• Code Postal : Code postal (validation pour 5 chiffres)
• Ville : Nom de la ville
• Région : Sélection de la région via un dropdown

Contact

• Téléphone fixe : Numéro de téléphone fixe (validation pour 10 chiffres)
• Téléphone mobile : Numéro de téléphone mobile (validation pour 10 chiffres)
• Email : Adresse email (obligatoire, avec validation de format)

Informations avancées (visibles uniquement pour les administrateurs ou si déjà remplies)

• GPS Latitude : Coordonnée GPS latitude
• GPS Longitude : Coordonnée GPS longitude
• Stripe ID : Identifiant Stripe pour les paiements

Options

• Mode démo : Indique si l'amicale est en mode démo
• Copie des mails reçus : Indique si l'amicale reçoit une copie des emails
• Accepte les SMS : Indique si l'amicale accepte les SMS
• Actif : Indique si l'amicale est active

Restrictions d'accès

Certains champs sont soumis à des restrictions d'accès basées sur le rôle de l'utilisateur :

• Les champs suivants sont en lecture seule pour les utilisateurs avec un rôle ≤ 2 :
  • fkRegion/libRegion
  • gpsLat
  • gpsLng
  • stripeId
  • chkDemo
  • chkActive

Exemple d'utilisation

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

Utilisation simple

// Création d'une nouvelle amicale
EntiteForm(
  onSubmit: (amicale) {
    // Gérer la soumission
    print('Nouvelle amicale: ${amicale.name}');
  },
)

// Modification d'une amicale existante
EntiteForm(
  amicale: amicaleExistante,
  onSubmit: (amicale) {
    // Gérer la soumission
    print('Amicale modifiée: ${amicale.name}');
  },
)

// Affichage en lecture seule
EntiteForm(
  amicale: amicaleExistante,
  readOnly: true,
)

Utilisation avec gestion d'état

class _MyWidgetState extends State<MyWidget> {
  AmicaleModel? _amicale;
  bool _isLoading = true;

  @override
  void initState() {
    super.initState();
    _loadAmicale();
  }

  Future<void> _loadAmicale() async {
    setState(() {
      _isLoading = true;
    });

    try {
      if (widget.amicaleId != null) {
        // Récupérer l'amicale depuis le repository
        final amicaleRepository = Provider.of<AmicaleRepository>(context, listen: false);
        final amicale = amicaleRepository.getAmicaleById(widget.amicaleId!);

        setState(() {
          _amicale = amicale;
          _isLoading = false;
        });
      } else {
        // Création d'une nouvelle amicale
        setState(() {
          _amicale = null;
          _isLoading = false;
        });
      }
    } catch (e) {
      debugPrint('Erreur lors du chargement de l\'amicale: $e');
      setState(() {
        _isLoading = false;
      });
    }
  }

  void _handleSubmit(AmicaleModel amicale) async {
    try {
      final amicaleRepository = Provider.of<AmicaleRepository>(context, listen: false);

      // Sauvegarder l'amicale
      final savedAmicale = await amicaleRepository.saveAmicale(amicale);

      // Afficher un message de confirmation
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(
          content: Text('Amicale ${savedAmicale.name} sauvegardée avec succès'),
          backgroundColor: Colors.green,
        ),
      );
    } catch (e) {
      debugPrint('Erreur lors de la sauvegarde de l\'amicale: $e');
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(
          content: Text('Erreur lors de la sauvegarde: $e'),
          backgroundColor: Colors.red,
        ),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return _isLoading
      ? const Center(child: CircularProgressIndicator())
      : EntiteForm(
          amicale: _amicale,
          onSubmit: _handleSubmit,
        );
  }
}

Intégration avec le système de rôles

Le widget utilise le UserRepository pour déterminer le rôle de l'utilisateur actuel et appliquer les restrictions d'accès en conséquence. Assurez-vous que le UserRepository est disponible dans l'arbre des widgets via un Provider.

// Dans le widget parent
return MultiProvider(
  providers: [
    Provider<UserRepository>(
      create: (context) => userRepository,
    ),
    Provider<AmicaleRepository>(
      create: (context) => amicaleRepository,
    ),
  ],
  child: MyWidget(),
);

Personnalisation

Le widget utilise le thème de l'application pour le style. Vous pouvez personnaliser l'apparence en modifiant le thème ou en étendant le widget pour créer votre propre version personnalisée.

Validation des données

Le formulaire inclut une validation pour les champs suivants :

• Nom : Ne peut pas être vide
• Code Postal : Doit contenir 5 chiffres s'il est rempli
• Téléphone fixe : Doit contenir 10 chiffres s'il est rempli
• Téléphone mobile : Doit contenir 10 chiffres s'il est rempli
• Email : Ne peut pas être vide et doit contenir un '@' et un '.'