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 devez consulter des réponses, générer des rapports ou 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 :

User fills contact form
↓
postFormsData() → Saved in OneEntry
↓
getFormsDataByMarker() → OneEntry returns data
↓
Admin views submissions 

Ce que vous pouvez faire :

• 📤 Soumettre des formulaires - Envoyer des données remplies par l'utilisateur à OneEntry
• 📥 Voir les soumissions - Obtenir toutes les réponses des 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 des analyses
• 📧 Gérer les réponses - Suivre les soumissions de formulaires en un seul endroit

Scénarios d'exemple :

Scénario	Que se passe-t-il ?
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', // Form marker
    formModuleConfigId: 9,          // Module config ID
    moduleEntityIdentifier: 'blog', // Module entity identifier
    replayTo: null,                 // Email address to reply to
    status: 'sent',                 // Submission status
    formData: [                     // Form fields
      {
        marker: 'string',           // Field marker
        type: 'string',             // Field type
        value: 'Test',              // Field value
      },
    ]
  };

Cycle de Vie des Données de Formulaire

1. User fills form in browser
   ↓
2. Frontend validates input
   ↓
3. postFormsData() sends to OneEntry
   ↓
4. OneEntry validates & stores form data submission
   ↓
5. Notifications sent (email, webhook)
   ↓
6. Admin retrieves with getFormsDataByMarker()
   ↓
7. Review, export, or respond

Cas d'Utilisation Courants

Cas d'Utilisation	Description	Exemple
Formulaires de Contact	Les clients posent 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 bulletins d'information	Suivre les participants/abonnés
Candidatures	Collecter des CV et des lettres de motivation	Les RH examinent les candidats
Formulaires de Retour d'Information	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 de texte unique pour le 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 :

// Fetch form
const form = await Forms.getFormByMarker('contact_form');

// Extract required IDs
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// Now you can submit

Pourquoi est-ce nécessaire ? OneEntry doit 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", // Field identifier
    type: "text"          // Field type
    value: "user_input",  // User's input
  }
]

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'administrateur	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
getFormsDataByMarker()	Obtenir des 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 frontend

---

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

Utilisez simplement File ou FileList avec FormData.postFormsData() ou Téléchargez des 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 ?

Utilisez les paramètres du corps dateFrom et dateTo.

---

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.

---

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 nécessaires
• 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 les entrées à la fois côté client et serveur
• Assainissez les entrées utilisateur avant de les 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 le 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érencez les 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 - Sauvegardez 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 de Formulaires - Créer et gérer des structures de formulaires
• Module de Téléchargement de Fichiers - Gérer les téléchargements de fichiers dans les formulaires
• Module d'Événements - Configurer des notifications basées sur des événements
• Module d'Utilisateurs - Gérer les utilisateurs qui soumettent des formulaires

---