Introduction

Gérez les soumissions de formulaires et récupérez les données des formulaires.

🎯 Que fait ce module ?

Le module FormData vous permet de soumettre des formulaires remplis par les utilisateurs (formulaires de contact, enquêtes, inscriptions) à OneEntry et de récupérer les données soumises pour analyse, reporting et gestion.

Considérez-le comme votre gestionnaire de soumissions de formulaires - les utilisateurs soumettent des formulaires, vous les stockez dans OneEntry, et vous les récupérez chaque fois que vous avez besoin de consulter des réponses, de générer des rapports ou d'analyser des données.

---

📖 Explication Simple

Imaginez que vous avez un formulaire de contact sur votre site web. Lorsque les utilisateurs le remplissent :

1. Soumettre - L'utilisateur clique sur "Envoyer" → Les données du formulaire vont à OneEntry
2. Stocker - OneEntry enregistre la soumission (nom, email, message)
3. Récupérer - Vous récupérez les soumissions pour les consulter, les exporter ou les analyser
4. Gérer - Filtrer, rechercher et organiser les réponses des formulaires

Flux de travail dans le monde réel :

L'utilisateur remplit le formulaire de contact → postFormsData() → Enregistré dans OneEntry
                                                              ↓
L'admin consulte les soumissions ← getFormsData() ← OneEntry renvoie les données

Ce que vous pouvez faire :

• 📤 Soumettre des formulaires - Envoyer des données remplies par l'utilisateur à OneEntry
• 📥 Consulter les soumissions - Obtenir toutes les réponses de formulaires avec pagination
• 🔍 Rechercher des soumissions - Trouver des soumissions spécifiques par marqueur ou filtre
• 📊 Exporter des données - Récupérer des soumissions pour des rapports et analyses
• 📧 Gérer les réponses - Suivre les soumissions de formulaires en un seul endroit

Scénarios d'exemple :

Scénario	Ce qui se passe
Formulaire de Contact	L'utilisateur soumet → Vous recevez une notification par email → Voir dans le tableau de bord
Enquête	Collecter des réponses → Exporter au format CSV → Analyser les résultats
Inscription	L'utilisateur s'inscrit → Données stockées → Envoyer un email de confirmation
Retour d'information	Le client laisse un retour → L'équipe examine → Répondre au client

---

✨ Concepts Clés

Qu'est-ce que les Données de Formulaire ?

Les données de formulaire sont les informations que les utilisateurs soumettent via des formulaires.

Structure de Soumission de Formulaire

Chaque soumission dans OneEntry a :

  const body: IBodyPostFormData = {
    formIdentifier: 'contact_form', // Marqueur de formulaire
    formModuleConfigId: 9,          // ID de configuration du module
    moduleEntityIdentifier: 'blog', // Identifiant d'entité du module
    replayTo: null,                 // Adresse email à laquelle répondre
    status: 'sent',                 // Statut de la soumission
    formData: [                     // Champs du formulaire
      {
        marker: 'string',           // Marqueur de champ
        type: 'string',             // Type de champ
        value: 'Test',              // Valeur de champ
      },
      {
        marker: 'number',
        type: 'integer',
        value: 1,
      },
    ]
  };

Cycle de Vie des Données de Formulaire

1. L'utilisateur remplit le formulaire dans le navigateur
   ↓
2. Le frontend valide l'entrée
   ↓
3. postFormsData() envoie à OneEntry
   ↓
4. OneEntry valide et stocke la soumission
   ↓
5. Notifications envoyées (email, webhook)
   ↓
6. L'admin récupère avec getFormsData()
   ↓
7. Examiner, exporter ou répondre

Cas d'Utilisation Courants

Cas d'Utilisation	Description	Exemple
Formulaires de Contact	Les clients contactent avec des questions	L'équipe de support examine et répond
Génération de Leads	Collecter des informations sur des clients potentiels	L'équipe de vente fait un suivi
Enquêtes	Recueillir des retours et des opinions	Le marketing analyse les résultats
Inscriptions	S'inscrire à des événements, des newsletters	Suivre les participants/abonnés
Candidatures	Collecter des CV et des lettres de motivation	Les RH examinent les candidats
Formulaires de Retour	Satisfaction et avis des clients	Améliorer les produits/services

---

📋 Ce que Vous Devez Savoir

La Soumission de Formulaires Nécessite une Configuration

Avant de soumettre, vous avez besoin de :

1. Marqueur de formulaire - Identifiant unique du formulaire
2. ID de configuration du module de formulaire - À partir des paramètres du formulaire
3. Identifiant d'entité du module - À partir de la configuration du formulaire

Comment obtenir ces éléments :

// Récupérer le formulaire
const form = await Forms.getFormByMarker('contact_form');

// Extraire les ID requis
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// Maintenant vous pouvez soumettre

Pourquoi est-ce nécessaire ? OneEntry a besoin de savoir :

• Quel modèle de formulaire utiliser
• Où stocker les données
• Quelles règles de validation appliquer

Structure des Données de Formulaire

Le tableau formData contient des objets de champ :

formData: [
  {
    marker: "field_name",     // Identifiant de champ
    type: "text"              // Type de champ
    value: "user_input",      // Entrée de l'utilisateur
  }
]

Important :

• marker doit correspondre aux marqueurs de champ de la définition du formulaire
• type utile pour la validation
• value contient l'entrée de l'utilisateur

Statut de Soumission

Utilisez status pour suivre l'état de la soumission :

Statut	Signification	Quand l'utiliser
"sent"	Soumis avec succès	Par défaut pour les nouvelles soumissions
"pending"	En attente de révision	Modération requise
"processed"	Traité par l'admin	Marqué comme examiné
"archived"	Soumission ancienne/fermée	Conserver pour archives

Pagination

Récupérez les soumissions par lots.

Marqueur de Formulaire

Une façon d'identifier les soumissions :

Identifiant	Ce que c'est	Quand l'utiliser
Marqueur de Formulaire	Identifiant du modèle de formulaire	Obtenir toutes les soumissions pour un formulaire spécifique

---

📊 Tableau de Référence Rapide

Méthode	Description	Cas d'Utilisation
postFormsData()	Soumettre de nouvelles données de formulaire	L'utilisateur soumet un formulaire de contact
getFormsData()	Obtenir toutes les soumissions (paginated)	Tableau de bord admin montrant tous les formulaires
getFormsDataByMarker()	Obtenir les soumissions pour un formulaire spécifique	Voir toutes les soumissions du formulaire de contact

❓ Questions Fréquemment Posées (FAQ)

Comment soumettre un formulaire ?

Vous avez besoin de trois choses :

1. Configuration du formulaire à partir de Forms.getFormByMarker()
2. Données d'entrée de l'utilisateur
3. Appeler FormData.postFormsData()

---

Puis-je mettre à jour les données de formulaire soumises ?

Pas directement. Les soumissions de formulaires sont généralement immuables pour maintenir l'intégrité des données.

Solutions de contournement :

• Soumettre une nouvelle version avec des données mises à jour
• Utiliser le champ status pour marquer les anciennes soumissions comme obsolètes
• Implémenter une logique de mise à jour personnalisée dans votre backend

---

Comment gérer les téléchargements de fichiers dans les formulaires ?

Téléchargez les fichiers séparément en utilisant le module FileUploading, puis incluez les URL des fichiers dans les données du formulaire :

---

Comment filtrer les soumissions par date ?

Récupérez toutes les soumissions et filtrez côté client

---

Puis-je rechercher des soumissions par valeur de champ ?

Oui, récupérez les soumissions et recherchez côté client

---

Comment paginer à travers toutes les soumissions ?

Utilisez offset et limit

---

Quelle est la différence entre getFormsData() et getFormsDataByMarker() ?

Méthode	Ce qu'elle retourne	Quand l'utiliser
getFormsData()	Toutes les soumissions de tous les formulaires	Tableau de bord admin montrant tout
getFormsDataByMarker()	Soumissions pour un formulaire spécifique	Voir uniquement les soumissions du formulaire de contact

---

Comment gérer les erreurs de validation ?

Utilisez try/catch et vérifiez les messages d'erreur

---

💡 Notes Importantes

⚠️ Configuration de Formulaire Requise

Vous ne pouvez pas soumettre de formulaires sans configuration :

• formModuleConfigId et moduleEntityIdentifier sont requis
• Obtenez-les à partir de Forms.getFormByMarker() avant de soumettre
• Stockez-les dans votre application pour éviter des appels API répétés

---

🔒 Considérations de Sécurité

Ne jamais exposer de données sensibles :

• Ne soumettez pas de mots de passe en texte clair
• Validez l'entrée à la fois côté client et serveur
• Nettoyez l'entrée de l'utilisateur avant d'afficher

---

📦 Ensembles de Données Importants

La pagination est importante :

• Ne récupérez pas des milliers de soumissions à la fois
• Utilisez limit et offset pour la pagination
• Envisagez de mettre en cache les données fréquemment consultées

---

🔄 Lecture Seule Après Soumission

Les données de formulaire sont immuables :

• Impossible de mettre à jour les soumissions via SDK
• Soumettez une nouvelle version si des modifications sont nécessaires
• Utilisez le champ status pour suivre l'état de la soumission

---

🎓 Meilleures Pratiques

• Mettre en cache la configuration du formulaire - Évitez de récupérer à chaque soumission
• Valider avant de soumettre - Vérifiez les champs requis côté client
• Utiliser la pagination - Récupérez les soumissions par lots
• Gérer les erreurs avec grâce - Utilisez toujours try/catch
• Utiliser des marqueurs de manière cohérente - Référez-vous aux formulaires par marqueur, pas par ID
• Suivre le statut de soumission - Utilisez le champ de statut pour organiser les soumissions
• Exporter les données régulièrement - Sauvegarder les soumissions au format CSV/base de données
• Surveiller les nouvelles soumissions - Implémentez le polling ou les webhooks

---

Définition du module FormData

const { FormData } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Paramètres du formulaire :

1. Obtenez le formulaire par marqueur en utilisant Forms.getFormByMarker('your-form-marker').
2. Utilisez le champ moduleFormConfigs du formulaire récupéré pour la configuration utilisée lors de la soumission des données du formulaire.
3. Créez le corps en utilisant moduleFormConfig et postez les données du formulaire.

const formModuleConfigId = moduleFormConfigs[0].id;
const moduleEntityIdentifier = moduleFormConfigs[0].entityIdentifiers[0].id;
const body = {
  "formIdentifier": "your-form-marker",
  "formModuleConfigId": formModuleConfigId,
  "moduleEntityIdentifier": moduleEntityIdentifier,
  "replayTo": null,
  "status": "sent",
  "formData": [...]
};
const response = await FormData.postFormsData(body);

---

🔗 Documentation Connexe

• Module Formulaires - Créer et gérer des structures de formulaires
• Module FileUploading - Gérer les téléchargements de fichiers dans les formulaires
• Module Événements - Configurer des notifications basées sur des événements
• Module Utilisateurs - Gérer les utilisateurs qui soumettent des formulaires

---